PostgreSQL/README.rpm-dist

warning

This wiki page is copy of README.rpm-dist file packaged in postgresql RPM package. We keep this page updated with the latest Fedora release package.

Feel free to report issues in this document against https://github.com/devexp-db/postgresql-setup project, or simply edit this wiki page, we'll backport the changes done in this document into the package.

                               PostgreSQL in RPMs

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

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.5 of PostgreSQL,
   which is the current version of the RPMs as of this writing. More to the
   point, versions prior to 9.5 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

   For a fresh installation, you will need to initialize the cluster first
   (as a root user):

         # postgresql-setup --initdb

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

         # systemctl start postgresql.service

   This command will 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. 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. Test section 2.

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

UPGRADING AN INSTALLATION

   For a minor-version upgrade (such as 9.3.1 to 9.3.4; last number changes),
   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,
   perform initdb, and run the dump file through psql to restore your data.

   In some major releases, the RPMs also support faster upgrade from concrete
   subset of previous releases. You can run the:

         $ postgresql-setup --upgrade-ids

   to see what previous versions you are able to upgrade from. This is much
   faster than a dump and reload. To do a faster upgrade:

    1. shut down the old postmaster running against old data

    2. optionally make a backup of data directory (recommended!)

    3. install the new version's RPMs (install all the ones you had before,
       plus postgresql-upgrade)

    4. as root, run "postgresql-setup --upgrade [--upgrade-from ID]"

    5. update the configuration files /var/lib/pgsql/data/*.conf with any
       customizations you had before (your old configuration files are in old
       data directory or in /var/lib/pgsql/data-old/ if you've done in-place
       upgrade)

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

    7. the postgresql-upgrade package can be removed after the update is
       complete, as can old data directory

   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 old data directory 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.

   Table 1. Sub-package list

   +------------------------------------------------------------------------+
   |        Package        |                  Description                   |
   |-----------------------+------------------------------------------------|
   | postgresql:           | Key client programs and basic documentation    |
   |-----------------------+------------------------------------------------|
   | postgresql-libs:      | Client shared libraries                        |
   |-----------------------+------------------------------------------------|
   | postgresql-server:    | Server executables and data files              |
   |-----------------------+------------------------------------------------|
   | postgresql-test:      | The regression tests and associated files      |
   |-----------------------+------------------------------------------------|
   | postgresql-upgrade:   | Support files for upgrading from previous      |
   |                       | major version                                  |
   |-----------------------+------------------------------------------------|
   | postgresql-docs:      | Full documentation in HTML and PDF, 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, this installation (which usually matches the Red Hat / CentOS /
   Fedora RPM's) install the files like:

   Table 2. Filesystem layout

   +------------------------------------------------------------------------+
   |      Description      |                   Directory                    |
   |-----------------------+------------------------------------------------|
   | Executables           | /usr/bin                                       |
   |-----------------------+------------------------------------------------|
   | Libraries             | /usr/lib64                                     |
   |-----------------------+------------------------------------------------|
   | Documentation         | /usr/share/doc/postgresql/html                 |
   |-----------------------+------------------------------------------------|
   | PDF documentation     | /usr/share/doc/postgresql                      |
   |-----------------------+------------------------------------------------|
   | 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/lib64/pgsql                               |
   |-----------------------+------------------------------------------------|
   | Development Headers   | /usr/include/pgsql                             |
   |-----------------------+------------------------------------------------|
   | Other shared data     | /usr/share/pgsql                               |
   |-----------------------+------------------------------------------------|
   | Regression tests      | /usr/lib64/pgsql/test/regress (in the -test    |
   |                       | package)                                       |
   +------------------------------------------------------------------------+

   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 package contains a systemd "unit" files
   postgresql.service and postgresql@.service. The first file is used solely
   to start the default PostgreSQL server. The second one is designed to
   allow instantiating additional PostgreSQL servers on same machine.

   As an example, let us create a secondary PostgreSQL service called,
   creatively enough, 'postgresql@secondary'. Here are the steps:

    1. Run the following command to create the necessary configuration and to
       initialize the new database cluster

         $ postgresql-setup --initdb \
             --unit postgresql@secondary \
             --new-systemd-unit \
             --datadir /path/to/data/directory \
             --port NNNN


       Replace the "/path/to/data/directory" path and NNNN port with
       appropriate settings that don't conflict with any other PostgreSQL
       setup. Make sure that the parent directory of specified path has
       appropriate ownership and permissions. Note the SELinux issues
       mentioned below.

    2. Edit postgresql.conf in the target 'datadir' directory to change
       settings as needed.

    3. Start the new service with this command:

         # systemctl start postgresql@secondary.service

       You will probably also want to run the command

         # systemctl enable postgresql@secondary.service

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

   When doing a major-version upgrade of a secondary service, add the service
   name to the postgresql-setup command, for example:

         # postgresql-setup --upgrade --unit postgresql@secondary

   This will let postgresql-setup find the correct data directory from the
   proper configuration 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 secondary server 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
   PostgreSQL server has been started (if not, su to root and do

         # systemctl start postgresql.service

   su to postgres, cd to /usr/lib64/pgsql/test/regress 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 /usr/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:

   Table 3. SRPM configuration options

   +------------------------------------------------------------------------+
   |  Variable    Default                      Comment                      |
   | 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 command 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/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 or fail a bug against postgresql component on
   bugzilla.redhat.com.