README.rpm-dist

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

Version 8.2, for the PostgreSQL 8.2.1-2 RPMset.

Devrim Gündüz <devrim@CommandPrompt.com>, Lamar Owen <lowen@pari.edu>

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

Contents:

 0.)	Quick note about '-i'

 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.)	Logging set up

 8.)	Rebuilding from the source RPM

 9.)	Contrib files

10.)	Further Information Resource

QUICK NOTE ABOUT '-i'

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

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.

INTRODUCTION

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

This document exists to explain the layout of the RPMs 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 8.2 of PostgreSQL, 

which is the current version of the RPMs as of this writing. More to the 

point, versions prior to 8.2 are not documented here.

Official PostgreSQL Global Development Group RPMs have from version 7.1.2

on carried a 'PGDG' after the release number.  Other RPMsets 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 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.  Dump first, then remove the old server

subpackage, install the new package, and restore the data from dump. (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.)

SuSE has maintained their own RPMset for some time -- their documentation

supercedes any found in this file.

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 localhost and Unix socket 5432 only.  Edit

/var/lib/pgsql/data/postgresql.conf and pg_hba.conf if you want to allow

remote access -- see the section on Grand Unified Configuration.

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

Devrim Gunduz

POSTGRESQL RPM PACKAGES AND RATIONALE.

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

PostgreSQL is split up into multiple packages so that users can 'pick and

choose' what pieces are needed, and what dependencies are required.

The RPMset is packaged in the following subpackages:

postgresql:		Key clients and libraries, and documentation

postgresql-libs:	Client shared libraries

postgresql-server:	Server executables and data files

postgresql-devel:	Development libraries and include files

postgresql-python:	The PyGreSQL client library

postgresql-tcl:		Tcl client library (Pgtcl)

postgresql-test:	The regression tests and associated files

postgresql-docs:	Extra documentation, such as the tutorial files

postgresql-contrib:	The contrib source tree, as well as selected binaries

postgresql-plperl:	PL/Perl procedural language

postgresql-plpython:	PL/Python procedural language

postgresql-pltcl:	PL/Tcl procedural language

You have to install postgresql and postgresql-libs to do anything.

postgresql-server is needed unless you only plan to use the clients to work

with a remote PostgreSQL server. The others are optional.

Note that there is no postgresql-perl, postgresql-jdbc, postgresql-odbc, or

postgresql-tk package any longer.  This is due to these portions being split

into separate source distributions.

While PyGreSQL was split out from the core PostgreSQL distribution, thanks to

Kaj's work it is still included as the python subpackage.  Also, Pgtcl is

still included as the tcl subpackage, although it is not part of the core

distribution anymore.

RPM FILE LOCATIONS.

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

To be in compliance with the Linux FHS, the PostgreSQL RPMs 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

Red Hat / Fedora Core locations are listed below.

However, the RPMs install the files like this:

Executables:		/usr/bin

Libraries:		/usr/lib

Documentation:		/usr/share/doc/postgresql-x.y.z

Contrib documentation:	/usr/share/doc/postgresql-contrib-x.y.z

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

Localization data:	/usr/share/locale

Other shared data:	/usr/share/pgsql

Regression tests:	/usr/lib/pgsql/test/regress  (in the -test package)

Tutorial:		/usr/lib/pgsql/tutorial (in the -docs package)

Extra documentation:	/usr/share/doc/postgresql-docs-x.y.z

On some 64-bit architectures, /usr/lib64 is used instead of /usr/lib.

The above list describes the Red Hat / Fedora Core layout.  These locations

may change for other distributions.  Use of 'rpm -ql' for each package is

recommended as the 'official' information 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 RPMs are designed to be LSB-compliant -- if you find this not to be the

case, please let us know by way of the pgsqlrpms-hackers@pgfoundry.org

mailing list.

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

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

If you install the postgresql-test RPM then you can run the PostgreSQL

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 "make check".

This command will start the regression tests and will both show the

results to the screen and store the results in the file regress.out.

If any tests fail, see the file regression.diffs in that directory for details,

and read the "Regression Tests" section of the PostgreSQL documentation to

find out whether the differences are actually significant.  If you need help

interpreting the results, contact the pgsql-ports list at postgresql.org or

the pgsqlrpms-general list at pgfoundry.org.

After testing, say "make clean" to remove the files generated by the test

script.

STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP

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

Red Hat 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 the postmaster down,

	service postgresql stop

There are other possible commands 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.  See 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.

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

nonlocal 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 

'listen_addresses' -- you need to both uncomment the line and set the value

to '*' to get the postmaster to accept nonlocal connections.  You'll also need

to adjust pg_hba.conf appropriately.

LOGGING SET UP

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

By default, the postmaster's stderr log is directed into files placed in a

pg_log subdirectory of the data directory (ie, /var/lib/pgsql/data/pg_log).

The out-of-the-box configuration rotates among seven files, one for each

day of the week.  You can adjust this by changing postgresql.conf settings.

REBUILDING FROM SOURCE RPM

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

If your distribution is not supported by the binary RPMs 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 Red

Hat or Fedora Core 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:

beta		0	#build with cassert and do not strip the binaries

python		1	#build the postgresql-python package.

tcl		1	#build the postgresql-tcl package.

test		1	#build the postgresql-test package.

plpython	1	#build the PL/Python package

pltcl		1	#build the PL/Tcl package.

plperl		1	#build the PL/Perl 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.

runselftest	1	#do "make check" during the build.

xml		1	#build contrib/xml2

pgfts		1	#build with --enable-thread-safety

To use these defines, invoke a rebuild like this:

rpmbuild --rebuild --define 'python 0' --define 'tcl 0' \

	--define 'test 0' --define 'runselftest 1' --define 'kerberos 0' \

	postgresql-8.2.1-1.src.rpm

This line would disable the python, tcl, and test subpackages, enable the

regression test run during build, and disable kerberos support.

You might need to disable runselftest if there is an installed version of

PostgreSQL that is a different major version from what you are trying to

build.  The self test tends to pick up the installed libpq.so shared library

in place of the one being built :-(, so if that isn't compatible the test will

fail.  Also, you can't use runselftest when doing the build as root.

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.

MORE INFORMATION

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

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

http://pgfoundry.org/projects/pgsqlrpms

Please help make this packaging better -- let us know if you find problems, or

better ways of doing things.  You can reach us by e-mail at

pgsqlrpms-hackers@pgfoundry.org

SUSE products usually ship with the latest version of PostgreSQL that

was available at the time they were released. RPMs for newer versions

of PostgreSQL can be found on the SUSE FTP server and it's mirrors.

ftp://ftp.suse.com/pub/projects/postgresql

http://www.novell.com/products/linuxprofessional/downloads/ftp/int_mirrors.html

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