README.rpm-dist
-----------------------------------------------------------------------------
Version 3.7, for PostgreSQL 7.1.3
Lamar Owen <lamar.owen@wgcr.org>
Trond Eivind Glomsrød <teg@redhat.com>
-----------------------------------------------------------------------------
Contents:
0.) Quickie -i note.
1.) Introduction, QuickStart, and credits
2.) PostgreSQL RPM packages and rationale
3.) Upgrading from an older version of PostgreSQL without losing data.
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
QUICKIE '-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
explain how to migrate from an older version, and to explain WHY it can be
so difficult to upgrade PostgreSQL.
This document is written to be applicable to version 7.1.2 of PostgreSQL,
which is the current version of the RPM's as of this writing.
Official PostgreSQL Global Development Group RPM's will from version 7.1.2
on carry 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.
QUICKSTART
-----------------------------------------------------------------------------
If this is an upgrade, please go to section 3, UPGRADING.
If this is a fresh installation, simply start the postmaster using:
/etc/rc.d/init.d/postgresql start (on Red Hat Linux and TurboLinux)
On SuSE, please see the file 'README.linux' in this directory.
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 Glomsrød <teg@redhat.com>
Mark Knox
Mike Mascari
Nicolas Huillard
Karl DeBisschop
Roger Luethi
Jeff Johnson <jbj@redhat.com>
Reinhard Max
POSTGRESQL RPM PACKAGES AND RATIONALE.
-----------------------------------------------------------------------------
On Red Hat Linux, prior to version 6.5, PostgreSQL was packaged in RPM form in
three (or four) packages:
postgresql: The server and documentation
postgresql-clients: The client libraries, the cli, and the tcl interface
postgresql-devel: Development libraries (for the client-side)
postgresql-data: A sample database -- not shipped with the 6.4 RPMS.
However, it was decided that a different split would be more appropriate for
users. The 7.0 splitup allows more flexibility in installation, as well as
making the new clients into their own packages. The new packages are:
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 the pgaccess client
postgresql-perl: PERL client module
postgresql-python: The PygreSQL client library
postgresql-odbc: Linux ODBC client (not required to use ODBC from Win95)
postgresql-jdbc: JAR of the JDBC client
postgresql-test: The regression tests and associated files.
For version 7.0.x, another package is being shipped, and one package has been
trimmed:
postgresql-tk: Tk client and pgaccess.
postgresql-tcl: Tcl client and PL ONLY.
For version 7.1, more packages are being shipped:
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.
For SuSE Linux <= 7.0, the packages are named differently, but with the same
functionality. Here is a mapping:
SuSE: Red Hat Linux:
----- -----------------
postgres postgresql
pg_serv postgresql-server
pg_devel postgresql-devel
pg_tcl postgresql-tcl
pg_perl postgresql-perl
pg_pyth postgresql-python
pg_odbc postgresql-odbc
pg_jdbc postgresql-jdbc
pg_test postgresql-test
There are other changes to the SuSE packages to make them conform to the
SuSE packaging standards. SuSE Linux has been shipping their own packages.
While the repackaging will initially cause some confusion, it makes it
possible to set up a Red Hat Linux machine to be only a client -- the
server is no longer required. The clients were split out -- after
all, a person who needs the perl client may very well not need the tcl
client, etc. And, the regression tests were added to give some
confidence of the suitability of PostgreSQL, as well as the stability
of the server machine. Additionally, the regression tests can be used
to help find hardware errors.
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
Red Hat Linux 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
TK client docs: /usr/share/doc/postgresql-tk-x.y.z
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 Linux 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.
UPGRADING.
-----------------------------------------------------------------------------
CAUTION: While a semi-automatic upgrade process has been implemented, it is
STRONGLY recommended that a full dump of your database (using pg_dumpall) is
performed BEFORE upgrading the RPMs! If you have already done the upgrade
with the RPM, and want to return to your previous version to do the dump,
find the old RPM's and use 'rpm -U --oldpackage' to downgrade.
NOTE: moving your existing data from /var/lib/pgsql to /var/lib/pgsql/data is
not currently automatic -- you will need to do this yourself at this release!
This change occurred between 6.5.3 and 7.0, so upgrading from priot to 7.0 to
7.0 or later might be difficult. The rh-dump script is provided to ease this,
see below.
The single biggest problem with upgrading PostgreSQL RPM's has been the lack
of a reasonably automated upgrade process. PostgreSQL has the property of
the binary on-disk database format changing between major versions (like
between 6.3 and 6.4). However, a change from 6.5 to 6.5.3 does not change
the on-disk format.
This property (feature, misfeature, bug, whatever) has been a known
property of PostgreSQL since before it was called PostgreSQL -- it has
always been this way. However, the means by which an upgrade is
performed is not readily performed in a fully automated fashion, as a
"dump-initdb-restore" cycle has to be performed. This doesn't appear
to be too difficult -- however, dumping the old database requires the
old executables -- and, if you've already done an rpm -U postgresql*
(or upgraded from an older version of Red Hat Linux and didn't
specifically exclude the postgresql rpms), you no longer have the
older executables to dump your data. And your data is useless (until
you reinstall the old version, that is). All RPM's prior to late
releases of version 6.5. 1 have this upgrade issue.
The newest RPM's for PostgreSQL attempt to make your job in upgrading
a little easier. First, during the installation of the new RPM's, a
copy is made of all the executable files and libraries necessary to
make a backup of your data. Second, the initialization script in the
new postgresql-server package detects the version of any database
found -- if the version is old, then the startup of the new version is
aborted. However, if no database is found, a new one is made.
One thing must be remembered -- due to the restructuring of the
PostgreSQL RPM's, you will have to manually select the
postgresql-server package if you want the server -- it is not
installed by default in an upgrade. You can either select it during
the upgrade/install, or you can mount your Red Hat Linux CD and
install manually with rpm -i.
To facilitate upgrading, the postgresql-dump utility has been
provided. Look at the man page for postgresql-dump to see its usage.
All executables to restore the immediately prior version of the
PostgreSQL database are placed in the directory /usr/lib/pgsql/backup,
and are accessed by the postgresql-dump script. The directory
/usr/lib/pgsql/backup is owned by the postgres user -- you can use
this directory to hold dump files and preserve directories.
The basic sequence is:
(as user postgres):
postgresql-dump -t /var/lib/pgsql/backup/db.bak -p /var/lib/pgsql/backup/old -d
(you can abort the ASCII dump with 'Q', as it uses more) Then, (as user root):
***** NOTE ***** ***** NOTE *****
The above script is broken. Use "rh-pgdump.sh targetfile" instead, remove the
old databases (/var/lib/pgsql/base) (or safer - move them somewhere else first),
start the database and follow the insert procedure described below.
***** NOTE ***** ***** NOTE *****
service postgresql start
(which will automatically create a new database structure) And finally,
(as user postgres):
psql -e template1