699f87
README.rpm-dist
699f87
-----------------------------------------------------------------------------
699f87
Version 9.2, for the PostgreSQL 9.2 RPM set.
699f87
Devrim Gündüz <devrim@gunduz.org>
699f87
-----------------------------------------------------------------------------
699f87
699f87
Contents:
699f87
 1.)	Introduction and QuickStart
699f87
 2.)	Upgrading an installation
699f87
 3.)	PostgreSQL RPM packages and rationale
699f87
 4.)	Starting multiple postmasters
699f87
 5.)	Regression Testing
699f87
 6.)	Starting postmaster automatically on startup
699f87
 7.)	Grand Unified Configuration(GUC) File
699f87
 8.)	Logging set up
699f87
 9.)	Rebuilding from the source RPM
699f87
10.)	Contrib files
699f87
11.)	Further Information Resource
699f87
699f87
INTRODUCTION
699f87
-----------------------------------------------------------------------------
699f87
This document exists to explain the layout of the RPMs for PostgreSQL, to 
699f87
describe various RPM specifics, and to document special features found
699f87
in the RPMset.
699f87
699f87
This document is written to be applicable to version 9.2 of PostgreSQL,
699f87
which is the current version of the RPMs as of this writing. More to the 
699f87
point, versions prior to 9.2 are not documented here.
699f87
699f87
This document is intended for use only with the RPMs supplied in Red Hat
699f87
Enterprise Linux, CentOS and Fedora.  Note that there are also "PGDG"
699f87
RPMs available directly from the upstream PostgreSQL project.  Those are
699f87
slightly different.
699f87
699f87
QUICKSTART (note that this requires postgresql-server installed)
699f87
-----------------------------------------------------------------------------
699f87
For a fresh installation, you will need to initialize the cluster first. Run:
699f87
699f87
	postgresql-setup initdb
699f87
699f87
as root, and it will prepare a new database cluster for you. Then you will 
699f87
need to start PostgreSQL. Again as root, run:
699f87
699f87
	systemctl start postgresql.service
699f87
699f87
This command will start a postmaster that willl listen on localhost and Unix 
699f87
socket 5432 only.  Edit /var/lib/pgsql/data/postgresql.conf and pg_hba.conf 
699f87
if you want to allow remote access -- see the section on Grand Unified 
699f87
Configuration.
699f87
699f87
You will probably also want to do
699f87
699f87
	systemctl enable postgresql.service
699f87
699f87
so that the postmaster is automatically started during future reboots.
699f87
699f87
The file /var/lib/pgsql/.bash_profile is packaged to help with the 
699f87
setting of environment variables. You may edit this file, and it won't be
699f87
overwritten during an upgrade.  However, enhancements and bugfixes may 
699f87
be added to this file, so be sure to check .bash_profile.rpmnew after 
699f87
upgrading.
699f87
699f87
The user 'postgres' is created during installation of the server subpackage.
699f87
This user by default is UID and GID 26. The user has the default shell set to
699f87
bash, and the home directory set to /var/lib/pgsql.  This user also has no
699f87
default password, so the only way to become this user is to su to it from root.
699f87
If you want to be able to su to it from a non-root account or log in directly
699f87
as 'postgres' you will need to set a password using passwd.
699f87
699f87
UPGRADING AN INSTALLATION
699f87
-----------------------------------------------------------------------------
699f87
For a minor-version upgrade (such as 9.2.1 to 9.2.2), just install the
699f87
new RPMs; there's usually nothing more to it than that.  Upgrading
699f87
across a major release of PostgreSQL (for example, from 9.1.x to 9.2.x)
699f87
requires more effort.
699f87
699f87
If you are upgrading across more than one major release of PostgreSQL
699f87
(for example, from 8.3.x to 9.0.x), you will need to follow the "traditional"
699f87
dump and reload process to bring your data into the new version.  That is:
699f87
*before* upgrading, run pg_dumpall to extract all your data into a SQL file.
699f87
Shut down the old postmaster, upgrade to the new version RPMs, initdb,
699f87
and run the dump file through psql to restore your data.
699f87
699f87
In some major releases, the RPMs also support in-place upgrade from the
699f87
immediately previous major release.  Currently, you can upgrade in-place
699f87
from 9.1.x to 9.2.x.  This is much faster than a dump and reload.
699f87
To do an in-place upgrade:
699f87
* shut down the old postmaster ("systemctl stop postgresql.service")
699f87
* optionally make a backup of /var/lib/pgsql/data/ (recommended!)
699f87
* install the new version's RPMs (install all the ones you had before,
699f87
  plus postgresql-upgrade)
