README.rpm-dist ----------------------------------------------------------------------------- Version 9.0, for the PostgreSQL 9.0 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.0 of PostgreSQL, which is the current version of the RPMs as of this writing. More to the point, versions prior to 9.0 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. Run: service postgresql initdb as root, and it will prepare a new database cluster for you. Then you will need to start PostgreSQL. Again as root, run: service postgresql start 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. 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. 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. UPGRADING AN INSTALLATION ----------------------------------------------------------------------------- For a minor-version upgrade (such as 9.0.1 to 9.0.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 8.3.x to 8.4.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 8.4.x to 9.0.x. This is much faster than a dump and reload. To do an in-place upgrade: * shut down the old postmaster * optionally make a backup of /var/lib/pgsql/data/ * install the new version's RPMs (install all the ones you had before, plus postgresql-upgrade) * as root, run "service postgresql 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 "service postgresql start" * postgresql-upgrade can be removed after the update is complete 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: The contrib source tree, as well as selected binaries postgresql-plperl: PL/Perl procedural language postgresql-plpython: PL/Python procedural language 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) Documentation: /usr/share/doc/postgresql-docs-x.y.z/html Contrib documentation: /usr/share/doc/postgresql-contrib-x.y.z 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 pgsqlrpms-hackers@pgfoundry.org mailing list. MULTIPLE POSTMASTERS ------------------------------------------------------------------------------- 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 named 'secondary' : 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 target PGDATA with 'service secondary initdb'. 5.) Edit postgresql.conf to change the port, address, tcpip settings, etc. 6.) Start the postmaster with 'service secondary start'. 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 postmaster has been started (if not, su to root and do "service postgresql start"), cd to /usr/lib/pgsql/test/regress (or /usr/lib64/pgsql/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 System V Init package. A startup script for PostgreSQL is provided in the server package, as /etc/rc.d/init.d/postgresql. To start the postmaster manually, as root run service postgresql start To shut the postmaster down, service postgresql stop There are other possible commands to this script -- execute 'service postgresql' for a listing. To get this script to run at system startup or any time the system switches into runlevels 3, 4, or 5, run: chkconfig --add postgresql chkconfig --level 345 postgresql on and the proper symlinks will be created. See the chkconfig man page for more information. Note that this is manual -- while the startup script can include tags to allow chkconfig to automatically perform the symlinking, this is not done at this time. 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 the 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. 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' \ postgresql-9.0.2-1.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. There is documentation in /usr/share/doc/postgresql-contrib-VERSION 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.pgsqlrpms.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 pgsqlrpms-hackers@pgfoundry.org -------------------------------------------------------------------------------