postgresql93/README.rpm-dist

README.rpm-dist
-----------------------------------------------------------------------------
Version 9.3, for the PostgreSQL 9.3 RPM set.
Devrim Gündüz <devrim@gunduz.org>
-----------------------------------------------------------------------------

Contents:
 1.)	Introduction and QuickStart
 2.)	Upgrading an installation
 3.)	PostgreSQL RPM packages and rationale
 4.)	Starting multiple postmasters
 5.)	Regression Testing
 6.)	Starting postmaster automatically on startup
 7.)	Grand Unified Configuration(GUC) File
 8.)	Logging set up
 9.)	Rebuilding from the source RPM
10.)	Contrib files
11.)	Further Information Resource

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 9.3 of PostgreSQL,
which is the current version of the RPMs as of this writing. More to the 
point, versions prior to 9.3 are not documented here.

Official PostgreSQL Global Development Group RPMs carry a 'PGDG after the
release number.  Other RPMsets as distributed with Linux distributions may
have a different release number and initials.

If you want to stay up-to-date on the PostgreSQL core itself, you may
want to use PGDG set, instead of the binaries supplied by distribution.

These RPMs do not support any sort of major version upgrading process
other than that documented in the regular documentation.  That is, you
must dump, upgrade,initdb, and restore your data if you are
performing a major version update. This is not needed for minor version
updates.

QUICKSTART (note that this requires postgresql93-server installed)
-----------------------------------------------------------------------------
For a fresh installation, you will need to initialize the cluster first. Run:

	/usr/pgsql-9.3/bin/postgresql93-setup initdb

as root, and it will prepare a new database cluster for you. Then you will 
need to start PostgreSQL. Again as root, run:

	systemctl start postgresql-9.3.service

This command will start a postmaster that willl listen on localhost and Unix 
socket 5432 only.  Edit /var/lib/pgsql/9.3/data/postgresql.conf and pg_hba.conf 
if you want to allow remote access -- see the section on Grand Unified 
Configuration.

You will probably also want to do

	systemctl enable postgresql-9.3.service

so that the postmaster is automatically started during future reboots.

The file /var/lib/pgsql/9.3/.bash_profile is 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.  If you want 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.

In the default installation, only postgres user is allowed to access to 
the database server, because initdb in the RPMs pick up "peer" auth 
method in the RPMs. 

All the binaries are installed under /usr/pgsql-9.3/bin. However, the 
tools that are compatible with the previous releases are symlinked under 
/usr/bin directory. Please note that RPMs are using alternatives method 
in here, so whenever a newer major version is installed, symlinks will 
point to the new version. Here is the current list of the binaries that 
are under $PATH:

- clusterdb
- createdb
- createlang
- createuser
- dropdb
- droplang
- dropuser
- pg_dump
- pg_dumpall
- pg_restore
- psql
- reindexdb

You may want to add /usr/pgsql-9.3/bin to your $PATH variable in 
/etc/profile, if you want to use them easily. However, please note that 
this may lead to some unintentional side effects, so be careful.


UPGRADING AN INSTALLATION
-----------------------------------------------------------------------------
For a minor-version upgrade (such as 9.3.1 to 9.3.2), just install the
new RPMs; there's usually nothing more to it than that.  Upgrading
across a major release of PostgreSQL (for example, from 9.2.x to 9.3.x)
requires more effort.

If you are upgrading across more than one major release of PostgreSQL
(for example, from 9.1.x to 9.3.x), you will need to follow the "traditional"
dump and reload process to bring your data into the new version.  That is:
*before* upgrading, run pg_dumpall to extract all your data into a SQL file.
Shut down the old postmaster, upgrade to the new version RPMs, initdb,
and run the dump file through psql to restore your data.

In 9.1+, the RPMs also support in-place upgrade from th immediately 
previous major release.  Currently, you can upgrade in-place
from 9.2.x to 9.3.x.  Just run:
$ /usr/pgsql-9.3/bin/postgresql93-setup upgrade

Please note that 9.2 and 9.3 contrib RPMs needs	to be installed	for this 
feature	to work.

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:

postgresql93:           Key clients and libraries, and documentation
postgresql93-server:    Server executables and data files
postgresql93-devel:     Development libraries and include files
postgresql93-test:	The regression tests and associated files
postgresql93-libs:      Client shared libraries
postgresql93-docs:	Extra documentation, such as the tutorial files
postgresql93-contrib:   The contrib source tree, as well as selected binaries
postgresql93-plperl:    PL/Perl procedural language
postgresql93-plpython:  PL/Python procedural language
postgresql93-pltcl:     PL/Tcl procedural language

