336 lines
16 KiB
Plaintext
336 lines
16 KiB
Plaintext
README.rpm-dist
|
|
-----------------------------------------------------------------------------
|
|
Version 8.1, for the PostgreSQL 8.1.0-1 RPMset.
|
|
Lamar Owen <lamar.owen@wgcr.org>
|
|
-----------------------------------------------------------------------------
|
|
|
|
Contents:
|
|
0.) Quick note about '-i'
|
|
1.) Introduction, QuickStart, and credits
|
|
2.) PostgreSQL RPM packages and rationale
|
|
3.) Starting multiple postmasters
|
|
4.) Regression Testing
|
|
5.) Starting postmaster automatically on startup
|
|
6.) Grand Unified Configuration(GUC) File
|
|
7.) Logging set up
|
|
8.) Rebuilding from the source RPM
|
|
9.) Contrib files
|
|
10.) Further Information Resource
|
|
|
|
QUICK NOTE ABOUT '-i'
|
|
-----------------------------------------------------------------------------
|
|
The postmaster '-i' option is NOT used by default in the initscript shipped
|
|
with these RPMs. Please do NOT modify the initscript to add the '-i' back
|
|
in -- it will get overwritten on the next package upgrade. Rather, see the
|
|
section below on the Grand Unified Configuration file, which includes the
|
|
recommended way to get '-i' functionality. Note that as of PostgreSQL 8.0,
|
|
you don't need '-i' anyway if all you want to allow is local TCP/IP
|
|
connections.
|
|
|
|
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 8.1 of PostgreSQL,
|
|
which is the current version of the RPMs as of this writing. More to the
|
|
point, versions prior to 8.1 are not documented here.
|
|
|
|
Official PostgreSQL Global Development Group RPMs have from version 7.1.2
|
|
on carried a 'PGDG' after the release number. Other RPMsets distributed
|
|
with Linux distributions may have a different release number and initials.
|
|
|
|
It is preferable for the distribution-specific set to be the one used, as
|
|
the PGDG set is intentionally generic. So, if your distro has a set of RPMs,
|
|
use them in preference. If you want to stay up-to-date on the PostgreSQL
|
|
core itself, use the PGDG generic set -- but understand that it is a
|
|
GENERIC set.
|
|
|
|
These RPMs no longer support any sort of upgrading process other than that
|
|
documented in the regular documentation. That is, you must dump, upgrade,
|
|
initdb, and restore your data. Dump first, then remove the old server
|
|
subpackage, install the new package, and restore the data from dump. (A new
|
|
method of running multiple versions of PostgreSQL, along with the capability
|
|
to run multiple postmasters, is in development, but was not ready for this
|
|
release.)
|
|
|
|
SuSE has maintained their own RPMset for some time -- their documentation
|
|
supercedes any found in this file.
|
|
|
|
QUICKSTART
|
|
-----------------------------------------------------------------------------
|
|
For a fresh installation on a recent Red Hat or similar system, a simple
|
|
service postgresql start
|
|
as root will prepare a new database (initdb), and 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.
|
|
|
|
The file /var/lib/pgsql/.bash_profile is now 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 -- in order 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.
|
|
|
|
CREDITS
|
|
-----------------------------------------------------------------------------
|
|
Thomas Lockhart
|
|
Uncle George
|
|
Ryan Kirkpatrick
|
|
Trond Eivind Glomsrd
|
|
Mark Knox
|
|
Mike Mascari
|
|
Nicolas Huillard
|
|
Karl DeBisschop
|
|
Roger Luethi
|
|
Jeff Johnson
|
|
Reinhard Max
|
|
Peter Eisentraut
|
|
Joe Conway
|
|
Andrew Overholt
|
|
David Jee
|
|
Kaj J. Niemi
|
|
|
|
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 clients and libraries, and documentation
|
|
postgresql-libs: Client shared libraries
|
|
postgresql-server: Server executables and data files
|
|
postgresql-devel: Development libraries and include files
|
|
postgresql-jdbc: JARs for the JDBC client library
|
|
postgresql-python: The PygreSQL client library
|
|
postgresql-tcl: Tcl client library (Pgtcl)
|
|
postgresql-test: The regression tests and associated files
|
|
postgresql-docs: Extra documentation, such as the tutorial files
|
|
postgresql-contrib: The contrib source tree, as well as selected binaries
|
|
postgresql-pl: PL/Perl (if possible on this dist), PL/Python, and PL/Tcl
|
|
|
|
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 is no postgresql-perl, postgresql-odbc, postgresql-tk, or
|
|
postgresql-plperl package any longer. This is due to these portions being
|
|
removed from the PostgreSQL source tarball.
|
|
|
|
While PygreSQL was split out from the core PostgreSQL distribution, thanks to
|
|
Kaj's work it is still included as the python subpackage. Also, Pgtcl is
|
|
still included as the tcl subpackage, although it is not part of the core
|
|
distribution anymore.
|
|
|
|
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. The
|
|
Red Hat/Fedora locations are listed below. On SuSE <7.1, substitute 'postgres'
|
|
for 'postgresql' below.
|
|
|
|
However, the RPMs install the files like this:
|
|
Executables: /usr/bin
|
|
Libraries: /usr/lib
|
|
Documentation: /usr/share/doc/postgresql-x.y.z
|
|
Contrib documentation: /usr/share/doc/postgresql-contrib-x.y.z
|
|
Source: not installed
|
|
Data: /var/lib/pgsql/data
|
|
Backup area: /var/lib/pgsql/backup
|
|
Templates: /usr/share/pgsql
|
|
Procedural Languages: /usr/lib/pgsql
|
|
Development Headers: /usr/include/pgsql
|
|
Localization data: /usr/share/locale
|
|
Other shared data: /usr/share/pgsql
|
|
Regression tests: /usr/lib/pgsql/test/regress (in the -test package)
|
|
Tutorial: /usr/lib/pgsql/tutorial (in the -docs package)
|
|
Extra documentation: /usr/share/doc/postgresql-docs-x.y.z
|
|
|
|
On some 64-bit architectures, /usr/lib64 is used instead of /usr/lib.
|
|
|
|
The above list describes the Red Hat/Fedora layout. These locations may
|
|
change for other distributions. Use of 'rpm -ql' for each package is
|
|
recommended as the 'official' information source.
|
|
|
|
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@PostgreSQL.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 targe PGDATA as documented in the main documentation.
|
|
Automatic initdb may or may not work for you, so a manual one is
|
|
preferred. This must be done as user 'postgres'
|
|
5.) Edit postgresql.conf to change the port, address, tcpip settings, etc.
|
|
6.) Start the postmaster with 'service secondary start'.
|
|
|
|
Note that there may be problems with the standard symlink -- consider this
|
|
support experimental at this point in time.
|
|
|
|
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 execute the
|
|
"/etc/rc.d/init.d/postgresql start" init script), cd to
|
|
/usr/lib/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-ports list at postgresql.org.
|
|
|
|
After testing, say "make clean" to remove the files generated by the test
|
|
script.
|
|
|
|
STARTING POSTMASTER AUTOMATICALLY AT SYSTEM STARTUP
|
|
-------------------------------------------------------------------------------
|
|
Red Hat Linux uses 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, with sanity checking, 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 already set up
|
|
a non-root build environment.
|
|
|
|
Install the source RPM with rpm -i, then CD to the rpm building area (on Red
|
|
Hat or Fedora Core this 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
|
|
perl 1 #build the postgresql-perl package.
|
|
tcl 1 #build the postgresql-tcl package.
|
|
jdbc 1 #build the postgresql-jdbc package.
|
|
pls 1 #build the postgresql-pl package.
|
|
test 1 #build the postgresql-test package.
|
|
python 1 #build the postgresql-python package.
|
|
pltcl 1 #build the pltcl portion of the postgresql-pl package.
|
|
plperl 1 #build the plperl portion of the postgresql-pl package.
|
|
ssl 1 #use OpenSSL support.
|
|
kerberos 1 #use Kerberos 5 support.
|
|
nls 1 #build with national language support.
|
|
pam 1 #build with PAM support.
|
|
runselftest 1 #do "make check" during the build.
|
|
|
|
To use these defines, invoke a rebuild like this:
|
|
rpm --rebuild --define 'perl 0' --define 'tcl 0' \
|
|
--define 'test 0' --define 'runselftest 1' --define 'kerberos 0' \
|
|
postgresql-8.1.0-1.src.rpm
|
|
This line would disable the perl, tcl, and test subpackages, enable 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 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
|
|
|
|
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@PostgreSQL.org .
|
|
|
|
SUSE products usually ship with the latest version of PostgreSQL that
|
|
was available at the time they were released. RPMs for newer versions
|
|
of PostgreSQL can be found on the SUSE FTP server and it's mirrors.
|
|
|
|
ftp://ftp.suse.com/pub/projects/postgresql
|
|
http://www.novell.com/products/linuxprofessional/downloads/ftp/int_mirrors.html
|
|
-------------------------------------------------------------------------------
|