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.

This document is intended for use only with the RPMs supplied in Red Hat

Enterprise Linux, CentOS and Fedora.  Note that there are also "PGDG"

RPMs available directly from the upstream PostgreSQL project.  Those are

slightly different.

QUICKSTART (note that this requires postgresql-server installed)

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

For a fresh installation, you will need to initialize the cluster first. Run:

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

This command will start a postmaster that willl 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.

You will probably also want to do

	systemctl enable postgresql.service

so that the postmaster is automatically started during future reboots.

The file /var/lib/pgsql/.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, so the only way to become this user is to su to it from root.

If you want to be able to su to it from a non-root account or log in directly

as 'postgres' you will need to set a password using passwd.

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 8.3.x to 9.0.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 some major releases, the RPMs also support in-place upgrade from the

immediately previous major release.  Currently, you can upgrade in-place

from 9.2.x to 9.3.x.  This is much faster than a dump and reload.

To do an in-place upgrade:

* shut down the old postmaster ("systemctl stop postgresql.service")

* optionally make a backup of /var/lib/pgsql/data/ (recommended!)

* install the new version's RPMs (install all the ones you had before,

  plus postgresql-upgrade)

* as root, run "postgresql-setup upgrade"

* update the configuration files /var/lib/pgsql/data/*.conf with any

  customizations you had before (your old configuration files are in

  /var/lib/pgsql/data-old/)

* as root, run "systemctl start postgresql.service"

* the postgresql-upgrade RPM can be removed after the update is complete,

  as can /var/lib/pgsql/data-old/

NOTE: The in-place upgrade process is new and relatively poorly tested,

so if your data is critical it's a really good idea to make a tarball

backup of /var/lib/pgsql/data/ before running the upgrade.  This will

let you get back to where you were in case of disaster.

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 client programs and documentation

postgresql-libs:	Client shared libraries

postgresql-server:	Server executables and data files

postgresql-devel:	Development libraries and include files

postgresql-test:	The regression tests and associated files

postgresql-upgrade:	Support files for upgrading from previous major version

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

postgresql-contrib:	Add-on loadable modules and programs

postgresql-plperl:	PL/Perl procedural language

postgresql-plpython:	PL/Python procedural language (for Python 2)

postgresql-plpython3:	PL/Python procedural language (for Python 3)

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 are no postgresql-perl, postgresql-jdbc, postgresql-odbc,

postgresql-python, postgresql-tcl, or postgresql-tk subpackages any longer.

Those programs have been split off into separate source distributions.

They are still available, but in some cases not under those RPM names.

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 / CentOS / Fedora RPM's install the files like 

this:

Executables:		/usr/bin

Libraries:		/usr/lib (or /usr/lib64 on 64-bit machines)

Documentation:		/usr/share/doc/postgresql/html

PDF documentation:	/usr/share/doc/postgresql-docs

Contrib documentation:	/usr/share/doc/postgresql-contrib

Source:			not installed

Data:			/var/lib/pgsql/data

Backup area:		/var/lib/pgsql/backups

Templates:		/usr/share/pgsql

Procedural Languages:	/usr/lib/pgsql or /usr/lib64/pgsql

Development Headers:	/usr/include/pgsql

Other shared data:	/usr/share/pgsql

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

			or /usr/lib64/pgsql/test/regress

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

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

The postgresql-server RPM contains a systemd "unit" file, postgresql.service,

that is used to start the PostgreSQL postmaster.  If you need to run multiple

postmasters on one machine, you can create additional unit files derived

from this one.

As an example, let us create a secondary postmaster called, creatively enough,

'secondary'.  Here are the steps:

1.)	Create a file named /etc/systemd/system/secondary.service.

	(Note that user-created unit files must go into /etc not /lib!)

	Put these lines in it:

		.include /lib/systemd/system/postgresql.service

		[Service]

		Environment=PGPORT=nnnn

		Environment=PGDATA=/path/to/data/directory

	Replace "nnnn" and "/path/to/data/directory" with appropriate

	settings that don't conflict with any other postmaster.

2.)	As root, do "/bin/systemctl daemon-reload" to ensure systemd has

	noticed your updates to the service file.

3.)	Create the target PGDATA directory, making sure that its parent

	directories have appropriate ownership and permissions.

4.)	Initdb the target PGDATA with 'postgresql-setup initdb secondary'.

5.)	Edit postgresql.conf in the target PGDATA to change settings as needed.

6.)	Start the new postmaster with 'systemctl start secondary.service'.

	You will probably also want to do 'systemctl enable secondary.service'

	so that the new postmaster is automatically started in future reboots.

When doing a major-version upgrade of a secondary postmaster, add the

service name to the postgresql-setup command, for example 'postgresql-setup

upgrade secondary'.  This will let postgresql-setup find the correct data

directory from the service file.

If you are running SELinux in enforcing mode (which is highly recommended,

particularly for network-exposed services like PostgreSQL) you will need to

adjust SELinux policy to allow the postmaster to use non-default PGPORT or

PGDATA settings.  To allow use of a non-default port, say 5433, do this

as root:

	semanage port -a -t postgresql_port_t -p tcp 5433

To allow use of a non-default data directory, say /special/pgdata, do:

	semanage fcontext -a -t postgresql_db_t "/special/pgdata(/.*)?"

If you already created the directory, follow that with:

	restorecon -R /special/pgdata

These settings are persistent across reboots.  For more information

see "man semanage".

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.service"), su to postgres, cd to /usr/lib/pgsql/test/regress

(or /usr/lib64/pgsql/test/regress on a 64-bit machine),

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, run "make clean" to remove the files generated by the test

script.  Then you can remove the postgresql-test RPM, if you wish.

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.service.  To start the postmaster manually,

as root run

	systemctl start postgresql.service

To shut the postmaster down,

	systemctl stop postgresql.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.service

To undo that again,

	systemctl disable postgresql.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/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/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.

If you have not previously rebuilt any RPMs, set up the required environment:

make a work directory, say ~/rpmwork, then cd into it and do

	mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS

Then make a file ~/.rpmmacros containing

	%_topdir <full path to work directory here>

Download the postgresql .src.rpm for the release you want and place it in

the SRPMS subdirectory, then cd there and execute

	rpmbuild --rebuild postgresql-nnn.src.rpm

The results will appear under the RPMS subdirectory.

You will have to have a full development environment to rebuild the RPM set.

If rpmbuild complains of lack of certain packages, install them and try

again.  In some cases, you can disable features to avoid needing some

development packages, as detailed next.

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

runselftest	1	#do "make check" during the build

test		1	#build the postgresql-test package

upgrade		1	#build the postgresql-upgrade package

plpython	1	#build the PL/Python procedural language package

plpython3	1	#build the PL/Python3 procedural language package

pltcl		1	#build the PL/Tcl procedural language package

plperl		1	#build the PL/Perl procedural language package

ssl		1	#build with OpenSSL support

kerberos	1	#build with Kerberos 5 support

ldap		1	#build with LDAP support

nls		1	#build with national language support

pam		1	#build with PAM support

sdt		1	#build with SystemTap support

xml		1	#build with XML support

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

selinux		1	#build contrib/selinux

uuid		1	#build contrib/uuid-ossp

To use these defines, invoke a rebuild like this:

rpmbuild --rebuild --define 'plpython 0' --define 'pltcl 0' \

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

	postgresql-9.2.0-1.src.rpm

This line would disable the plpython, pltcl, 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.  There is documentation in

/usr/share/doc/postgresql-contrib for these modules.  Most of the

modules are in /usr/lib/pgsql (or /usr/lib64/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://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

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