344 lines
16 KiB
Plaintext
344 lines
16 KiB
Plaintext
README.rpm-dist
|
|
-----------------------------------------------------------------------------
|
|
Version 5.0, for the PostgreSQL 7.3-1PGDG RPMset.
|
|
Lamar Owen <lamar.owen@wgcr.org>
|
|
-----------------------------------------------------------------------------
|
|
|
|
Contents:
|
|
0.) Quick -i note.
|
|
1.) Introduction, QuickStart, and credits
|
|
2.) PostgreSQL RPM packages and rationale
|
|
3.) Starting multiple postmasters
|
|
4.) Regression Testing
|
|
5.) Starting postmaster automatically on startup
|
|
6.) Grand Unified Configuration(GUC) File.
|
|
7.) Rebuilding the source RPM.
|
|
8.) Contrib files.
|
|
9.) Logging set up
|
|
10.) Further Information Resource
|
|
|
|
QUICK '-i' NOTE
|
|
-----------------------------------------------------------------------------
|
|
The postmaster '-i' option is NOT used by default in the initscript shipped
|
|
with these RPMs. Please do NOT modify the initscript to add the '-i' back
|
|
in -- it will get overwritten on the next package upgrade. Rather, see the
|
|
section below on the Grand Unified Configuration file, which includes the
|
|
recommended way to get '-i' functionality back.
|
|
|
|
INTRODUCTION
|
|
-----------------------------------------------------------------------------
|
|
This document exists to explain the layout of the RPM's for PostgreSQL,to
|
|
describe various RPM specifics, and to document special features found
|
|
in the RPMset.
|
|
|
|
This document is written to be applicable to version 7.3 of PostgreSQL,
|
|
which is the current version of the RPM's as of this writing. More to the
|
|
point, versions prior to 7.3 are not documented here.
|
|
|
|
Official PostgreSQL Global Development Group RPM's have from version 7.1.2
|
|
on carried a 'PGDG' after the release number. Other RPMset's as distributed
|
|
with Linux distributions may have a different release number and initials.
|
|
|
|
It is preferable for the distribution-specific set to be the one used, as
|
|
the PGDG set is intentionally generic. So, if your distro has a set of RPMs,
|
|
use them in preference. If you want to stay up-to-date on the PostgreSQL
|
|
core itself, use the PGDG generic set -- but understand that it is a
|
|
GENERIC set.
|
|
|
|
These RPMs are designed to be LSB-compliant -- if you find this not to be the
|
|
case, please let me know by way of the pgsql-ports@postgresql.org mailing
|
|
list.
|
|
|
|
These RPMs no longer support any sort of upgrading process other than that
|
|
documented in the regular documentation. That is, you must dump, upgrade,
|
|
initdb, and restore your data. The 7.2 to 7.3 migration can be quite
|
|
difficult, even to the point of requiring hand-editing of the dumpfile.
|
|
|
|
Thus, the 7.3 postgresql-server RPM specifically conflicts with prior
|
|
versions. The old server subpackage must be removed first, the new package
|
|
installed, and the data restored from dump.
|
|
|
|
A new section on running multiple postmasters has replaced the old upgrade
|
|
instructions.
|
|
|
|
QUICKSTART
|
|
-----------------------------------------------------------------------------
|
|
For a fresh installation on a recent Red Hat or similar system, a simple
|
|
service postgresql start
|
|
as root will prepare a new database (initdb), and start a postmaster that
|
|
will listen on Unix socket 5432 only. Edit /var/lib/pgsql/data/postgresql.conf
|
|
to enable TCP/IP -- see the section on '-i.'
|
|
|
|
The file /var/lib/pgsql/.bash_profile is now packaged to help with the
|
|
setting of environment variables. You may edit this file, and it won't be
|
|
overwritten during an upgrade. However, enhancements and bugfixes may be added
|
|
to this file, so be sure to check .bash_profile.rpmnew after upgrading.
|
|
|
|
The user 'postgres' is created during installation of the server subpackage.
|
|
This user by default is UID and GID 26. The user has the default shell set to
|
|
bash, and the home directory set to /var/lib/pgsql. This user also has no
|
|
default password -- in order to be able to su to from a non-root account
|
|
or login as 'postgres' you will need to set a password using passwd.
|
|
|
|
CREDITS
|
|
-----------------------------------------------------------------------------
|
|
Thomas Lockhart
|
|
Uncle George
|
|
Ryan Kirkpatrick
|
|
Trond Eivind Glomsrd
|
|
Mark Knox
|
|
Mike Mascari
|
|
Nicolas Huillard
|
|
Karl DeBisschop
|
|
Roger Luethi
|
|
Jeff Johnson
|
|
Reinhard Max
|
|
Peter Eisentraut
|
|
Joe Conway
|
|
|
|
POSTGRESQL RPM PACKAGES AND RATIONALE.
|
|
-----------------------------------------------------------------------------
|
|
The RPMset is packaged in the following subpackages:
|
|
|
|
postgresql: Some clients and libraries, and documentation
|
|
postgresql-server: Server executables and data files
|
|
postgresql-devel: Client-side development libraries
|
|
postgresql-tcl: TCL/TK client libraries and docs
|
|
postgresql-python: The PygreSQL client library
|
|
postgresql-jdbc: JAR of the JDBC client
|
|
postgresql-test: The regression tests and associated files.
|
|
postgresql-tcl: Tcl client and PL ONLY.
|
|
postgresql-libs: client shared libraries.
|
|
postgresql-docs: extra documentation,such as the SGML doc sources.
|
|
postgresql-contrib: The contrib source tree, as well as selected binaries.
|
|
postgresql-pl: PL/Perl (if possible on this dist), PL/Python, and PL/Tcl
|
|
|
|
Note that there is no postgresql-perl, postgresql-odbc, postgresql-tk, or
|
|
postgresql-plperl package any longer. This is due to these portions being
|
|
removed from the PostgreSQL source tarball. The TK client package 'pgaccess'
|
|
was the core of the -tk subpackage -- so the pgtksh client was rolled back
|
|
into the -tcl package.
|
|
|
|
PostgreSQL is split up into multiple packages so that users can 'pick and
|
|
choose' what pieces are needed, and what dependencies are required.
|
|
|
|
RPM FILE LOCATIONS.
|
|
-----------------------------------------------------------------------------
|
|
In compliance with the Linux FHS, the PostgreSQL RPM's install files in a manner
|
|
not consistent with most of the PostgreSQL documentation. According to the
|
|
standard PostgreSQL documentation, PostgreSQL is installed under the directory
|
|
/usr/local/pgsql, with executables, source, and data existing in various
|
|
subdirectories.
|
|
|
|
Different distributions have different ideas of some of these file locations.
|
|
In particular, the documentation directory can be /usr/doc, /usr/doc/packages,
|
|
/usr/share/doc, /usr/share/doc/packages, or some other similar path. The
|
|
RedHat 7 locations are listed below. On SuSE <7.1, substitute 'postgres' for
|
|
'postgresql' below, and 'pg_tk' for 'postgresql-tk' below.
|
|
|
|
However, the RPM's install the files like this:
|
|
Executables: /usr/bin
|
|
Libaries: /usr/lib
|
|
Documentation: /usr/share/doc/postgresql-x.y.z
|
|
Contrib: /usr/share/doc/postgresql-x.y.z/contrib
|
|
Source: not installed
|
|
Data: /var/lib/pgsql/data
|
|
Backup area: /var/lib/pgsql/backup
|
|
Templates: /usr/share/pgsql
|
|
Procedural Languages: /usr/lib/pgsql
|
|
Development Headers: /usr/include/pgsql
|
|
Other shared data: /usr/share/pgsql
|
|
Regression tests: /usr/lib/pgsql/test/regress (in the -test package)
|
|
Documentation SGML: /usr/share/doc/postgresql-docs-x.y.z
|
|
|
|
The above list references the Red Hat 7.x structure. These locations may
|
|
change for other distributions. Use of 'rpm -ql' for each package is
|
|
recommended as the 'Official' location source.
|
|
|
|
While it may seem gratuitous to place these files in different locations, the
|
|
FHS requires it -- distributions should not ever touch /usr/local. It may
|
|
also seem like more work to keep track of where everything is -- but, that's
|
|
the beauty of RPM -- you don't have to keep track of the files, RPM does it
|
|
for you.
|
|
|
|
These RPM's are meant to be LSB-compliant. If you find errors in them that
|
|
cause thembe be non-compliant, please let me know.
|
|
|
|
MULTIPLE POSTMASTERS
|
|
-------------------------------------------------------------------------------
|
|
The postgresql-server RPM contains an 'initscript' that is used to start the
|
|
postmaster. The current version of this script has logic to be able to start
|
|
multiple postmasters, with different data areas, listening on different ports,
|
|
etc. To use this functionality requires root access.
|
|
|
|
As an example, let us create a secondary postmaster called, creatively enough,
|
|
'secondary'. Here are the steps:
|
|
1.) create a hard link in /etc/rc.d/init.d (or equivalent location)
|
|
to postgresql named 'secondary' : ln postgresql secondary Pick
|
|
a name not already used in /etc/rc.d/init.d!
|
|
2.) create a file in /etc/sysconfig/pgsql named secondary. This file is
|
|
a shell script -- typically you would define PGDATA, PGPORT, and PGOPTS
|
|
here. Since $PGDATA/postgresql.conf will override many of these
|
|
settings, except PGDATA, you might be surprised on startup.
|
|
3.) create the target PGDATA.
|
|
4.) Initdb the targe PGDATA as documented in the main documentation.
|
|
Automatic initdb may or may not work for you, so a manual one is
|
|
preferred. This must be done as user 'postgres'
|
|
5.) Edit postgresql.conf to change the port, address, tcpip settings, etc.
|
|
6.) Start the postmaster with 'service secondary start'.
|
|
|
|
Note that there may be problems with the standard symlink -- consider this
|
|
support experimental at this point in time.
|
|
|
|
REGRESSION TESTING
|
|
-------------------------------------------------------------------------------
|
|
One of the features of the newer RPM sets is the capability to perform the
|
|
regression tests. These tests stress your database installation and produce
|
|
results that give you assurances that the installation is complete, and that
|
|
your database machine is up to the task.
|
|
|
|
To run the regression tests under the RPM installation, make sure that
|
|
postmaster has been started (if not, su to root and execute the
|
|
'/etc/rc.d/init.d/postgresql start' init script), cd to
|
|
/usr/lib/pgsql/test/regress, su to postgres, and execute the command line:
|
|
time ./pg_regress.sh --schedule=parallel_schedule
|
|
This command line will start the regression tests and will both show the
|
|
results to the screen and store the results in the file regress.out.
|
|
It will also give you a crude benchmark of how fast your machine performs.
|
|
|
|
If tests fail, please see the file regression.diffs in that directory. If
|
|
you need help interpreting that file, contact the pgsql-ports list on
|
|
postgresql.org.
|
|
|
|
There are some tests that will almost always fail with RedHat Linux 5.x and 6.x
|
|
installations. The geometry, float8, and on occassion the random test will
|
|
fail. These failures are normal for RedHat 5.2 and 6.1. For RedHat 6.1 with
|
|
certain i18n settings, there will be other tests fail.
|
|
|
|
For 7.1RC1, all 76 tests passed on RedHat 6.2 and RedHat 7.0. This
|
|
was accomplished by fiddling with the locale settings. In version 7.1.2 this
|
|
capability was removed -- you need to set your locale to 'C' before executing
|
|
the first postmaster startup, or many more regression tests will fail.
|
|
|
|
For interpretation of the regression tests, see the PostgreSQL documentation.
|
|
|
|
STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
|
|
-------------------------------------------------------------------------------
|
|
RedHat Linux uses the System V Init package. A startup script for PostgreSQL
|
|
is provided in the server package, as /etc/rc.d/init.d/postgresql. To start
|
|
the postmaster, with sanity checking, as root, run
|
|
service postgresql start
|
|
to shut postmaster down,
|
|
service postgresql stop
|
|
There are other parameters to this script -- execute 'service postgresql' for a
|
|
listing.
|
|
|
|
To get this script to run at system startup or any time the system switches into
|
|
runlevels 3, 4, or 5, run:
|
|
chkconfig --add postgresql
|
|
chkconfig --level 345 postgresql on
|
|
and the proper symlinks will be created. Check the chkconfig man page for more
|
|
information. Note that this is manual -- while the startup script can include
|
|
tags to allow chkconfig to automatically perform the symlinking, this is not
|
|
done at this time.
|
|
|
|
SuSE has maintained their own RPMset for some time -- their documentation
|
|
supercedes any found in this file.
|
|
|
|
GRAND UNIFIED CONFIGURATION (GUC) FILE
|
|
-------------------------------------------------------------------------------
|
|
The PostgreSQL server has many tunable parameters -- the file
|
|
/var/lib/pgsql/data/postgresql.conf is the master configuration file for the
|
|
whole system.
|
|
|
|
The RPM ships with the default file -- you will need to tune the
|
|
parameters for your installation. In particular, you might want to allow
|
|
TCP/IP socket connections -- in order to allow these, you will need to edit
|
|
the postgresql.conf file. The line in question contains the string
|
|
'tcpip_socket' --want to both uncomment the line and set the parameter to true
|
|
in order to get the TCP/IP socket to open.
|
|
|
|
This is the same behavior the -i command line switch provides. It is
|
|
preferable to use the postgresql.conf file, however, as future versions
|
|
of the RPMset will allow multiple postmaster instances -- and that will only
|
|
be possible thanks to the decoupling of settings out to each datadir.
|
|
|
|
REBUILDING FROM SOURCE RPM
|
|
-------------------------------------------------------------------------------
|
|
If your distribution is not supported by the binary RPM's from PostgreSQL.org,
|
|
you will need to rebuild from the source RPM. Download the .src.rpm for this
|
|
release. You will need to be root to rebuild, unless you have already set up
|
|
a non-root build environment.
|
|
|
|
Install the source RPM with rpm -i, then CD to the rpm building area (on RedHat
|
|
this is /usr/src/redhat by default). You will have to have a full development
|
|
environment to rebuild the full RPM set.
|
|
|
|
This release of the RPMset includes the ability to conditionally build
|
|
sets of packages. The parameters, their defaults, and the meanings are:
|
|
|
|
build6x undef #don't build for Red Hat 6.x. Define it to cause
|
|
# other options to be tailored to 6.x.
|
|
beta 0 #build with cassert and do not strip the binaries
|
|
perl 1 #build the postgresql-perl package.
|
|
tcl 1 #build the postgresql-tcl package.
|
|
tkpkg 1 #build the postgresql-tk package.
|
|
jdbc 1 #build the postgresql-jdbc package.
|
|
pls 1 #build the postgresql-pl package.
|
|
test 1 #build the postgresql-test package.
|
|
python 1 #build the postgresql-python package.
|
|
pltcl 1 #build the pltcl portion of the postgresql-pl package.
|
|
plperl 1 #build the plperl portion of the postgresql-pl package.
|
|
ssl 1 #use OpenSSL support.
|
|
kerberos 1 #use Kerberos 5 support.
|
|
nls 1 #build with national language support.
|
|
pam 1 #build with PAM support.
|
|
|
|
To use these defines, invoke a rebuild like this:
|
|
rpm --rebuild --define 'perl 0' --define 'tcl 0' --define 'tkpkg 0'\
|
|
--define 'test 0' --define 'newintarray 1' --define 'kerberos 0' \
|
|
postgresql-7.1.3-1PGDG.src.rpm
|
|
This line would disable the perl, tcl, tk, and test subpackages, enable the
|
|
newer intarray code, and disable kerberos support.
|
|
|
|
More of these conditionals will be added in the future.
|
|
|
|
CONTRIB FILES
|
|
-------------------------------------------------------------------------------
|
|
The contents of the contrib tree are packaged into the -contrib subpackage
|
|
and are processed with make and make install. There is documentation in
|
|
/usr/share/doc/postgresql-contrib-VERSION for these modules. Most of the
|
|
modules are in /usr/lib/pgsql for loadable modules, and binaries are in
|
|
/usr/bin. In the future these files may be split out, depending upon function
|
|
and dependencies.
|
|
|
|
LOGGING SET UP
|
|
-------------------------------------------------------------------------------
|
|
To get rollable syslog set up, see the documentation for the file
|
|
postgresql.conf, by default in the directory /var/lib/pgsql/data, as relates to
|
|
the syslog options. Then, add a line to /etc/syslog.conf, using the man page
|
|
for syslog.conf as a source. Example:
|
|
If postgresql.conf has the following lines for the syslog settings:
|
|
syslog = 1 # range 0-2
|
|
syslog_facility = 'LOCAL0'
|
|
syslog_ident = 'postgres'
|
|
|
|
Then you need to add the line to /etc/syslog.conf:
|
|
local0.* /var/log/postgresql
|
|
|
|
Then set up an entry in /etc/logrotate.d to roll postgresql the way you want it
|
|
rolled.
|
|
|
|
MORE INFORMATION
|
|
-------------------------------------------------------------------------------
|
|
You can get more information at http://www.postgresql.org
|
|
|
|
Please help make this packaging better -- let me know if you find problems, or
|
|
better ways of doing things. You can reach me by e-mail at
|
|
pgsql-ports@postgresql.org -- please include an [RPM] string in the subject, as
|
|
I use automatic mail folder processing to put mail in the right place.
|
|
|
|
SuSE information is available at SuSE's website and information contacts.
|
|
-----------------------------------------------------------------------------
|
|
|