From c9851aba23877372fb8a04dce1aa123d53351f0d Mon Sep 17 00:00:00 2001 From: cvsdist Date: Thu, 9 Sep 2004 10:37:06 +0000 Subject: auto-import postgresql-7.1.3-1 from postgresql-7.1.3-1.src.rpm --- README.rpm-dist | 437 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 437 insertions(+) create mode 100644 README.rpm-dist diff --git a/README.rpm-dist b/README.rpm-dist new file mode 100644 index 0000000..507f74b --- /dev/null +++ b/README.rpm-dist @@ -0,0 +1,437 @@ +README.rpm-dist +----------------------------------------------------------------------------- +Version 3.6, for PostgreSQL 7.1.3 +Lamar Owen +----------------------------------------------------------------------------- + +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 RedHat 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 +Mark Knox +Mike Mascari +Nicolas Huillard +Karl DeBisschop +Roger Luethi +Jeff Johnson +Reinhard Max + + +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, 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: 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 <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. + +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 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