RPMs for PostgreSQL7.1 available.

RPMs built for Red Hat 6.2, 7.0, and 7.1 on the i386 architecture, as
well asthe source RPM, are available for immediate download from
ftp.postgresql.org in the directory /pub/binary/v7.1/RPMS.

Please read the attached README.rpm-dist file for details.

Any questions, please e-mail the pgsql-ports list.

There are a couple of known issueswhich are being worked on forthe next
(-2) RPM release, which will be made as soon as the hardcopy docs are
available.

Bug reports dealing with the RPMs should be made to pgsql-ports.
--
Lamar Owen
WGCR Internet Radio
1 Peter 4:11README.rpm-dist

-----------------------------------------------------------------------------
Version 3.2, for PostgreSQL 7.1
Lamar Owen <lamar.owen@wgcr.org>

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.1

-----------------------------------------------------------------------------

Contents:
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.)     Further Information Resource

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 of PostgreSQL,
which is the current version of the RPM's as of this writing.

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
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

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 </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:

-------------------------------------------------------------------------------
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.

REGRESSION TESTING

-------------------------------------------------------------------------------
One of the features of the newer RPM sets is the capability to perform the
regression tests.  These tests stress your database installation and produce
results that give you assurances that the installation is complete, and that
your database machine is up to the task.

To run the regression tests under the RPM installation, make sure that
postmaster has been started (if not, su to root and execute the
'/etc/rc.d/init.d/postgresql start' init script), cd to
/usr/share/pgsql/test/regress, su to postgres, and execute the command line:
time ./pg_regress.sh --schedule=parallel_schedule
This command line will start the regression tests and will both show the
results to the screen and store the results in the file regress.out.
It will also give you a crude benchmark of how fast your machine performs.

If tests fail, please see the file regression.diffs in that directory.  If
you need help interpreting that file, contact the pgsql-ports list on
postgresql.org.

There are some tests that will almost always fail with RedHat Linux 5.x and
6.x
installations.  The geometry, float8, and on occassion the random test will
fail.  These failures are normal for RedHat 5.2 and 6.1.  For RedHat 6.1
with
certain i18n settings, there will be other tests fail.

New for 7.1RC1, all 76 tests should pass on RedHat 6.2 and RedHat 7.0.

For interpretation of the regression tests, see the PostgreSQL
documentation.

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
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
listing.

To get this script to run at system startup or any time the system switches
into
runlevels 4, 5, or 6, run 'chkconfig --add postgresql', and the proper
symlinks
will be created.  Check the chkconfig man page for more information.

This same script also works for TurboLinux, and any other distribution
similar
enough to RedHat.  SuSE Linux uses a different approach, using a different
location and a different script, found at either /sbin/init.d/postgres or
/usr/sbin/rcpostgres.  Please see the SuSE 'README.linux' for more
information.

GRAND UNIFIED CONFIGURATION (GUC) FILE

-------------------------------------------------------------------------------
The PostgreSQL server has many tunable parameters -- the file
/var/lib/pgsql/data/postgresql.conf is the master configuration file for the
whole system.  The RPM ships the default file -- you will need to tune the
parameters for your installation.  In particular, you might want to allow
TCP/IP socket connections -- in order to allow these, you will need to edit
the postgresql.conf file.

REBUILDING FROM SOURCE RPM

-------------------------------------------------------------------------------
If your distribution is not supported by the binary RPM's from
PostgreSQL.org,
you will need to rebuild from the source RPM.  Download the .src.rpm for
this
release.  You will need to be root to rebuild, unless you have already set
up
a non-root build environment.

Install the source RPM with rpm -i, then CD to the rpm building area (on
RedHat
this is /usr/src/redhat by default).  You will have to have a full
development
environment to rebuild the full RPM set.

Please read SPECS/postgresql.spec for instructions on using the conditional
package build system included in this RPM release.

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.

MORE INFORMATION

-------------------------------------------------------------------------------
You can get more information at http://www.postgresql.org

Please help make this packaging better -- let me know if you find problems,
or
better ways of doing things.  You can reach me by e-mail at
lamar@postgresql.org or pgsql-ports@postgresql.org.

SuSE information is available at feedback@suse.de

-----------------------------------------------------------------------------