315 lines
15 KiB
Plaintext
315 lines
15 KiB
Plaintext
README.rpm-dist
|
|
-----------------------------------------------------------------------------
|
|
Version 9.0, for the PostgreSQL 9.0 RPM set.
|
|
Devrim Gündüz <devrim@gunduz.org>
|
|
-----------------------------------------------------------------------------
|
|
|
|
Contents:
|
|
1.) Introduction and QuickStart
|
|
2.) Upgrading an installation
|
|
3.) PostgreSQL RPM packages and rationale
|
|
4.) Starting multiple postmasters
|
|
5.) Regression Testing
|
|
6.) Starting postmaster automatically on startup
|
|
7.) Grand Unified Configuration(GUC) File
|
|
8.) Logging set up
|
|
9.) Rebuilding from the source RPM
|
|
10.) Contrib files
|
|
11.) Further Information Resource
|
|
|
|
INTRODUCTION
|
|
-----------------------------------------------------------------------------
|
|
This document exists to explain the layout of the RPMs 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 9.0 of PostgreSQL,
|
|
which is the current version of the RPMs as of this writing. More to the
|
|
point, versions prior to 9.0 are not documented here.
|
|
|
|
This document is intended for use only with the RPMs supplied in Red Hat
|
|
Enterprise Linux, CentOS and Fedora. Note that there are also "PGDG"
|
|
RPMs available directly from the upstream PostgreSQL project. Those are
|
|
slightly different.
|
|
|
|
QUICKSTART
|
|
-----------------------------------------------------------------------------
|
|
For a fresh installation, you will need to initialize the cluster first. Run:
|
|
|
|
service postgresql initdb
|
|
|
|
as root, and it will prepare a new database cluster for you. Then you will
|
|
need to start PostgreSQL. Again as root, run:
|
|
|
|
service postgresql start
|
|
|
|
This command will start a postmaster that willl listen on localhost and Unix
|
|
socket 5432 only. Edit /var/lib/pgsql/data/postgresql.conf and pg_hba.conf
|
|
if you want to allow remote access -- see the section on Grand Unified
|
|
Configuration.
|
|
|
|
The file /var/lib/pgsql/.bash_profile is 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. If you want to be able to su to it from a non-root account
|
|
or login as 'postgres' you will need to set a password using passwd.
|
|
|
|
UPGRADING AN INSTALLATION
|
|
-----------------------------------------------------------------------------
|
|
For a minor-version upgrade (such as 9.0.1 to 9.0.2), just install the
|
|
new RPMs; there's usually nothing more to it than that. Upgrading
|
|
across a major release of PostgreSQL (for example, from 8.3.x to 8.4.x)
|
|
requires more effort.
|
|
|
|
If you are upgrading across more than one major release of PostgreSQL
|
|
(for example, from 8.3.x to 9.0.x), you will need to follow the "traditional"
|
|
dump and reload process to bring your data into the new version. That is:
|
|
*before* upgrading, run pg_dumpall to extract all your data into a SQL file.
|
|
Shut down the old postmaster, upgrade to the new version RPMs, initdb,
|
|
and run the dump file through psql to restore your data.
|
|
|
|
In some major releases, the RPMs also support in-place upgrade from the
|
|
immediately previous major release. Currently, you can upgrade in-place
|
|
from 8.4.x to 9.0.x. This is much faster than a dump and reload.
|
|
To do an in-place upgrade:
|
|
* shut down the old postmaster
|
|
* optionally make a backup of /var/lib/pgsql/data/
|
|
* install the new version's RPMs (install all the ones you had before,
|
|
plus postgresql-upgrade)
|
|
* as root, run "service postgresql upgrade"
|
|
* update the configuration files /var/lib/pgsql/data/*.conf with any
|
|
customizations you had before (your old configuration files are in
|
|
/var/lib/pgsql/data-old/)
|
|
* as root, run "service postgresql start"
|
|
* postgresql-upgrade can be removed after the update is complete
|
|
|
|
NOTE: The in-place upgrade process is new and relatively poorly tested,
|
|
so if your data is critical it's a really good idea to make a tarball
|
|
backup of /var/lib/pgsql/data/ before running the upgrade. This will
|
|
let you get back to where you were in case of disaster.
|
|
|
|
POSTGRESQL RPM PACKAGES AND RATIONALE.
|
|
-----------------------------------------------------------------------------
|
|
PostgreSQL is split up into multiple packages so that users can 'pick and
|
|
choose' what pieces are needed, and what dependencies are required.
|
|
|
|
The RPMset is packaged in the following subpackages:
|
|
|
|
postgresql: Key client programs and documentation
|
|
postgresql-libs: Client shared libraries
|
|
postgresql-server: Server executables and data files
|
|
postgresql-devel: Development libraries and include files
|
|
postgresql-test: The regression tests and associated files
|
|
postgresql-upgrade: Support files for upgrading from previous major version
|
|
postgresql-docs: Extra documentation, such as the tutorial files
|
|
postgresql-contrib: The contrib source tree, as well as selected binaries
|
|
postgresql-plperl: PL/Perl procedural language
|
|
postgresql-plpython: PL/Python procedural language
|
|
postgresql-pltcl: PL/Tcl procedural language
|
|
|
|
You have to install postgresql and postgresql-libs to do anything.
|
|
postgresql-server is needed unless you only plan to use the clients to work
|
|
with a remote PostgreSQL server. The others are optional.
|
|
|
|
Note that there are no postgresql-perl, postgresql-jdbc, postgresql-odbc,
|
|
postgresql-python, postgresql-tcl, or postgresql-tk subpackages any longer.
|
|
Those programs have been split off into separate source distributions.
|
|
They are still available, but in some cases not under those RPM names.
|
|
|
|
RPM FILE LOCATIONS.
|
|
-----------------------------------------------------------------------------
|
|
To be in compliance with the Linux FHS, the PostgreSQL RPMs 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.
|
|
|
|
However, the Red Hat / CentOS / Fedora RPM's install the files like
|
|
this:
|
|
|
|
Executables: /usr/bin
|
|
Libraries: /usr/lib (or /usr/lib64)
|
|
Documentation: /usr/share/doc/postgresql-docs-x.y.z/html
|
|
Contrib documentation: /usr/share/doc/postgresql-contrib-x.y.z
|
|
Source: not installed
|
|
Data: /var/lib/pgsql/data
|
|
Backup area: /var/lib/pgsql/backups
|
|
Templates: /usr/share/pgsql
|
|
Procedural Languages: /usr/lib/pgsql or /usr/lib64/pgsql
|
|
Development Headers: /usr/include/pgsql
|
|
Other shared data: /usr/share/pgsql
|
|
Regression tests: /usr/lib/pgsql/test/regress (in the -test package)
|
|
or /usr/lib64/pgsql/test/regress
|
|
|
|
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 RPMs are designed to be LSB-compliant -- if you find this not to be the
|
|
case, please let us know by way of the pgsqlrpms-hackers@pgfoundry.org
|
|
mailing list.
|
|
|
|
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 target PGDATA with 'service secondary initdb'.
|
|
5.) Edit postgresql.conf to change the port, address, tcpip settings, etc.
|
|
6.) Start the postmaster with 'service secondary start'.
|
|
|
|
REGRESSION TESTING
|
|
-------------------------------------------------------------------------------
|
|
If you install the postgresql-test RPM then you can run the PostgreSQL
|
|
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 do "service postgresql
|
|
start"), cd to /usr/lib/pgsql/test/regress (or /usr/lib64/pgsql/test/regress),
|
|
su to postgres, and execute "make check".
|
|
This command will start the regression tests and will both show the
|
|
results to the screen and store the results in the file regress.out.
|
|
|
|
If any tests fail, see the file regression.diffs in that directory for details,
|
|
and read the "Regression Tests" section of the PostgreSQL documentation to
|
|
find out whether the differences are actually significant. If you need help
|
|
interpreting the results, contact the pgsql-general list at
|
|
postgresql.org.
|
|
|
|
After testing, say "make clean" to remove the files generated by the test
|
|
script.
|
|
|
|
STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
|
|
-------------------------------------------------------------------------------
|
|
Fedora / Red Hat / CentOS use 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 manually,
|
|
as root run
|
|
service postgresql start
|
|
To shut the postmaster down,
|
|
service postgresql stop
|
|
There are other possible commands 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. See 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.
|
|
|
|
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
|
|
nonlocal 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
|
|
'listen_addresses' -- you need to both uncomment the line and set the value
|
|
to '*' to get the postmaster to accept nonlocal connections. You'll also need
|
|
to adjust pg_hba.conf appropriately.
|
|
|
|
LOGGING SET UP
|
|
-------------------------------------------------------------------------------
|
|
By default, the postmaster's stderr log is directed into files placed in a
|
|
pg_log subdirectory of the data directory (ie, /var/lib/pgsql/data/pg_log).
|
|
The out-of-the-box configuration rotates among seven files, one for each
|
|
day of the week. You can adjust this by changing postgresql.conf settings.
|
|
|
|
REBUILDING FROM SOURCE RPM
|
|
-------------------------------------------------------------------------------
|
|
If your distribution is not supported by the binary RPMs 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 set up
|
|
a non-root build environment (which is the recommended method anyway).
|
|
|
|
Install the source RPM with rpm -i, then cd to the rpm building area
|
|
(which 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:
|
|
|
|
beta 0 #build with cassert and do not strip the binaries
|
|
python 1 #build the postgresql-python package.
|
|
tcl 1 #build the postgresql-tcl package.
|
|
test 1 #build the postgresql-test package.
|
|
plpython 1 #build the PL/Python procedural language package.
|
|
pltcl 1 #build the PL/Tcl procedural language package.
|
|
plperl 1 #build the PL/Perl procedural language package.
|
|
ssl 1 #use OpenSSL support.
|
|
kerberos 1 #use Kerberos 5 support.
|
|
nls 1 #build with national language support.
|
|
ldap 1 #build with LDAP support.
|
|
pam 1 #build with PAM support.
|
|
runselftest 1 #do "make check" during the build.
|
|
sdt 1 #build with SystemTap support.
|
|
xml 1 #build with XML support
|
|
pgfts 1 #build with --enable-thread-safety
|
|
uuid 1 #build contrib/uuid-ossp
|
|
|
|
To use these defines, invoke a rebuild like this:
|
|
rpmbuild --rebuild --define 'python 0' --define 'tcl 0' \
|
|
--define 'test 0' --define 'runselftest 0' --define 'kerberos 0' \
|
|
postgresql-9.0.2-1.src.rpm
|
|
This line would disable the python, tcl, and test subpackages, disable the
|
|
regression test run during build, and disable kerberos support.
|
|
|
|
You might need to disable runselftest if there is an installed version of
|
|
PostgreSQL that is a different major version from what you are trying to
|
|
build. The self test tends to pick up the installed libpq.so shared library
|
|
in place of the one being built :-(, so if that isn't compatible the test will
|
|
fail. Also, you can't use runselftest when doing the build as root.
|
|
|
|
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 (or /usr/lib64/pgsql) for loadable
|
|
modules, and binaries are in /usr/bin. In the future these files may be
|
|
split out, depending upon function and dependencies.
|
|
|
|
MORE INFORMATION
|
|
-------------------------------------------------------------------------------
|
|
You can get more information at http://www.postgresql.org and
|
|
http://yum.pgsqlrpms.org
|
|
|
|
Please help make this packaging better -- let us know if you find problems, or
|
|
better ways of doing things. You can reach us by e-mail at
|
|
pgsqlrpms-hackers@pgfoundry.org
|
|
-------------------------------------------------------------------------------
|