905 lines
45 KiB
Plaintext
905 lines
45 KiB
Plaintext
PostgreSQL Installation Instructions
|
|
|
|
This document describes the installation of PostgreSQL from the source
|
|
code distribution. (If you are installing a pre-packaged distribution,
|
|
such as an RPM or Debian package, ignore this document and read the
|
|
packager's instructions instead.)
|
|
__________________________________________________________________
|
|
|
|
Short Version
|
|
|
|
./configure
|
|
gmake
|
|
su
|
|
gmake install
|
|
adduser postgres
|
|
mkdir /usr/local/pgsql/data
|
|
chown postgres /usr/local/pgsql/data
|
|
su - postgres
|
|
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
|
|
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data >logfile 2>&1 &
|
|
/usr/local/pgsql/bin/createdb test
|
|
/usr/local/pgsql/bin/psql test
|
|
|
|
The long version is the rest of this document.
|
|
__________________________________________________________________
|
|
|
|
Requirements
|
|
|
|
In general, a modern Unix-compatible platform should be able to run
|
|
PostgreSQL. The platforms that had received specific testing at the
|
|
time of release are listed in the Section called Supported Platforms
|
|
below. In the "doc" subdirectory of the distribution there are several
|
|
platform-specific FAQ documents you might wish to consult if you are
|
|
having trouble.
|
|
|
|
The following software packages are required for building PostgreSQL:
|
|
|
|
* GNU make is required; other make programs will *not* work. GNU make
|
|
is often installed under the name "gmake"; this document will
|
|
always refer to it by that name. (On some systems GNU make is the
|
|
default tool with the name "make".) To test for GNU make enter
|
|
gmake --version
|
|
It is recommended to use version 3.76.1 or later.
|
|
* You need an ISO/ANSI C compiler. Recent versions of GCC are
|
|
recommendable, but PostgreSQL is known to build with a wide variety
|
|
of compilers from different vendors.
|
|
* tar is required to unpack the source distribution in the first
|
|
place, in addition to either gzip or bzip2.
|
|
* The GNU Readline library (for simple line editing and command
|
|
history retrieval) is used by default. If you don't want to use it
|
|
then you must specify the "--without-readline" option for
|
|
"configure". As an alternative, you can often use the BSD-licensed
|
|
"libedit" library, originally developed on NetBSD. The "libedit"
|
|
library is GNU Readline-compatible and is used if "libreadline" is
|
|
not found, or if "--with-libedit-preferred" is used as an option to
|
|
"configure". If you are using a package-based Linux distribution,
|
|
be aware that you need both the readline and readline-devel
|
|
packages, if those are separate in your distribution.
|
|
* The zlib compression library will be used by default. If you don't
|
|
want to use it then you must specify the "--without-zlib" option
|
|
for "configure". Using this option disables support for compressed
|
|
archives in pg_dump and pg_restore.
|
|
|
|
The following packages are optional. They are not required in the
|
|
default configuration, but they are needed when certain build options
|
|
are enabled, as explained below.
|
|
|
|
* To build the server programming language PL/Perl you need a full
|
|
Perl installation, including the "libperl" library and the header
|
|
files. Since PL/Perl will be a shared library, the "libperl"
|
|
library must be a shared library also on most platforms. This
|
|
appears to be the default in recent Perl versions, but it was not
|
|
in earlier versions, and in any case it is the choice of whomever
|
|
installed Perl at your site.
|
|
If you don't have the shared library but you need one, a message
|
|
like this will appear during the build to point out this fact:
|
|
*** Cannot build PL/Perl because libperl is not a shared library.
|
|
*** You might have to rebuild your Perl installation. Refer to
|
|
*** the documentation for details.
|
|
(If you don't follow the on-screen output you will merely notice
|
|
that the PL/Perl library object, "plperl.so" or similar, will not
|
|
be installed.) If you see this, you will have to rebuild and
|
|
install Perl manually to be able to build PL/Perl. During the
|
|
configuration process for Perl, request a shared library.
|
|
* To build the PL/Python server programming language, you need a
|
|
Python installation with the header files and the distutils module.
|
|
The distutils module is included by default with Python 1.6 and
|
|
later; users of earlier versions of Python will need to install it.
|
|
Since PL/Python will be a shared library, the "libpython" library
|
|
must be a shared library also on most platforms. This is not the
|
|
case in a default Python installation. If after building and
|
|
installing you have a file called "plpython.so" (possibly a
|
|
different extension), then everything went well. Otherwise you
|
|
should have seen a notice like this flying by:
|
|
*** Cannot build PL/Python because libpython is not a shared library.
|
|
*** You might have to rebuild your Python installation. Refer to
|
|
*** the documentation for details.
|
|
That means you have to rebuild (part of) your Python installation
|
|
to supply this shared library.
|
|
If you have problems, run Python 2.3 or later's configure using the
|
|
--enable-shared flag. On some operating systems you don't have to
|
|
build a shared library, but you will have to convince the
|
|
PostgreSQL build system of this. Consult the "Makefile" in the
|
|
"src/pl/plpython" directory for details.
|
|
* If you want to build the PL/Tcl procedural language, you of course
|
|
need a Tcl installation. If you are using a pre-8.4 release of Tcl,
|
|
ensure that it was built without multithreading support.
|
|
* To enable Native Language Support (NLS), that is, the ability to
|
|
display a program's messages in a language other than English, you
|
|
need an implementation of the Gettext API. Some operating systems
|
|
have this built-in (e.g., Linux, NetBSD, Solaris), for other
|
|
systems you can download an add-on package from
|
|
http://developer.postgresql.org/~petere/bsd-gettext/. If you are
|
|
using the Gettext implementation in the GNU C library then you will
|
|
additionally need the GNU Gettext package for some utility
|
|
programs. For any of the other implementations you will not need
|
|
it.
|
|
* Kerberos, OpenSSL, OpenLDAP, and/or PAM, if you want to support
|
|
authentication or encryption using these services.
|
|
|
|
If you are building from a CVS tree instead of using a released source
|
|
package, or if you want to do development, you also need the following
|
|
packages:
|
|
|
|
* GNU Flex and Bison are needed to build a CVS checkout or if you
|
|
changed the actual scanner and parser definition files. If you need
|
|
them, be sure to get Flex 2.5.4 or later and Bison 1.875 or later.
|
|
Other yacc programs can sometimes be used, but doing so requires
|
|
extra effort and is not recommended. Other lex programs will
|
|
definitely not work.
|
|
|
|
If you need to get a GNU package, you can find it at your local GNU
|
|
mirror site (see http://www.gnu.org/order/ftp.html for a list) or at
|
|
ftp://ftp.gnu.org/gnu/.
|
|
|
|
Also check that you have sufficient disk space. You will need about 65
|
|
MB for the source tree during compilation and about 15 MB for the
|
|
installation directory. An empty database cluster takes about 25 MB,
|
|
databases take about five times the amount of space that a flat text
|
|
file with the same data would take. If you are going to run the
|
|
regression tests you will temporarily need up to an extra 90 MB. Use
|
|
the "df" command to check free disk space.
|
|
__________________________________________________________________
|
|
|
|
Upgrading
|
|
|
|
These instructions assume that your existing installation is under the
|
|
"/usr/local/pgsql" directory, and that the data area is in
|
|
"/usr/local/pgsql/data". Substitute your paths appropriately.
|
|
|
|
The internal data storage format typically changes in every major
|
|
release of PostgreSQL. Therefore, if you are upgrading an existing
|
|
installation that does not have a version number of "8.3.x", you must
|
|
back up and restore your data. If you are upgrading from PostgreSQL
|
|
"8.3.x", the new version can use your current data files so you should
|
|
skip the backup and restore steps below because they are unnecessary.
|
|
1. If making a backup, make sure that your database is not being
|
|
updated. This does not affect the integrity of the backup, but the
|
|
changed data would of course not be included. If necessary, edit
|
|
the permissions in the file "/usr/local/pgsql/data/pg_hba.conf" (or
|
|
equivalent) to disallow access from everyone except you.
|
|
To back up your database installation, type:
|
|
pg_dumpall > outputfile
|
|
If you need to preserve OIDs (such as when using them as foreign
|
|
keys), then use the "-o" option when running pg_dumpall.
|
|
To make the backup, you can use the pg_dumpall command from the
|
|
version you are currently running. For best results, however, try
|
|
to use the pg_dumpall command from PostgreSQL 8.3.3, since this
|
|
version contains bug fixes and improvements over older versions.
|
|
While this advice might seem idiosyncratic since you haven't
|
|
installed the new version yet, it is advisable to follow it if you
|
|
plan to install the new version in parallel with the old version.
|
|
In that case you can complete the installation normally and
|
|
transfer the data later. This will also decrease the downtime.
|
|
2. Shut down the old server:
|
|
pg_ctl stop
|
|
On systems that have PostgreSQL started at boot time, there is
|
|
probably a start-up file that will accomplish the same thing. For
|
|
example, on a Red Hat Linux system one might find that
|
|
/etc/rc.d/init.d/postgresql stop
|
|
works.
|
|
3. If restoring from backup, rename or delete the old installation
|
|
directory. It is a good idea to rename the directory, rather than
|
|
delete it, in case you have trouble and need to revert to it. Keep
|
|
in mind the directory might consume significant disk space. To
|
|
rename the directory, use a command like this:
|
|
mv /usr/local/pgsql /usr/local/pgsql.old
|
|
4. Install the new version of PostgreSQL as outlined in the next
|
|
section.
|
|
5. Create a new database cluster if needed. Remember that you must
|
|
execute these commands while logged in to the special database user
|
|
account (which you already have if you are upgrading).
|
|
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
|
|
6. Restore your previous "pg_hba.conf" and any "postgresql.conf"
|
|
modifications.
|
|
7. Start the database server, again from the special database user
|
|
account:
|
|
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
|
|
8. Finally, restore your data from backup with
|
|
/usr/local/pgsql/bin/psql -d postgres -f outputfile
|
|
using the *new* psql.
|
|
|
|
Further discussion appears in the documentation, including instructions
|
|
on how the previous installation can continue running while the new
|
|
installation is installed.
|
|
__________________________________________________________________
|
|
|
|
Installation Procedure
|
|
|
|
1. Configuration
|
|
The first step of the installation procedure is to configure the
|
|
source tree for your system and choose the options you would like.
|
|
This is done by running the "configure" script. For a default
|
|
installation simply enter
|
|
./configure
|
|
This script will run a number of tests to guess values for various
|
|
system dependent variables and detect some quirks of your operating
|
|
system, and finally will create several files in the build tree to
|
|
record what it found. (You can also run "configure" in a directory
|
|
outside the source tree if you want to keep the build directory
|
|
separate.)
|
|
The default configuration will build the server and utilities, as
|
|
well as all client applications and interfaces that require only a
|
|
C compiler. All files will be installed under "/usr/local/pgsql" by
|
|
default.
|
|
You can customize the build and installation process by supplying
|
|
one or more of the following command line options to "configure":
|
|
|
|
--prefix=PREFIX
|
|
Install all files under the directory "PREFIX" instead of
|
|
"/usr/local/pgsql". The actual files will be installed
|
|
into various subdirectories; no files will ever be
|
|
installed directly into the "PREFIX" directory.
|
|
|
|
If you have special needs, you can also customize the
|
|
individual subdirectories with the following options.
|
|
However, if you leave these with their defaults, the
|
|
installation will be relocatable, meaning you can move the
|
|
directory after installation. (The man and doc locations
|
|
are not affected by this.)
|
|
|
|
For relocatable installs, you might want to use
|
|
"configure"'s --disable-rpath option. Also, you will need
|
|
to tell the operating system how to find the shared
|
|
libraries.
|
|
|
|
--exec-prefix=EXEC-PREFIX
|
|
You can install architecture-dependent files under a
|
|
different prefix, "EXEC-PREFIX", than what "PREFIX" was
|
|
set to. This can be useful to share
|
|
architecture-independent files between hosts. If you omit
|
|
this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
|
|
architecture-dependent and independent files will be
|
|
installed under the same tree, which is probably what you
|
|
want.
|
|
|
|
--bindir=DIRECTORY
|
|
Specifies the directory for executable programs. The
|
|
default is "EXEC-PREFIX/bin", which normally means
|
|
"/usr/local/pgsql/bin".
|
|
|
|
--datadir=DIRECTORY
|
|
Sets the directory for read-only data files used by the
|
|
installed programs. The default is "PREFIX/share". Note
|
|
that this has nothing to do with where your database files
|
|
will be placed.
|
|
|
|
--sysconfdir=DIRECTORY
|
|
The directory for various configuration files,
|
|
"PREFIX/etc" by default.
|
|
|
|
--libdir=DIRECTORY
|
|
The location to install libraries and dynamically loadable
|
|
modules. The default is "EXEC-PREFIX/lib".
|
|
|
|
--includedir=DIRECTORY
|
|
The directory for installing C and C++ header files. The
|
|
default is "PREFIX/include".
|
|
|
|
--mandir=DIRECTORY
|
|
The man pages that come with PostgreSQL will be installed
|
|
under this directory, in their respective "manx"
|
|
subdirectories. The default is "PREFIX/man".
|
|
|
|
--with-docdir=DIRECTORY, --without-docdir
|
|
Documentation files, except "man" pages, will be installed
|
|
into this directory. The default is "PREFIX/doc". If the
|
|
option "--without-docdir" is specified, the documentation
|
|
will not be installed by "make install". This is intended
|
|
for packaging scripts that have special methods for
|
|
installing documentation.
|
|
|
|
Note: Care has been taken to make it possible to install PostgreSQL
|
|
into shared installation locations (such as "/usr/local/include")
|
|
without interfering with the namespace of the rest of the system.
|
|
First, the string "/postgresql" is automatically appended to
|
|
datadir, sysconfdir, and docdir, unless the fully expanded directory
|
|
name already contains the string "postgres" or "pgsql". For example,
|
|
if you choose "/usr/local" as prefix, the documentation will be
|
|
installed in "/usr/local/doc/postgresql", but if the prefix is
|
|
"/opt/postgres", then it will be in "/opt/postgres/doc". The public
|
|
C header files of the client interfaces are installed into
|
|
includedir and are namespace-clean. The internal header files and
|
|
the server header files are installed into private directories under
|
|
includedir. See the documentation of each interface for information
|
|
about how to get at the its header files. Finally, a private
|
|
subdirectory will also be created, if appropriate, under libdir for
|
|
dynamically loadable modules.
|
|
|
|
--with-includes=DIRECTORIES
|
|
"DIRECTORIES" is a colon-separated list of directories
|
|
that will be added to the list the compiler searches for
|
|
header files. If you have optional packages (such as GNU
|
|
Readline) installed in a non-standard location, you have
|
|
to use this option and probably also the corresponding
|
|
"--with-libraries" option.
|
|
|
|
Example:
|
|
--with-includes=/opt/gnu/include:/usr/sup/include.
|
|
|
|
--with-libraries=DIRECTORIES
|
|
"DIRECTORIES" is a colon-separated list of directories to
|
|
search for libraries. You will probably have to use this
|
|
option (and the corresponding "--with-includes" option) if
|
|
you have packages installed in non-standard locations.
|
|
|
|
Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
|
|
|
|
--enable-nls[=LANGUAGES]
|
|
Enables Native Language Support (NLS), that is, the
|
|
ability to display a program's messages in a language
|
|
other than English. "LANGUAGES" is a space-separated list
|
|
of codes of the languages that you want supported, for
|
|
example --enable-nls='de fr'. (The intersection between
|
|
your list and the set of actually provided translations
|
|
will be computed automatically.) If you do not specify a
|
|
list, then all available translations are installed.
|
|
|
|
To use this option, you will need an implementation of the
|
|
Gettext API; see above.
|
|
|
|
--with-pgport=NUMBER
|
|
Set "NUMBER" as the default port number for server and
|
|
clients. The default is 5432. The port can always be
|
|
changed later on, but if you specify it here then both
|
|
server and clients will have the same default compiled in,
|
|
which can be very convenient. Usually the only good reason
|
|
to select a non-default value is if you intend to run
|
|
multiple PostgreSQL servers on the same machine.
|
|
|
|
--with-perl
|
|
Build the PL/Perl server-side language.
|
|
|
|
--with-python
|
|
Build the PL/Python server-side language.
|
|
|
|
--with-tcl
|
|
Build the PL/Tcl server-side language.
|
|
|
|
--with-tclconfig=DIRECTORY
|
|
Tcl installs the file "tclConfig.sh", which contains
|
|
configuration information needed to build modules
|
|
interfacing to Tcl. This file is normally found
|
|
automatically at a well-known location, but if you want to
|
|
use a different version of Tcl you can specify the
|
|
directory in which to look for it.
|
|
|
|
--with-gssapi
|
|
Build with support for GSSAPI authentication. On many
|
|
systems, the GSSAPI (usually a part of the Kerberos
|
|
installation) system is not installed in a location that
|
|
is searched by default (e.g., "/usr/include", "/usr/lib"),
|
|
so you must use the options "--with-includes" and
|
|
"--with-libraries" in addition to this option. "configure"
|
|
will check for the required header files and libraries to
|
|
make sure that your GSSAPI installation is sufficient
|
|
before proceeding.
|
|
|
|
--with-krb5
|
|
Build with support for Kerberos 5 authentication. On many
|
|
systems, the Kerberos system is not installed in a
|
|
location that is searched by default (e.g.,
|
|
"/usr/include", "/usr/lib"), so you must use the options
|
|
"--with-includes" and "--with-libraries" in addition to
|
|
this option. "configure" will check for the required
|
|
header files and libraries to make sure that your Kerberos
|
|
installation is sufficient before proceeding.
|
|
|
|
--with-krb-srvnam=NAME
|
|
The default name of the Kerberos service principal (also
|
|
used by GSSAPI). postgres is the default. There's usually
|
|
no reason to change this unless you have a Windows
|
|
environment, in which case it must be set to uppercase
|
|
POSTGRES.
|
|
|
|
--with-openssl
|
|
Build with support for SSL (encrypted) connections. This
|
|
requires the OpenSSL package to be installed. "configure"
|
|
will check for the required header files and libraries to
|
|
make sure that your OpenSSL installation is sufficient
|
|
before proceeding.
|
|
|
|
--with-pam
|
|
Build with PAM (Pluggable Authentication Modules) support.
|
|
|
|
--with-ldap
|
|
Build with LDAP support for authentication and connection
|
|
parameter lookup (see the documentation about client
|
|
authentication and libpq for more information). On Unix,
|
|
this requires the OpenLDAP package to be installed.
|
|
"configure" will check for the required header files and
|
|
libraries to make sure that your OpenLDAP installation is
|
|
sufficient before proceeding. On Windows, the default
|
|
WinLDAP library is used.
|
|
|
|
--without-readline
|
|
Prevents use of the Readline library (and libedit as
|
|
well). This option disables command-line editing and
|
|
history in psql, so it is not recommended.
|
|
|
|
--with-libedit-preferred
|
|
Favors the use of the BSD-licensed libedit library rather
|
|
than GPL-licensed Readline. This option is significant
|
|
only if you have both libraries installed; the default in
|
|
that case is to use Readline.
|
|
|
|
--with-bonjour
|
|
Build with Bonjour support. This requires Bonjour support
|
|
in your operating system. Recommended on Mac OS X.
|
|
|
|
--with-ossp-uuid
|
|
Use the OSSP UUID library when building
|
|
"contrib/uuid-ossp". The library provides functions to
|
|
generate UUIDs.
|
|
|
|
--with-libxml
|
|
Build with libxml (enables SQL/XML support). Libxml
|
|
version 2.6.23 or later is required for this feature.
|
|
|
|
Libxml installs a program "xml2-config" that can be used
|
|
to detect the required compiler and linker options.
|
|
PostgreSQL will use it automatically if found. To specify
|
|
a libxml installation at an unusual location, you can
|
|
either set the environment variable XML2_CONFIG to point
|
|
to the "xml2-config" program belonging to the
|
|
installation, or use the options "--with-includes" and
|
|
"--with-libraries".
|
|
|
|
--with-libxslt
|
|
Use libxslt when building "contrib/xml2". "contrib/xml2"
|
|
relies on this library to perform XSL transformations of
|
|
XML.
|
|
|
|
--enable-integer-datetimes
|
|
Use 64-bit integer storage for datetimes and intervals,
|
|
rather than the default floating-point storage. This
|
|
reduces the range of representable values but guarantees
|
|
microsecond precision across the full range (see the
|
|
documentation about datetime datatypes for more
|
|
information).
|
|
|
|
--disable-spinlocks
|
|
Allow the build to succeed even if PostgreSQL has no CPU
|
|
spinlock support for the platform. The lack of spinlock
|
|
support will result in poor performance; therefore, this
|
|
option should only be used if the build aborts and informs
|
|
you that the platform lacks spinlock support. If this
|
|
option is required to build PostgreSQL on your platform,
|
|
please report the problem to the PostgreSQL developers.
|
|
|
|
--enable-thread-safety
|
|
Make the client libraries thread-safe. This allows
|
|
concurrent threads in libpq and ECPG programs to safely
|
|
control their private connection handles. This option
|
|
requires adequate threading support in your operating
|
|
system.
|
|
|
|
--with-system-tzdata=DIRECTORY
|
|
PostgreSQL includes its own time zone database, which it
|
|
requires for date and time operations. This time zone
|
|
database is in fact compatible with the "zic" time zone
|
|
database provided by many operating systems such as
|
|
FreeBSD, Linux, and Solaris, so it would be redundant to
|
|
install it again. When this option is used, the
|
|
system-supplied time zone database in "DIRECTORY" is used
|
|
instead of the one included in the PostgreSQL source
|
|
distribution. "DIRECTORY" must be specified as an absolute
|
|
path. "/usr/share/zoneinfo" is a likely directory on some
|
|
operating systems. Note that the installation routine will
|
|
not detect mismatching or erroneous time zone data. If you
|
|
use this option, you are advised to run the regression
|
|
tests to verify that the time zone data you have pointed
|
|
to works correctly with PostgreSQL.
|
|
|
|
This option is mainly aimed at binary package distributors
|
|
who know their target operating system well. The main
|
|
advantage of using this option is that the PostgreSQL
|
|
package won't need to be upgraded whenever any of the many
|
|
local daylight-saving time rules change. Another advantage
|
|
is that PostgreSQL can be cross-compiled more
|
|
straightforwardly if the time zone database files do not
|
|
need to be built during the installation.
|
|
|
|
--without-zlib
|
|
Prevents use of the Zlib library. This disables support
|
|
for compressed archives in pg_dump and pg_restore. This
|
|
option is only intended for those rare systems where this
|
|
library is not available.
|
|
|
|
--enable-debug
|
|
Compiles all programs and libraries with debugging
|
|
symbols. This means that you can run the programs through
|
|
a debugger to analyze problems. This enlarges the size of
|
|
the installed executables considerably, and on non-GCC
|
|
compilers it usually also disables compiler optimization,
|
|
causing slowdowns. However, having the symbols available
|
|
is extremely helpful for dealing with any problems that
|
|
might arise. Currently, this option is recommended for
|
|
production installations only if you use GCC. But you
|
|
should always have it on if you are doing development work
|
|
or running a beta version.
|
|
|
|
--enable-profiling
|
|
If using GCC, all programs and libraries are compiled so
|
|
they can be profiled. On backend exit, a subdirectory will
|
|
be created that contains the "gmon.out" file for use in
|
|
profiling. This option is for use only with GCC and when
|
|
doing development work.
|
|
|
|
--enable-cassert
|
|
Enables assertion checks in the server, which test for
|
|
many "cannot happen" conditions. This is invaluable for
|
|
code development purposes, but the tests can slow down the
|
|
server significantly. Also, having the tests turned on
|
|
won't necessarily enhance the stability of your server!
|
|
The assertion checks are not categorized for severity, and
|
|
so what might be a relatively harmless bug will still lead
|
|
to server restarts if it triggers an assertion failure.
|
|
This option is not recommended for production use, but you
|
|
should have it on for development work or when running a
|
|
beta version.
|
|
|
|
--enable-depend
|
|
Enables automatic dependency tracking. With this option,
|
|
the makefiles are set up so that all affected object files
|
|
will be rebuilt when any header file is changed. This is
|
|
useful if you are doing development work, but is just
|
|
wasted overhead if you intend only to compile once and
|
|
install. At present, this option will work only if you use
|
|
GCC.
|
|
|
|
--enable-dtrace
|
|
Compiles with support for the dynamic tracing tool DTrace.
|
|
Operating system support for DTrace is currently only
|
|
available in Solaris.
|
|
|
|
To point to the "dtrace" program, the environment variable
|
|
DTRACE can be set. This will often be necessary because
|
|
"dtrace" is typically installed under "/usr/sbin", which
|
|
might not be in the path. Additional command-line options
|
|
for the "dtrace" program can be specified in the
|
|
environment variable DTRACEFLAGS.
|
|
|
|
To include DTrace support in a 64-bit binary, specify
|
|
DTRACEFLAGS="-64" to configure. For example, using the GCC
|
|
compiler:
|
|
|
|
./configure CC='gcc -m64' --enable-dtrace DTRACEFLAGS='-64' ...
|
|
|
|
Using Sun's compiler:
|
|
|
|
./configure CC='/opt/SUNWspro/bin/cc -xtarget=native64' --enable-dtrace DTRACEFL
|
|
AGS='-64' ...
|
|
|
|
If you prefer a C compiler different from the one "configure"
|
|
picks, you can set the environment variable CC to the program of
|
|
your choice. By default, "configure" will pick "gcc" if available,
|
|
else the platform's default (usually "cc"). Similarly, you can
|
|
override the default compiler flags if needed with the CFLAGS
|
|
variable.
|
|
You can specify environment variables on the "configure" command
|
|
line, for example:
|
|
./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'
|
|
Here is a list of the significant variables that can be set in this
|
|
manner:
|
|
|
|
CC
|
|
C compiler
|
|
|
|
CFLAGS
|
|
options to pass to the C compiler
|
|
|
|
CPP
|
|
C preprocessor
|
|
|
|
CPPFLAGS
|
|
options to pass to the C preprocessor
|
|
|
|
DTRACE
|
|
location of the "dtrace" program
|
|
|
|
DTRACEFLAGS
|
|
options to pass to the "dtrace" program
|
|
|
|
LDFLAGS
|
|
options to pass to the link editor
|
|
|
|
LDFLAGS_SL
|
|
linker options for shared library linking
|
|
|
|
MSGFMT
|
|
"msgfmt" program for native language support
|
|
|
|
PERL
|
|
Full path to the Perl interpreter. This will be used to
|
|
determine the dependencies for building PL/Perl.
|
|
|
|
PYTHON
|
|
Full path to the Python interpreter. This will be used to
|
|
determine the dependencies for building PL/Python.
|
|
|
|
TCLSH
|
|
Full path to the Tcl interpreter. This will be used to
|
|
determine the dependencies for building PL/Tcl.
|
|
|
|
XML2_CONFIG
|
|
"xml2-config" program used to locate the libxml
|
|
installation.
|
|
|
|
YACC
|
|
Yacc program (bison -y if using Bison)
|
|
|
|
2. Build
|
|
To start the build, type
|
|
gmake
|
|
(Remember to use GNU make.) The build will take a few minutes
|
|
depending on your hardware. The last line displayed should be
|
|
All of PostgreSQL is successfully made. Ready to install.
|
|
3. Regression Tests
|
|
If you want to test the newly built server before you install it,
|
|
you can run the regression tests at this point. The regression
|
|
tests are a test suite to verify that PostgreSQL runs on your
|
|
machine in the way the developers expected it to. Type
|
|
gmake check
|
|
(This won't work as root; do it as an unprivileged user.) The file
|
|
"src/test/regress/README" and the documentation contain detailed
|
|
information about interpreting the test results. You can repeat
|
|
this test at any later time by issuing the same command.
|
|
4. Installing The Files
|
|
|
|
Note: If you are upgrading an existing system and are going to
|
|
install the new files over the old ones, be sure to back up your
|
|
data and shut down the old server before proceeding, as explained in
|
|
the Section called Upgrading above.
|
|
To install PostgreSQL enter
|
|
gmake install
|
|
This will install files into the directories that were specified in
|
|
step 1. Make sure that you have appropriate permissions to write
|
|
into that area. Normally you need to do this step as root.
|
|
Alternatively, you could create the target directories in advance
|
|
and arrange for appropriate permissions to be granted.
|
|
You can use gmake install-strip instead of gmake install to strip
|
|
the executable files and libraries as they are installed. This will
|
|
save some space. If you built with debugging support, stripping
|
|
will effectively remove the debugging support, so it should only be
|
|
done if debugging is no longer needed. install-strip tries to do a
|
|
reasonable job saving space, but it does not have perfect knowledge
|
|
of how to strip every unneeded byte from an executable file, so if
|
|
you want to save all the disk space you possibly can, you will have
|
|
to do manual work.
|
|
The standard installation provides all the header files needed for
|
|
client application development as well as for server-side program
|
|
development, such as custom functions or data types written in C.
|
|
(Prior to PostgreSQL 8.0, a separate gmake install-all-headers
|
|
command was needed for the latter, but this step has been folded
|
|
into the standard install.)
|
|
Client-only installation: If you want to install only the client
|
|
applications and interface libraries, then you can use these
|
|
commands:
|
|
gmake -C src/bin install
|
|
gmake -C src/include install
|
|
gmake -C src/interfaces install
|
|
gmake -C doc install
|
|
"src/bin" has a few binaries for server-only use, but they are
|
|
small.
|
|
|
|
Registering eventlog on Windows: To register a Windows eventlog library
|
|
with the operating system, issue this command after installation:
|
|
regsvr32 pgsql_library_directory/pgevent.dll
|
|
|
|
This creates registry entries used by the event viewer.
|
|
|
|
Uninstallation: To undo the installation use the command "gmake
|
|
uninstall". However, this will not remove any created directories.
|
|
|
|
Cleaning: After the installation you can make room by removing the
|
|
built files from the source tree with the command "gmake clean". This
|
|
will preserve the files made by the "configure" program, so that you
|
|
can rebuild everything with "gmake" later on. To reset the source tree
|
|
to the state in which it was distributed, use "gmake distclean". If you
|
|
are going to build for several platforms within the same source tree
|
|
you must do this and re-configure for each build. (Alternatively, use a
|
|
separate build tree for each platform, so that the source tree remains
|
|
unmodified.)
|
|
|
|
If you perform a build and then discover that your "configure" options
|
|
were wrong, or if you change anything that "configure" investigates
|
|
(for example, software upgrades), then it's a good idea to do "gmake
|
|
distclean" before reconfiguring and rebuilding. Without this, your
|
|
changes in configuration choices might not propagate everywhere they
|
|
need to.
|
|
__________________________________________________________________
|
|
|
|
Post-Installation Setup
|
|
|
|
Shared Libraries
|
|
|
|
On some systems that have shared libraries (which most systems do) you
|
|
need to tell your system how to find the newly installed shared
|
|
libraries. The systems on which this is *not* necessary include BSD/OS,
|
|
FreeBSD, HP-UX, IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX (formerly
|
|
Digital UNIX), and Solaris.
|
|
|
|
The method to set the shared library search path varies between
|
|
platforms, but the most widely usable method is to set the environment
|
|
variable LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh",
|
|
"bash", "zsh"):
|
|
LD_LIBRARY_PATH=/usr/local/pgsql/lib
|
|
export LD_LIBRARY_PATH
|
|
|
|
or in "csh" or "tcsh":
|
|
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
|
|
|
|
Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in
|
|
step 1. You should put these commands into a shell start-up file such
|
|
as "/etc/profile" or "~/.bash_profile". Some good information about the
|
|
caveats associated with this method can be found at
|
|
http://www.visi.com/~barr/ldpath.html.
|
|
|
|
On some systems it might be preferable to set the environment variable
|
|
LD_RUN_PATH *before* building.
|
|
|
|
On Cygwin, put the library directory in the PATH or move the ".dll"
|
|
files into the "bin" directory.
|
|
|
|
If in doubt, refer to the manual pages of your system (perhaps "ld.so"
|
|
or "rld"). If you later on get a message like
|
|
psql: error in loading shared libraries
|
|
libpq.so.2.1: cannot open shared object file: No such file or directory
|
|
|
|
then this step was necessary. Simply take care of it then.
|
|
|
|
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you
|
|
can run:
|
|
/sbin/ldconfig /usr/local/pgsql/lib
|
|
|
|
(or equivalent directory) after installation to enable the run-time
|
|
linker to find the shared libraries faster. Refer to the manual page of
|
|
"ldconfig" for more information. On FreeBSD, NetBSD, and OpenBSD the
|
|
command is:
|
|
/sbin/ldconfig -m /usr/local/pgsql/lib
|
|
|
|
instead. Other systems are not known to have an equivalent command.
|
|
__________________________________________________________________
|
|
|
|
Environment Variables
|
|
|
|
If you installed into "/usr/local/pgsql" or some other location that is
|
|
not searched for programs by default, you should add
|
|
"/usr/local/pgsql/bin" (or whatever you set "--bindir" to in step 1)
|
|
into your PATH. Strictly speaking, this is not necessary, but it will
|
|
make the use of PostgreSQL much more convenient.
|
|
|
|
To do this, add the following to your shell start-up file, such as
|
|
"~/.bash_profile" (or "/etc/profile", if you want it to affect every
|
|
user):
|
|
PATH=/usr/local/pgsql/bin:$PATH
|
|
export PATH
|
|
|
|
If you are using "csh" or "tcsh", then use this command:
|
|
set path = ( /usr/local/pgsql/bin $path )
|
|
|
|
To enable your system to find the man documentation, you need to add
|
|
lines like the following to a shell start-up file unless you installed
|
|
into a location that is searched by default:
|
|
MANPATH=/usr/local/pgsql/man:$MANPATH
|
|
export MANPATH
|
|
|
|
The environment variables PGHOST and PGPORT specify to client
|
|
applications the host and port of the database server, overriding the
|
|
compiled-in defaults. If you are going to run client applications
|
|
remotely then it is convenient if every user that plans to use the
|
|
database sets PGHOST. This is not required, however: the settings can
|
|
be communicated via command line options to most client programs.
|
|
__________________________________________________________________
|
|
|
|
Getting Started
|
|
|
|
The following is a quick summary of how to get PostgreSQL up and
|
|
running once installed. The main documentation contains more
|
|
information.
|
|
1. Create a user account for the PostgreSQL server. This is the user
|
|
the server will run as. For production use you should create a
|
|
separate, unprivileged account ("postgres" is commonly used). If
|
|
you do not have root access or just want to play around, your own
|
|
user account is enough, but running the server as root is a
|
|
security risk and will not work.
|
|
adduser postgres
|
|
2. Create a database installation with the "initdb" command. To run
|
|
"initdb" you must be logged in to your PostgreSQL server account.
|
|
It will not work as root.
|
|
root# mkdir /usr/local/pgsql/data
|
|
root# chown postgres /usr/local/pgsql/data
|
|
root# su - postgres
|
|
postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
|
|
The "-D" option specifies the location where the data will be
|
|
stored. You can use any path you want, it does not have to be under
|
|
the installation directory. Just make sure that the server account
|
|
can write to the directory (or create it, if it doesn't already
|
|
exist) before starting "initdb", as illustrated here.
|
|
3. At this point, if you did not use the "initdb" -A option, you might
|
|
want to modify "pg_hba.conf" to control local access to the server
|
|
before you start it. The default is to trust all local users.
|
|
4. The previous "initdb" step should have told you how to start up the
|
|
database server. Do so now. The command should look something like:
|
|
/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
|
|
This will start the server in the foreground. To put the server in
|
|
the background use something like:
|
|
nohup /usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data \
|
|
</dev/null >>server.log 2>&1 </dev/null &
|
|
To stop a server running in the background you can type:
|
|
kill `cat /usr/local/pgsql/data/postmaster.pid`
|
|
5. Create a database:
|
|
createdb testdb
|
|
Then enter
|
|
psql testdb
|
|
to connect to that database. At the prompt you can enter SQL
|
|
commands and start experimenting.
|
|
__________________________________________________________________
|
|
|
|
What Now?
|
|
|
|
* The PostgreSQL distribution contains a comprehensive documentation
|
|
set, which you should read sometime. After installation, the
|
|
documentation can be accessed by pointing your browser to
|
|
"/usr/local/pgsql/doc/html/index.html", unless you changed the
|
|
installation directories.
|
|
The first few chapters of the main documentation are the Tutorial,
|
|
which should be your first reading if you are completely new to SQL
|
|
databases. If you are familiar with database concepts then you want
|
|
to proceed with part on server administration, which contains
|
|
information about how to set up the database server, database
|
|
users, and authentication.
|
|
* Usually, you will want to modify your computer so that it will
|
|
automatically start the database server whenever it boots. Some
|
|
suggestions for this are in the documentation.
|
|
* Run the regression tests against the installed server (using "gmake
|
|
installcheck"). If you didn't run the tests before installation,
|
|
you should definitely do it now. This is also explained in the
|
|
documentation.
|
|
* By default, PostgreSQL is configured to run on minimal hardware.
|
|
This allows it to start up with almost any hardware configuration.
|
|
The default configuration is, however, not designed for optimum
|
|
performance. To achieve optimum performance, several server
|
|
parameters must be adjusted, the two most common being
|
|
shared_buffers and work_mem. Other parameters mentioned in the
|
|
documentation also affect performance.
|
|
__________________________________________________________________
|
|
|
|
Supported Platforms
|
|
|
|
A platform (that is, a CPU architecture and operating system
|
|
combination) is considered supported by the PostgreSQL development
|
|
community if the code contains provisions to work on that platform and
|
|
it has recently been verified to build and pass its regression tests on
|
|
that platform. Currently, most testing of platform compatibility is
|
|
done automatically by test machines in the PostgreSQL Build Farm. If
|
|
you are interested in using PostgreSQL on a platform that is not
|
|
represented in the build farm, but on which the code works or can be
|
|
made to work, you are strongly encouraged to set up a build farm member
|
|
machine so that continued compatibility can be assured.
|
|
|
|
In general, PostgreSQL can be expected to work on these CPU
|
|
architectures: x86, x86_64, IA64, PowerPC, PowerPC 64, S/390, S/390x,
|
|
Sparc, Sparc 64, Alpha, ARM, MIPS, MIPSEL, M68K, and PA-RISC. Code
|
|
support exists for M32R, NS32K, and VAX, but these architectures are
|
|
not known to have been tested recently. It is often possible to build
|
|
on an unsupported CPU type by configuring with "--disable-spinlocks",
|
|
but performance will be poor.
|
|
|
|
PostgreSQL can be expected to work on these operating systems: Linux
|
|
(all recent distributions), Windows (Win2000 SP4 and later), FreeBSD,
|
|
OpenBSD, NetBSD, Mac OS X, AIX, HP/UX, IRIX, Solaris, Tru64 Unix, and
|
|
UnixWare. Other Unix-like systems may also work but are not currently
|
|
being tested. In most cases, all CPU architectures supported by a given
|
|
operating system will work. Look in the "doc/" directory of the source
|
|
distribution to see if there is a FAQ document specific to your
|
|
operating system, particularly if using an older system.
|
|
|
|
If you have installation problems on a platform that is known to be
|
|
supported according to recent build farm results, please report it to
|
|
<pgsql-bugs@postgresql.org>. If you are interested in porting
|
|
PostgreSQL to a new platform, <pgsql-ports@postgresql.org> is the
|
|
appropriate place to discuss that.
|