README.rpm ----------------------------------------------------------------------------- Version 3.0, for PostgreSQL 7.1 RC1 Lamar Owen Updated by teg@redhat.com for 7.0.2 and to use FHS compliant doc paths Updated to 7.0.3 and to reflect more of a cross-distribution slant. Updated to 7.1RC1 ----------------------------------------------------------------------------- Contents: 0.) Precautionary Statement for RPM packaging 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.) Further Information Resource PRECAUTIONS FOR RELEASE CANDIDATE RPMS. ----------------------------------------------------------------------------- This RPM package of 7.1RC1 is being made available for testing purposes only. This packaging is likely to change -- in particular, there will be at least one more package (the contrib tree) added to the set before final release. 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 RC1 of PostgreSQL, which is the current version of the RPM's as of this writing. These are Release Candidate RPM's -- things can and will change before final release. 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 RedHat and TurboLinux) On SuSE, please see the file 'README.linux' in this directory. CREDITS ----------------------------------------------------------------------------- Thomas Lockhart Uncle George Ryan Kirkpatrick Trond Eivind Glomsrød Mark Knox Mike Mascari Nicolas Huillard Karl DeBisschop Roger Luethi Jeff Johnson POSTGRESQL RPM PACKAGES AND RATIONALE. ----------------------------------------------------------------------------- On RedHat 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, one more package is being shipped: postgresql-libs: client shared libraries. For SuSE Linux <= 7.0, the packages are named differently, but with the same functionality. Here is a mapping: SuSE: RedHat: ----- ----------------- 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 RedHat 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 RedHat 7 locations are listed below. On SuSE, 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 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. ----------------------------------------------------------------------------- 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 RedHat 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 RedHat 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