diff options
Diffstat (limited to 'README.rpm-dist')
| -rw-r--r-- | README.rpm-dist | 257 |
1 files changed, 82 insertions, 175 deletions
diff --git a/README.rpm-dist b/README.rpm-dist index ecf543f..ce775d3 100644 --- a/README.rpm-dist +++ b/README.rpm-dist @@ -1,18 +1,14 @@ README.rpm-dist ----------------------------------------------------------------------------- -Version 4.1, for the PostgreSQL 7.2.1-2PGDG RPMset. +Version 5.0, for the PostgreSQL 7.3-1PGDG RPMset. Lamar Owen <lamar.owen@wgcr.org> - -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) + 3.) Starting multiple postmasters 4.) Regression Testing 5.) Starting postmaster automatically on startup 6.) Grand Unified Configuration(GUC) File. @@ -31,35 +27,47 @@ 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 exists to explain the layout of the RPM's 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 7.2.1 of PostgreSQL, -which is the current version of the RPM's as of this writing. +This document is written to be applicable to version 7.3 of PostgreSQL, +which is the current version of the RPM's as of this writing. More to the +point, versions prior to 7.3 are not documented here. -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. +Official PostgreSQL Global Development Group RPM's have from version 7.1.2 +on carried 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. +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. +These RPMs no longer support any sort of upgrading process other than that +documented in the regular documentation. That is, you must dump, upgrade, +initdb, and restore your data. The 7.2 to 7.3 migration can be quite +difficult, even to the point of requiring hand-editing of the dumpfile. + +Thus, the 7.3 postgresql-server RPM specifically conflicts with prior +versions. The old server subpackage must be removed first, the new package +installed, and the data restored from dump. + +A new section on running multiple postmasters has replaced the old upgrade +instructions. + 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) +For a fresh installation on a recent Red Hat or similar system, a simple +service postgresql start +as root will prepare a new database (initdb), and start a postmaster that +will listen on Unix socket 5432 only. Edit /var/lib/pgsql/data/postgresql.conf +to enable TCP/IP -- see the section on '-i.' 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 @@ -77,7 +85,7 @@ CREDITS Thomas Lockhart Uncle George Ryan Kirkpatrick -Trond Eivind Glomsrød +Trond Eivind Glomsrd Mark Knox Mike Mascari Nicolas Huillard @@ -86,42 +94,38 @@ 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. +Joe Conway 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: +The RPMset is packaged in the following subpackages: 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-tcl: TCL/TK client libraries and docs 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. +postgresql-pl: PL/Perl (if possible on this dist), PL/Python, and PL/Tcl + +Note that there is no postgresql-perl, postgresql-odbc, postgresql-tk, or +postgresql-plperl package any longer. This is due to these portions being +removed from the PostgreSQL source tarball. The TK client package 'pgaccess' +was the core of the -tk subpackage -- so the pgtksh client was rolled back +into the -tcl package. -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. +PostgreSQL is split up into multiple packages so that users can 'pick and +choose' what pieces are needed, and what dependencies are required. 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 +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. @@ -142,7 +146,6 @@ 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) @@ -161,123 +164,31 @@ 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 </var/lib/pgsql/backup/db.bak - -Once you are satisfied that the data has been restored properly, you may remove -the dump file (/var/lib/pgsql/backup/db.bak) and the preserve directory -(/var/lib/pgsql/backup/old). - -EXPLANATION OF STEPS: +MULTIPLE POSTMASTERS ------------------------------------------------------------------------------- -postgresql-dump: dumps the old database structure out, using the postmaster and -the backend saved during the rpm upgrade. This step MUST be done as user -postgres. - -/etc/rc.d/init.d/postgresql start: initializes the new database structure that -the data from your old version will be restored into, does some sanity -checking, and starts the postmaster. Due to the nature of some of the tasks, -this step must be done as root. - -psql -e: restores the old database into the new structure created by the -previous step. - -NOTE: -------------------------------------------------------------------------------- -If you have added tables, indices, or basically anything to the template1 -database which is the default administrative database this script will NOT -upgrade your database. As a matter of fact you will lose your data included -in the template1 database. Please look at www.postgresql.org for information -on upgrading the template1 database. This is a known bug in the PostgreSQL -pg_dump and pg_dumpall utilities. - -The above information is considered deprecated. The utilities it mentions -are also considered deprecated and will be removed from a future release of -the RPMset due to the difficulty involved with a dump-restore upgrade and the -hand-editing of dumpfiles that are sometimes necessary. +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 targe PGDATA as documented in the main documentation. + Automatic initdb may or may not work for you, so a manual one is + preferred. This must be done as user 'postgres' +5.) Edit postgresql.conf to change the port, address, tcpip settings, etc. +6.) Start the postmaster with 'service secondary start'. + +Note that there may be problems with the standard symlink -- consider this +support experimental at this point in time. REGRESSION TESTING ------------------------------------------------------------------------------- @@ -316,10 +227,10 @@ STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP RedHat Linux uses 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, with sanity checking, as root, run -/etc/rc.d/init.d/postgresql start +service postgresql start to shut postmaster down, -/etc/rc.d/init.d/postgresql stop -There are other parameters to this script -- /etc/rc.d/init.d/postgresql for a +service postgresql stop +There are other parameters 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 @@ -366,28 +277,22 @@ 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: -build6x undef #build for RHL 6.x. Define to 1 to build for 6.x, - # undefined otherwise. - #currently, this disables the kerberos, nls, and ssl - # builds, as well as correcting dependencies for 6.x +build6x undef #don't build for Red Hat 6.x. Define it to cause + # other options to be tailored to 6.x. beta 0 #build with cassert and do not strip the binaries perl 1 #build the postgresql-perl package. tcl 1 #build the postgresql-tcl package. tkpkg 1 #build the postgresql-tk package. -odbc 1 #build the postgresql-odbc package. jdbc 1 #build the postgresql-jdbc package. +pls 1 #build the postgresql-pl package. test 1 #build the postgresql-test package. python 1 #build the postgresql-python package. -pltcl 1 #build the postgresql-pltcl package. -forceplperl 0 #don't force a build of pl/perl over libperl.a -plperl 0 #don't build the postgresql-plperl package. +pltcl 1 #build the pltcl portion of the postgresql-pl package. +plperl 1 #build the plperl portion of the postgresql-pl package. ssl 1 #use OpenSSL support. kerberos 1 #use Kerberos 5 support. nls 1 #build with national language support. -enable_mb 1 #enable multibyte encodings. -pgaccess 1 #build the pgaccess client, part of postgresql-tk. -newintarray 0 #substitute a newer intarray contrib. -pam 1 #build --with-pam +pam 1 #build with PAM support. To use these defines, invoke a rebuild like this: rpm --rebuild --define 'perl 0' --define 'tcl 0' --define 'tkpkg 0'\ @@ -401,9 +306,11 @@ 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 compiled and placed into /usr/lib/pgsql/contrib with no further -processing. Please see each directory under contrib for details on how to -install and use. +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 for loadable modules, and binaries are in +/usr/bin. In the future these files may be split out, depending upon function +and dependencies. LOGGING SET UP ------------------------------------------------------------------------------- |