postgresql/README.rpm-dist

README.rpm-dist
-----------------------------------------------------------------------------
Version 6.0, for the PostgreSQL 7.4-0.1PGDG RPMset.
Lamar Owen <lamar.owen@wgcr.org> 
-----------------------------------------------------------------------------

Contents:
 0.)	Quick -i note.
 1.)	Introduction, QuickStart, and credits
 2.)	PostgreSQL RPM packages and rationale
 3.)	Starting multiple postmasters
 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 
describe various RPM specifics, and to document special features found
in the RPMset.

This document is written to be applicable to version 7.4 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 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.

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 conflicted with prior
versions.  The old server subpackage must be removed first, the new package
installed, and the data restored from dump.  However, RPM itself did not
honor this.  A new method of running multiple versions of PostgreSQL, along
with the capability to run multiple postmasters, is in development, but was
not ready for this release.

A new section on running multiple postmasters has replaced the old upgrade
instructions.

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

While PygreSQL was split out from the main tarball, thanks to Kaj's work it
is still included as the python subpackage.

CREDITS
-----------------------------------------------------------------------------
Thomas Lockhart
Uncle George
Ryan Kirkpatrick
Trond Eivind Glomsrd
Mark Knox
Mike Mascari
Nicolas Huillard
Karl DeBisschop
Roger Luethi
Jeff Johnson
Reinhard Max
Peter Eisentraut
Joe Conway
Andrew Overholt
David Jee
Kaj J. Niemi

POSTGRESQL RPM PACKAGES AND RATIONALE.
-----------------------------------------------------------------------------
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-tcl:		TCL/TK client libraries and docs
postgresql-python:	The PygreSQL client library
postgresql-jdbc:	JAR of the JDBC client
postgresql-test:	The regression tests and associated files.
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.

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

MULTIPLE POSTMASTERS
-------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------
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/lib/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.

For 7.1RC1, all 76 tests passed on RedHat 6.2 and RedHat 7.0. This
was accomplished by fiddling with the locale settings.  In version 7.1.2 this
capability was removed -- you need to set your locale to 'C' before executing
the first postmaster startup, or many more regression tests will fail.

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
service postgresql start
to shut postmaster down,
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
runlevels 3, 4, or 5, run:
chkconfig --add postgresql
chkconfig --level 345 postgresql on
and the proper symlinks will be created.  Check the chkconfig man page for more
information.  Note that this is manual -- while the startup script can include
tags to allow chkconfig to automatically perform the symlinking, this is not
done at this time.

SuSE has maintained their own RPMset for some time -- their documentation
supercedes any found in this file.

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 with 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.  The line in question contains the string 
'tcpip_socket' --want to both uncomment the line and set the parameter to true
in order to get the TCP/IP socket to open.  

This is the same behavior the -i command line switch provides.  It is 
preferable to use the postgresql.conf file, however, as future versions
of the RPMset will allow multiple postmaster instances -- and that will only
be possible thanks to the decoupling of settings out to each datadir.

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.

This release of the RPMset includes the ability to conditionally build 
sets of packages.  The parameters, their defaults, and the meanings are:

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.  
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 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.
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'\
	--define 'test 0' --define 'newintarray 1' --define 'kerberos 0' \
	postgresql-7.1.3-1PGDG.src.rpm
This line would disable the perl, tcl, tk, and test subpackages, enable the
newer intarray code, and disable kerberos support.

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 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
-------------------------------------------------------------------------------
To get rollable syslog set up, see the documentation for the file
postgresql.conf, by default in the directory /var/lib/pgsql/data, as relates to
the syslog options.  Then, add a line to /etc/syslog.conf, using the man page
for syslog.conf as a source. Example:
If postgresql.conf has the following lines for the syslog settings:
syslog = 1 # range 0-2
syslog_facility = 'LOCAL0'
syslog_ident = 'postgres'

Then you need to add the line to /etc/syslog.conf:
local0.*			/var/log/postgresql 

Then set up an entry in /etc/logrotate.d to roll postgresql the way you want it
rolled.

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
pgsql-ports@postgresql.org -- please include an [RPM] string in the subject, as
I use automatic mail folder processing to put mail in the right place.

SuSE information is available at SuSE's website and information contacts.
A 7.4 SuSE RPM is available on ftp.postgresql.org.  It is different from this
RPM due to SuSE's different needs.
-----------------------------------------------------------------------------