postgresql93-jdbc, postgresql93-python, postgresql93-tcl and postgresql93-odbc have
been splitted into  seperate (s)rpms.

You have to install postgresql and postgresql93-libs to do anything.
postgresql93-server is needed unless you only plan to use the clients to work
with a remote PostgreSQL server. The others are optional.

postgresql93-python package includes PyGreSQL, and Pgtcl is distributed
via postgresql93-tcl package.

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.

However, the Red Hat / Scientific Linux ( CentOS / Fedora RPM's install 
the files like this:

Executables:		/usr/bin and /usr/pgsql-9.3/bin
Libraries:		/usr/pgsql-9.3/lib
Documentation:		/usr/pgsql-9.3/doc
Contrib documentation:	/usr/pgsql-9.3/doc
Source:			not installed
Data:			/var/lib/pgsql/9.3/data
Backup area:		/var/lib/pgsql/9.3/backups
Templates:		/usr/pgsql-9.3/share
Procedural Languages:	/usr/pgsql-9.3/lib
Development Headers:	/usr/pgsql-9.3/include
Other shared data:	/usr/pgsql-9.3/share
Regression tests:	/usr/pgsql-9.3/lib/test

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 pgsql-pkg-yum@postgresql.org
mailing list.

-------------------------------------------------------------------------------
MULTIPLE POSTMASTERS (For the same PostgreSQL version)
-------------------------------------------------------------------------------
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-9.3 named 'secondary-9.3' : 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-9.3 start'.

Note that there may be problems with the standard symlink -- consider this
support experimental at this point in time.

When doing a major-version upgrade of a secondary postmaster, mention the
service name in the postgresql-setup command, for example 'postgresql-setup
upgrade secondary'.  This will let postgresql-setup find the correct data
directory from the service file.

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 the
postmaster has been started (if not, su to root and do "systemctl start
postgresql-9.3.service"), cd to /usr/pgsql-9.3/lib/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-general list at 
postgresql.org.

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

STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
-------------------------------------------------------------------------------
Fedora / Red Hat / CentOS use the systemd package to manage server startup.
A systemd unit file for PostgreSQL is provided in the server package, as
/lib/systemd/system/postgresql-9.3.service.  To start the postmaster manually,
as root run
	systemctl start postgresql-9.3.service
To shut the postmaster down,
	systemctl stop postgresql-9.3.service
These two commands only change the postmaster's current status.  If you
want the postmaster to be started automatically during future system startups,
run
	systemctl enable postgresql-9.3.service
To undo that again,
	systemctl disable postgresql-9.3.service
See "man systemctl" for other possible subcommands.

GRAND UNIFIED CONFIGURATION (GUC) FILE
-------------------------------------------------------------------------------
The PostgreSQL server has many tunable parameters -- the file 
/var/lib/pgsql/9.3/data/postgresql.conf is the master configuration file for the
whole system.  

The RPM ships with a mostly-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/9.3/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 set up
a non-root build environment (which is the recommended method anyway).

Install the source RPM with rpm -i, then cd to the rpm building area
(which 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 procedural language package.
pltcl		1	#build the PL/Tcl procedural language package.
plperl		1	#build the PL/Perl procedural language package.
ssl		1	#use OpenSSL support.
kerberos	1	#use Kerberos 5 support.
nls		1	#build with national language support.
ldap		1	#build with LDAP support.
pam		1	#build with PAM support.
runselftest	1	#do "make check" during the build.
sdt		1	#build with SystemTap support.
xml		1	#build with XML support
pgfts		1	#build with --enable-thread-safety
uuid		1	#build contrib/uuid-ossp

To use these defines, invoke a rebuild like this:
rpmbuild --rebuild --define 'python 0' --define 'tcl 0' \
	--define 'test 0' --define 'runselftest 0' --define 'kerberos 0' \
	postgresql93-9.3.1-1PGDG.f17.src.rpm
This line would disable the python, tcl, and test subpackages, disable 
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. Most of the modules are in 
/usr/pgsql-9.3/lib for loadable modules, and binaries are in 
/usr/pgsql-9.3/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://yum.postgresql.org

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
pgsql-pkg-yum@postgresql.org
-------------------------------------------------------------------------------