699f87
* as root, run "postgresql-setup upgrade"
699f87
* update the configuration files /var/lib/pgsql/data/*.conf with any
699f87
  customizations you had before (your old configuration files are in
699f87
  /var/lib/pgsql/data-old/)
699f87
* as root, run "systemctl start postgresql.service"
699f87
* the postgresql-upgrade RPM can be removed after the update is complete,
699f87
  as can /var/lib/pgsql/data-old/
699f87
699f87
NOTE: The in-place upgrade process is new and relatively poorly tested,
699f87
so if your data is critical it's a really good idea to make a tarball
699f87
backup of /var/lib/pgsql/data/ before running the upgrade.  This will
699f87
let you get back to where you were in case of disaster.
699f87
699f87
POSTGRESQL RPM PACKAGES AND RATIONALE.
699f87
-----------------------------------------------------------------------------
699f87
PostgreSQL is split up into multiple packages so that users can 'pick and
699f87
choose' what pieces are needed, and what dependencies are required.
699f87
699f87
The RPMset is packaged in the following subpackages:
699f87
699f87
postgresql:		Key client programs and documentation
699f87
postgresql-libs:	Client shared libraries
699f87
postgresql-server:	Server executables and data files
699f87
postgresql-devel:	Development libraries and include files
699f87
postgresql-test:	The regression tests and associated files
699f87
postgresql-upgrade:	Support files for upgrading from previous major version
699f87
postgresql-docs:	Extra documentation, such as the tutorial files
699f87
postgresql-contrib:	Add-on loadable modules and programs
699f87
postgresql-plperl:	PL/Perl procedural language
699f87
postgresql-plpython:	PL/Python procedural language (for Python 2)
699f87
postgresql-plpython3:	PL/Python procedural language (for Python 3)
699f87
postgresql-pltcl:	PL/Tcl procedural language
699f87
699f87
You have to install postgresql and postgresql-libs to do anything.
699f87
postgresql-server is needed unless you only plan to use the clients to work
699f87
with a remote PostgreSQL server. The others are optional.
699f87
699f87
Note that there are no postgresql-perl, postgresql-jdbc, postgresql-odbc,
699f87
postgresql-python, postgresql-tcl, or postgresql-tk subpackages any longer.
699f87
Those programs have been split off into separate source distributions.
699f87
They are still available, but in some cases not under those RPM names.
699f87
699f87
RPM FILE LOCATIONS.
699f87
-----------------------------------------------------------------------------
699f87
To be in compliance with the Linux FHS, the PostgreSQL RPMs install files in
699f87
a manner not consistent with most of the PostgreSQL documentation.  According
699f87
to the standard PostgreSQL documentation, PostgreSQL is installed under the
699f87
directory /usr/local/pgsql, with executables, source, and data existing in
699f87
various subdirectories.
699f87
699f87
Different distributions have different ideas of some of these file locations.
699f87
In particular, the documentation directory can be /usr/doc, /usr/doc/packages,
699f87
/usr/share/doc, /usr/share/doc/packages, or some other similar path.
699f87
699f87
However, the Red Hat / CentOS / Fedora RPM's install the files like 
699f87
this:
699f87
699f87
Executables:		/usr/bin
699f87
Libraries:		/usr/lib (or /usr/lib64 on 64-bit machines)
699f87
Documentation:		/usr/share/doc/postgresql-docs-x.y.z/html
699f87
Contrib documentation:	/usr/share/doc/postgresql-contrib-x.y.z
699f87
Source:			not installed
699f87
Data:			/var/lib/pgsql/data
699f87
Backup area:		/var/lib/pgsql/backups
699f87
Templates:		/usr/share/pgsql
699f87
Procedural Languages:	/usr/lib/pgsql or /usr/lib64/pgsql
699f87
Development Headers:	/usr/include/pgsql
699f87
Other shared data:	/usr/share/pgsql
699f87
Regression tests:	/usr/lib/pgsql/test/regress  (in the -test package)
699f87
			or /usr/lib64/pgsql/test/regress
699f87
699f87
While it may seem gratuitous to place these files in different locations, the
699f87
FHS requires it -- distributions should not ever touch /usr/local.  It may
699f87
also seem like more work to keep track of where everything is -- but, that's
699f87
the beauty of RPM -- you don't have to keep track of the files, RPM does it
699f87
for you.
699f87
699f87
These RPMs are designed to be LSB-compliant -- if you find this not to be the
699f87
case, please let us know by way of the pgsqlrpms-hackers@pgfoundry.org
699f87
mailing list.
699f87
699f87
MULTIPLE POSTMASTERS
699f87
-------------------------------------------------------------------------------
699f87
The postgresql-server RPM contains a systemd "unit" file, postgresql.service,
699f87
that is used to start the PostgreSQL postmaster.  If you need to run multiple
699f87
postmasters on one machine, you can create additional unit files derived
699f87
from this one.
699f87
699f87
As an example, let us create a secondary postmaster called, creatively enough,
699f87
'secondary'.  Here are the steps:
699f87
1.)	Create a file named /etc/systemd/system/secondary.service.
699f87
	(Note that user-created unit files must go into /etc not /lib!)
699f87
	Put these lines in it:
699f87
		.include /lib/systemd/system/postgresql.service
699f87
		[Service]
699f87
		Environment=PGPORT=nnnn
699f87
		Environment=PGDATA=/path/to/data/directory
699f87
	Replace "nnnn" and "/path/to/data/directory" with appropriate
699f87
	settings that don't conflict with any other postmaster.
699f87
2.)	As root, do "/bin/systemctl daemon-reload" to ensure systemd has
699f87
	noticed your updates to the service file.
699f87
3.)	Create the target PGDATA directory, making sure that its parent
699f87
	directories have appropriate ownership and permissions.
699f87
4.)	Initdb the target PGDATA with 'postgresql-setup initdb secondary'.
699f87
5.)	Edit postgresql.conf in the target PGDATA to change settings as needed.
699f87
6.)	Start the new postmaster with 'systemctl start secondary.service'.
699f87
	You will probably also want to do 'systemctl enable secondary.service'
699f87
	so that the new postmaster is automatically started in future reboots.
699f87
699f87
When doing a major-version upgrade of a secondary postmaster, add the
699f87
service name to the postgresql-setup command, for example 'postgresql-setup
699f87
upgrade secondary'.  This will let postgresql-setup find the correct data
699f87
directory from the service file.
699f87
699f87
If you are running SELinux in enforcing mode (which is highly recommended,
699f87
particularly for network-exposed services like PostgreSQL) you will need to
699f87
adjust SELinux policy to allow the postmaster to use non-default PGPORT or
699f87
PGDATA settings.  To allow use of a non-default port, say 5433, do this
699f87
as root:
699f87
	semanage port -a -t postgresql_port_t -p tcp 5433
699f87
To allow use of a non-default data directory, say /special/pgdata, do:
699f87
	semanage fcontext -a -t postgresql_db_t "/special/pgdata(/.*)?"
699f87
If you already created the directory, follow that with:
699f87
	restorecon -R /special/pgdata
699f87
These settings are persistent across reboots.  For more information
699f87
see "man semanage".
699f87
699f87
REGRESSION TESTING
699f87
-------------------------------------------------------------------------------
699f87
If you install the postgresql-test RPM then you can run the PostgreSQL
699f87
regression tests.  These tests stress your database installation and produce
699f87
results that give you assurances that the installation is complete, and that
699f87
your database machine is up to the task.
699f87
699f87
To run the regression tests under the RPM installation, make sure that the
699f87
postmaster has been started (if not, su to root and do "systemctl start
699f87
postgresql.service"), su to postgres, cd to /usr/lib/pgsql/test/regress
699f87
(or /usr/lib64/pgsql/test/regress on a 64-bit machine),
699f87
and execute "make check".
699f87
This command will start the regression tests and will both show the
699f87
results to the screen and store the results in the file regress.out.
699f87
699f87
If any tests fail, see the file regression.diffs in that directory for details,
699f87
and read the "Regression Tests" section of the PostgreSQL documentation to
699f87
find out whether the differences are actually significant.  If you need help
699f87
interpreting the results, contact the pgsql-general list at 
699f87
postgresql.org.
699f87
699f87
After testing, run "make clean" to remove the files generated by the test
699f87
script.  Then you can remove the postgresql-test RPM, if you wish.
699f87
699f87
STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
699f87
-------------------------------------------------------------------------------
699f87
Fedora / Red Hat / CentOS use the systemd package to manage server startup.
699f87
A systemd unit file for PostgreSQL is provided in the server package, as
699f87
/lib/systemd/system/postgresql.service.  To start the postmaster manually,
699f87
as root run
699f87
	systemctl start postgresql.service
699f87
To shut the postmaster down,
699f87
	systemctl stop postgresql.service
699f87
These two commands only change the postmaster's current status.  If you
699f87
want the postmaster to be started automatically during future system startups,
699f87
run
699f87
	systemctl enable postgresql.service
699f87
To undo that again,
699f87
	systemctl disable postgresql.service
699f87
See "man systemctl" for other possible subcommands.
699f87
699f87
GRAND UNIFIED CONFIGURATION (GUC) FILE
699f87
-------------------------------------------------------------------------------
699f87
The PostgreSQL server has many tunable parameters -- the file 
699f87
/var/lib/pgsql/data/postgresql.conf is the master configuration file for the
699f87
whole system.  
699f87
699f87
The RPM ships with a mostly-default file -- you will need to tune the
699f87
parameters for your installation.  In particular, you might want to allow
699f87
nonlocal TCP/IP socket connections -- in order to allow these, you will need
699f87
to edit the postgresql.conf file.  The line in question contains the string 
699f87
'listen_addresses' -- you need to both uncomment the line and set the value
699f87
to '*' to get the postmaster to accept nonlocal connections.  You'll also need
699f87
to adjust pg_hba.conf appropriately.
699f87
699f87
LOGGING SET UP
699f87
-------------------------------------------------------------------------------
699f87
By default, the postmaster's stderr log is directed into files placed in a
699f87
pg_log subdirectory of the data directory (ie, /var/lib/pgsql/data/pg_log).
699f87
The out-of-the-box configuration rotates among seven files, one for each
699f87
day of the week.  You can adjust this by changing postgresql.conf settings.
699f87
699f87
REBUILDING FROM SOURCE RPM
699f87
-------------------------------------------------------------------------------
699f87
If your distribution is not supported by the binary RPMs from PostgreSQL.org, 
699f87
you will need to rebuild from the source RPM.
699f87
699f87
If you have not previously rebuilt any RPMs, set up the required environment:
699f87
make a work directory, say ~/rpmwork, then cd into it and do
699f87
	mkdir BUILD BUILDROOT RPMS SOURCES SPECS SRPMS
699f87
Then make a file ~/.rpmmacros containing
699f87
	%_topdir <full path to work directory here>
699f87
699f87
Download the postgresql .src.rpm for the release you want and place it in
699f87
the SRPMS subdirectory, then cd there and execute
699f87
	rpmbuild --rebuild postgresql-nnn.src.rpm
699f87
The results will appear under the RPMS subdirectory.
699f87
699f87
You will have to have a full development environment to rebuild the RPM set.
699f87
If rpmbuild complains of lack of certain packages, install them and try
699f87
again.  In some cases, you can disable features to avoid needing some
699f87
development packages, as detailed next.
699f87
699f87
This release of the RPMset includes the ability to conditionally build 
699f87
sets of packages.  The parameters, their defaults, and the meanings are:
699f87
699f87
beta		0	#build with cassert and do not strip the binaries
699f87
runselftest	1	#do "make check" during the build
699f87
test		1	#build the postgresql-test package
699f87
upgrade		1	#build the postgresql-upgrade package
699f87
plpython	1	#build the PL/Python procedural language package
699f87
plpython3	1	#build the PL/Python3 procedural language package
699f87
pltcl		1	#build the PL/Tcl procedural language package
699f87
plperl		1	#build the PL/Perl procedural language package
699f87
ssl		1	#build with OpenSSL support
699f87
kerberos	1	#build with Kerberos 5 support
699f87
ldap		1	#build with LDAP support
699f87
nls		1	#build with national language support
699f87
pam		1	#build with PAM support
699f87
sdt		1	#build with SystemTap support
699f87
xml		1	#build with XML support
699f87
pgfts		1	#build with --enable-thread-safety
699f87
selinux		1	#build contrib/selinux
699f87
uuid		1	#build contrib/uuid-ossp
699f87
699f87
To use these defines, invoke a rebuild like this:
699f87
rpmbuild --rebuild --define 'plpython 0' --define 'pltcl 0' \
699f87
	--define 'test 0' --define 'runselftest 0' --define 'kerberos 0' \
699f87
	postgresql-9.2.0-1.src.rpm
699f87
This line would disable the plpython, pltcl, and test subpackages, disable
699f87
the regression test run during build, and disable kerberos support.
699f87
699f87
You might need to disable runselftest if there is an installed version of
699f87
PostgreSQL that is a different major version from what you are trying to
699f87
build.  The self test tends to pick up the installed libpq.so shared library
699f87
in place of the one being built :-(, so if that isn't compatible the test will
699f87
fail.  Also, you can't use runselftest when doing the build as root.
699f87
699f87
More of these conditionals will be added in the future.
699f87
699f87
CONTRIB FILES
699f87
-------------------------------------------------------------------------------
699f87
The contents of the contrib tree are packaged into the -contrib subpackage
699f87
and are processed with make and make install.  There is documentation in
699f87
/usr/share/doc/postgresql-contrib-VERSION for these modules.  Most of the
699f87
modules are in /usr/lib/pgsql (or /usr/lib64/pgsql) for loadable
699f87
modules, and binaries are in /usr/bin.  In the future these files may be
699f87
split out, depending upon function and dependencies.
699f87
699f87
MORE INFORMATION
699f87
-------------------------------------------------------------------------------
699f87
You can get more information at http://www.postgresql.org and 
699f87
http://yum.pgsqlrpms.org
699f87
699f87
Please help make this packaging better -- let us know if you find problems, or
699f87
better ways of doing things. You can reach us by e-mail at
699f87
pgsqlrpms-hackers@pgfoundry.org
699f87
-------------------------------------------------------------------------------