README.rpm-dist ----------------------------------------------------------------------------- Version 4.1, for the PostgreSQL 7.2.1-2PGDG RPMset. Lamar Owen DISCLAIMER: the following information is provided in the hope that it helps people install and use PostgreSQL. It is being provided without warranty of any kind, so, use at your own risk. ----------------------------------------------------------------------------- Contents: 0.) Quick -i note. 1.) Introduction, QuickStart, and credits 2.) PostgreSQL RPM packages and rationale 3.) Upgrading. (Deprecated. Will be removed in a future README) 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 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.2.1 of PostgreSQL, which is the current version of the RPM's as of this writing. Official PostgreSQL Global Development Group RPM's 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. In particular, SuSE and RedHat users that use late-model distributions should definitely use their RPMs. Trond and Reinhard do a good job keeping them up to date. The Polish(ed) Linux Distribution also does an excellent job with the PLD RPM version. 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 RedHat and TurboLinux) 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 Mark Knox Mike Mascari Nicolas Huillard Karl DeBisschop Roger Luethi Jeff Johnson Reinhard Max Peter Eisentraut A big THANK YOU to Trond, particularly. He has poured an amazing amount of work into this package, particularly in cleaning up my errors, as well as getting the contrib package to actually be useful. POSTGRESQL RPM PACKAGES AND RATIONALE. ----------------------------------------------------------------------------- [This section has been edited. See prior versions for older history] PostgreSQL is a large, multifaceted program, with many clients and options that all users will not need. So, several subpackages are built. Here is the list of the current (7.2.1) packages: postgresql: Some clients and libraries, and documentation postgresql-server: Server executables and data files postgresql-devel: Client-side development libraries 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. postgresql-tk: Tk client and pgaccess. 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. The postgresql-libs package is required for all installations. Otherwise, a mix and match installation may be made. The devel package is required to do any compilation of a program that uses either the client libs or the server (SPI) interface. RPM FILE LOCATIONS. ----------------------------------------------------------------------------- In compliance with the LSB, the PostgreSQL RPM's install files in a manner not consistent with much 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 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 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. UPGRADING. ----------------------------------------------------------------------------- WARNING: This information is deprecated. Make sure to fully back up your database files BEFORE upgrading the RPM. Unfortunately, even then you may have problems -- so be ready to hand-edit dump files. A pg_upgrade utility is found in the contrib tree -- but it is not really production quality code. If this lack of easy upgrades bothers you, please let the developer list (pgsql-hackers@postgresql.org) know about it -- maybe seamless upgrades can be made a higher prioriy if enough users complain. Use the following information at your own risk. 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. I cannot overemphasize this precaution. 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 prior 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