358 lines
17 KiB
Plaintext
358 lines
17 KiB
Plaintext
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
|
|
-------------------------------------------------------------------------------
|