- Installation instructions for PostgreSQL 7.0.1.
+ PostgreSQL Installation Instructions
-If you haven't gotten the PostgreSQL distribution, get it from
-ftp.postgresql.org, then unpack it:
+ ------------------------------------------------------------------------
-> gunzip postgresql-7.0.1.tar.gz
-> tar -xf postgresql-7.0.1.tar
-> mv postgresql-7.0.1 /usr/src
+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/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
+/usr/local/pgsql/bin/createdb test
+/usr/local/pgsql/bin/psql test
-Before you start
+The long version is the rest of this document.
-Building PostgreSQL requires GNU make. It will not work with other make
-programs. On GNU/Linux systems GNU make is the default tool, on other
-systems you may find that GNU make is installed under the name gmake. We
-will use that name from now on to indicate GNU make, no matter what name it
-has on your system. To test for GNU make enter
+ ------------------------------------------------------------------------
-> gmake --version
+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.
-If you need to get GNU make, you can find it at ftp://ftp.gnu.org.
+The following prerequisites exist for building PostgreSQL:
-Up to date information on supported platforms is at
-http://www.postgresql.org/docs/admin/ports.htm. In general, most
-Unix-compatible platforms with modern libraries should be able to run
-PostgreSQL. In the doc subdirectory of the distribution are several
-platform-specific FAQ and README documents you might wish to consult if you
-are having trouble.
+ * 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
-Although the minimum required memory for running PostgreSQL can be as little
-as 8MB, there are noticeable speed improvements when expanding memory up to
-96MB or beyond. The rule is you can never have too much memory.
+ gmake --version
-Check that you have sufficient disk space. You will need about 30 Mbytes for
-the source tree during compilation and about 5 Mbytes for the installation
-directory. An empty database takes about 1 Mbyte, otherwise they take about
+ 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.
+
+ * gzip is needed to unpack the distribution in the first place. If you
+ are reading this, you probably already got past that hurdle.
+
+ * The GNU Readline library (for comfortable line editing and command
+ history retrieval) will automatically be used if found. You might wish
+ to install it before proceeding, but it is not essential. (On NetBSD,
+ the "libedit" library is readline-compatible and is used if
+ "libreadline" is not found.)
+
+ * GNU Flex and Bison are needed to build from scratch, but they are *not*
+ required when building from a released source package because
+ pre-generated output files are included in released packages. You will
+ need these programs only when building from a CVS tree 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.28 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.
+
+ * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
+ packages. See the file "doc/FAQ_MSWIN" for details.
+
+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 30 MB
+for the source tree during compilation and about 10 MB for the installation
+directory. An empty database cluster takes about 20 MB, databases take about
five times the amount of space that a flat text file with the same data
-would take. If you run the regression tests you will temporarily need an
-extra 20MB.
+would take. If you are going to run the regression tests you will
+temporarily need an extra 20 MB. Use the "df" command to check for disk
+space.
+
+ ------------------------------------------------------------------------
+
+If You Are Upgrading
+
+The internal data storage format changes with new releases of PostgreSQL.
+Therefore, if you are upgrading an existing installation that does not have
+a version number "7.2.x", you must back up and restore your data as shown
+here. 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.
+
+ 1. Make sure that your database is not updated during or after the backup.
+ 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.
+
+ 2. To dump 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".
+
+ "pg_dumpall" does not save large objects. Check the Administrator's
+ Guide if you need to do this.
+
+ Make sure that you use the "pg_dumpall" command from the version you
+ are currently running. 7.2's "pg_dumpall" should not be used on older
+ databases.
+
+ 3. If you are installing the new version at the same location as the old
+ one then shut down the old server, at the latest before you install the
+ new files:
+
+ kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
+
+ Versions prior to 7.0 do not have this "postmaster.pid" file. If you
+ are using such a version you must find out the process id of the server
+ yourself, for example by typing "ps ax | grep postmaster", and supply
+ it to the "kill" command.
+
+ 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
-To check for disk space, use
+ /etc/rc.d/init.d/postgresql stop
-> df -k
+ works. Another possibility is "pg_ctl stop".
-Considering today's prices for hard disks, getting a large and fast hard
-disk should probably be in your plans before putting a database into
-production use.
+ 4. If you are installing in the same place as the old version then it is
+ also a good idea to move the old installation out of the way, in case
+ you have trouble and need to revert to it. Use a command like this:
+ mv /usr/local/pgsql /usr/local/pgsql.old
+
+After you have installed PostgreSQL 7.2, create a new database directory and
+start the new server. 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
+/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+
+Finally, restore your data with
+
+/usr/local/pgsql/bin/psql -d template1 -f outputfile
+
+using the *new* psql.
+
+You can also install the new version in parallel with the old one to
+decrease the downtime. These topics are discussed at length in the
+Administrator's Guide, which you are encouraged to read in any case.
+
+ ------------------------------------------------------------------------
Installation Procedure
-PostgreSQL Installation
+ 1. Configuration
-For a fresh install or upgrading from previous releases of PostgreSQL:
+ 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
- 1. Create the PostgreSQL superuser account. 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.
+ ./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.
+
+ 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.
+
+ --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
- Running PostgreSQL as root, bin, or any other account with special
- access rights is a security risk; don't do it. The postmaster will in
- fact refuse to start as root.
+ 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.
- You need not do the building and installation itself under this account
- (although you can). You will be told when you need to login as the
- database superuser.
+ --sysconfdir=DIRECTORY
- 2. Configure the source code for your system. It is this step at which you
- can specify your actual installation path for the build process and
- make choices about what gets installed. Change into the src
- subdirectory and type:
+ The directory for various configuration files, "PREFIX/etc" by
+ default.
- > ./configure
+ --libdir=DIRECTORY
+ The location to install libraries and dynamically loadable
+ modules. The default is "EXEC-PREFIX/lib".
- followed by any options you might want to give it. For a first
- installation you should be able to do fine without any. For a complete
- list of options, type:
+ --includedir=DIRECTORY
- > ./configure --help
+ The directory for installing C and C++ header files. The default
+ is "PREFIX/include".
+ --docdir=DIRECTORY
- Some of the more commonly used ones are:
+ Documentation files, except "man" pages, will be installed into
+ this directory. The default is "PREFIX/doc".
- --prefix=BASEDIR
+ --mandir=DIRECTORY
- Selects a different base directory for the installation of
- PostgreSQL. The default is /usr/local/pgsql.
+ The man pages that come with PostgreSQL will be installed under
+ this directory, in their respective "manx" subdirectories. The
+ default is "PREFIX/man".
+
+ 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".
+ Second, the installation layout of the C and C++ header files
+ has been reorganized in the 7.2 release. The public 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 Programmer's Guide for information
+ about how to get at the header files for each interface.
+ 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-locale
- If you want to use locales.
+ Enables locale support. There is a performance penalty associated
+ with locale support, but if you are not in an English-speaking
+ environment you will most likely need this.
+
+ --enable-recode
+
+ Enables single-byte character set recode support. See the
+ Administrator's Guide about this feature.
--enable-multibyte
- Allows the use of multibyte character encodings. This is primarily
- for languages like Japanese, Korean, or Chinese.
+ Allows the use of multibyte character encodings (including
+ Unicode) and character set encoding conversion. Read the
+ Administrator's Guide for details.
+
+ Note that some interfaces (such as Tcl or Java) expect all
+ character strings to be in Unicode, so this option will be
+ required to correctly support these interfaces.
+
+ --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. Some operating systems have this built-in (e.g., Linux,
+ NetBSD, Solaris), for other systems you can download an add-on
+ package from here: http://www.postgresql.org/~petere/gettext.html.
+ 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.
+
+ --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-CXX
+
+ Build the C++ interface library.
--with-perl
- Builds the Perl interface and plperl extension language. Please
- note that the Perl interface needs to be installed into the usual
- place for Perl modules (typically under /usr/lib/perl), so you
- must have root access to perform the installation step. (It is
- often easiest to leave out --with-perl initially, and then build
- and install the Perl interface after completing the installation
- of PostgreSQL itself.)
+ Build the Perl interface module. The Perl interface will be
+ installed at the usual place for Perl modules (typically under
+ "/usr/lib/perl"), so you must have root access to perform the
+ installation step (see step 4). You need to have Perl 5 installed
+ to use this option.
- --with-odbc
+ --with-python
- Builds the ODBC driver package.
+ Build the Python interface module. You need to have root access to
+ be able to install the Python module at its default place
+ ("/usr/lib/pythonx.y"). To be able to use this option, you must
+ have Python installed and your system needs to support shared
+ libraries. If you instead want to build a new complete interpreter
+ binary, you will have to do it manually.
--with-tcl
- Builds interface libraries and programs requiring Tcl/Tk,
- including libpgtcl, pgtclsh, and pgtksh.
+ Builds components that require Tcl/Tk, which are libpgtcl,
+ pgtclsh, pgtksh, PgAccess, and PL/Tcl. But see below about
+ "--without-tk".
- 3. Compile the program. Type
+ --without-tk
- > gmake
+ If you specify "--with-tcl" and this option, then programs that
+ require Tk (pgtksh and PgAccess) will be excluded.
+ --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
- The compilation process can take anywhere from 10 minutes to an hour.
- Your mileage will most certainly vary. Remember to use GNU make.
+ Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
+ contain configuration information needed to build modules
+ interfacing to Tcl or Tk. These files are normally found
+ automatically at their well-known locations, but if you want to
+ use a different version of Tcl or Tk you can specify the directory
+ in which to find them.
- The last line displayed will hopefully be
+ --enable-odbc
- All of PostgreSQL is successfully made. Ready to install.
+ Build the ODBC driver. By default, the driver will be independent
+ of a driver manager. To work better with a driver manager already
+ installed on your system, use one of the following options in
+ addition to this one. More information can be found in the
+ Programmer's Guide.
+ --with-iodbc
- 4. 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. For detailed instructions see Regression
- Test. (Be sure to use the "parallel regress test" method, since the
- sequential method only works with an already-installed server.)
+ Build the ODBC driver for use with iODBC.
- 5. If you are not upgrading an existing system then skip to step 7.
+ --with-unixodbc
- You now need to back up your existing database. To dump your fairly
- recent post-6.0 database installation, type
+ Build the ODBC driver for use with unixODBC.
- > pg_dumpall > db.out
+ --with-odbcinst=DIRECTORY
+ Specifies the directory where the ODBC driver will expect its
+ "odbcinst.ini" configuration file. The default is
+ "/usr/local/pgsql/etc" or whatever you specified as
+ "--sysconfdir". It should be arranged that the driver reads the
+ same file as the driver manager.
- If you wish to preserve object id's (oids), then use the -o option when
- running pg_dumpall. However, unless you have a special reason for doing
- this (such as using OIDs as keys in tables), don't do it.
+ If either the option "--with-iodbc" or the option
+ "--with-unixodbc" is used, this option will be ignored because in
+ that case the driver manager handles the location of the
+ configuration file.
- Make sure to use the pg_dumpall command from the version you are
- currently running. 7.0.1's pg_dumpall will not work on pre-7.0 databases.
- However, if you are still using 6.0, do not use the pg_dumpall script
- from 6.0 or everything will be owned by the PostgreSQL superuser after
- you reload. In that case you should grab pg_dumpall from a later 6.x.x
- release. If you are upgrading from a version prior to Postgres95 v1.09
- then you must back up your database, install Postgres95 v1.09, restore
- your database, then back it up again.
+ --with-java
- Caution
- You must make sure that your database is not updated in the middle of your
- backup. If necessary, bring down postmaster, edit the permissions in file
- /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring
- postmaster back up.
+ Build the JDBC driver and associated Java packages. This option
+ requires Ant to be installed (as well as a JDK, of course). Refer
+ to the JDBC driver documentation in the Programmer's Guide for
+ more information.
- 6. If you are upgrading an existing system then kill the database server
- now. Type
+ --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY]
- > ps ax | grep postmaster
+ Build with support for Kerberos authentication. You can use either
+ Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
+ specifies the root directory of the Kerberos installation;
+ "/usr/athena" is assumed as default. If the relevant header files
+ and libraries are not under a common parent directory, then you
+ must use the "--with-includes" and "--with-libraries" options in
+ addition to this option. If, on the other hand, the required files
+ are in a location that is searched by default (e.g., "/usr/lib"),
+ then you can leave off the argument.
+ "configure" will check for the required header files and libraries
+ to make sure that your Kerberos installation is sufficient before
+ proceeding.
- or
+ --with-krb-srvnam=NAME
- > ps -e | grep postmaster
+ The name of the Kerberos service principal. postgres is the
+ default. There's probably no reason to change this.
+ --with-openssl[=DIRECTORY]
- (It depends on your system which one of these two works. No harm can be
- done by typing the wrong one.) This should list the process numbers for
- a number of processes, similar to this:
+ Build with support for SSL (encrypted) connections. This requires
+ the OpenSSL package to be installed. The "DIRECTORY" argument
+ specifies the root directory of the OpenSSL installation; the
+ default is "/usr/local/ssl".
- 263 ? SW 0:00 (postmaster)
- 777 p1 S 0:00 grep postmaster
+ "configure" will check for the required header files and libraries
+ to make sure that your OpenSSL installation is sufficient before
+ proceeding.
+ --with-pam
- Type the following line, with pid replaced by the process id for
- process postmaster (263 in the above case). (Do not use the id for the
- process "grep postmaster".)
+ Build with PAM (Pluggable Authentication Modules) support.
- > kill pid
+ --enable-syslog
+ Enables the PostgreSQL server to use the syslog logging facility.
+ (Using this option does not mean that you must log with syslog or
+ even that it will be done by default, it simply makes it possible
+ to turn that option on at run time.)
- Tip: On systems which have PostgreSQL started at boot time,
- there is probably a startup file that will accomplish the
- same thing. For example, on a Redhat Linux system one might
- find that
+ --enable-debug
- > /etc/rc.d/init.d/postgres.init stop
+ 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 may 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-cassert
- works.
+ Enables assertion checks in the server, which test for many "can't
+ happen" conditions. This is invaluable for code development
+ purposes, but the tests slow things down a little. 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.
+ Currently, this option is not recommended for production use, but
+ you should have it on for development work or when running a beta
+ version.
- If you used pg_dumpall, move the old directories out of the
- way. Type the following:
+ --enable-depend
- > mv /usr/local/pgsql /usr/local/pgsql.old
+ 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.
+ If you prefer a C or C++ compiler different from the one "configure"
+ picks then you can set the environment variables CC or CXX,
+ respectively, to the program of your choice. Similarly, you can
+ override the default compiler flags with the CFLAGS and CXXFLAGS
+ variables. For example:
- (substitute your particular paths).
+ env CC=/opt/bin/gcc CFLAGS='-O2 -pipe' ./configure
- 7. Install the PostgreSQL executable files and libraries. Type
+ 2. Build
- > gmake install
+ To start the build, type
+ gmake
- You should do this step as the user that you want the installed
- executables to be owned by. This does not have to be the same as the
- database superuser; some people prefer to have the installed files be
- owned by root.
+ (Remember to use GNU make.) The build may take anywhere from 5 minutes
+ to half an hour depending on your hardware. The last line displayed
+ should be
- 8. If necessary, tell your system how to find the new shared libraries.
- How to do this varies between platforms. The most widely usable method
- is to set the environment variable LD_LIBRARY_PATH:
+ All of PostgreSQL is successfully made. Ready to install.
- > LD_LIBRARY_PATH=/usr/local/pgsql/lib
- > export LD_LIBRARY_PATH
+ 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
- on sh, ksh, bash, zsh or
+ gmake check
- > setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+ (This won't work as root; do it as an unprivileged user.) It is
+ possible that some tests fail, due to differences in error message
+ wording or floating point results. The file "src/test/regress/README"
+ and the Administrator's Guide 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
- on csh or tcsh. You might want to put this into a shell startup file
- such as /etc/profile.
+ Note: If you are upgrading an existing system and are going
+ to install the new files over the old ones, then you should
+ have backed up your data and shut down the old server by now,
+ as explained in the Section called If You Are Upgrading
+ above.
- On some systems the following is the preferred method, but you must
- have root access. Edit file /etc/ld.so.conf to add a line
+ To install PostgreSQL enter
- /usr/local/pgsql/lib
+ 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.
- Then run command /sbin/ldconfig.
+ If you built the Perl or Python interfaces and you were not the root
+ user when you executed the above command then that part of the
+ installation probably failed. In that case you should become the root
+ user and then do
- If in doubt, refer to the manual pages of your system. If you later on
- get a message like
+ gmake -C src/interfaces/perl5 install
+ gmake -C src/interfaces/python install
- psql: error in loading shared libraries
- libpq.so.2.1: cannot open shared object file: No such file or directory
+ If you do not have superuser access you are on your own: you can still
+ take the required files and place them in other directories where Perl
+ or Python can find them, but how to do that is left as an exercise.
+ The standard installation provides only the header files needed for
+ client application development. If you plan to do any server-side
+ program development (such as custom functions or data types written in
+ C), then you may want to install the entire PostgreSQL include tree
+ into your target include directory. To do that, enter
- then the above was necessary. Simply do this step then.
+ gmake install-all-headers
- 9. Create the database installation (the working data files). To do this
- you must log in to your PostgreSQL superuser account. It will not work
- as root.
+ This adds a megabyte or two to the installation footprint, and is only
+ useful if you don't plan to keep the whole source tree around for
+ reference. (If you do, you can just use the source's include directory
+ when building server-side software.)
- > mkdir /usr/local/pgsql/data
- > chown postgres /usr/local/pgsql/data
- > su - postgres
- > /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+ 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
- 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 superuser account can
- write to the directory (or create it, if it doesn't already exist)
- before starting initdb. (If you have already been doing the
- installation up to now as the PostgreSQL superuser, you may have to log
- in as root temporarily to create the data directory underneath a
- root-owned directory.)
+ To undo the installation use the command "gmake uninstall". However,
+ this will not remove any created directories.
- 10. The previous step should have told you how to start up the database
- server. Do so now. The command should look something like
+After the installation you can make room by removing the built files from
+the source tree with the "gmake clean" command. 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 from the same source tree you must do this and re-configure for
+each build.
- > /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+If you perform a build and then discover that your configure options were
+wrong, or if you change anything that configure investigates (for example,
+you install GNU Readline), then it's a good idea to do "gmake distclean"
+before reconfiguring and rebuilding. Without this, your changes in
+configuration choices may not propagate everywhere they need to.
+ ------------------------------------------------------------------------
- This will start the server in the foreground. To make it detach to the
- background, you can use the -S option, but then you won't see any log
- messages the server produces. A better way to put the server in the
- background is
+Post-Installation Setup
- > nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
- </dev/null >>server.log 2>>1 &
+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.
- 11. If you did a pg_dumpall, reload your data back in:
+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")
- > /usr/local/pgsql/bin/psql -d template1 -f db.out
+LD_LIBRARY_PATH=/usr/local/pgsql/lib
+export LD_LIBRARY_PATH
+or in "csh" or "tcsh"
- You also might want to copy over the old pg_hba.conf file and any other
- files you might have had set up for authentication, such as password
- files.
+setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
-This concludes the installation proper. To make your life more productive
-and enjoyable you should look at the following optional steps and
-suggestions.
+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.
- * Life will be more convenient if you set up some environment variables.
- First of all you probably want to include /usr/local/pgsql/bin (or
- equivalent) into your PATH. To do this, add the following to your shell
- startup file, such as ~/.bash_profile (or /etc/profile, if you want it
- to affect every user):
+On some systems it might be preferable to set the environment variable
+LD_RUN_PATH *before* building.
- > PATH=$PATH:/usr/local/pgsql/bin
+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
- Furthermore, if you set PGDATA in the environment of the PostgreSQL
- superuser, you can omit the -D for postmaster and initdb.
+then this step was necessary. Simply take care of it then.
- * You probably want to install the man and HTML documentation. Type
+If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run
- > cd /usr/src/pgsql/postgresql-7.0.1/doc
- > gmake install
+/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
- This will install files under /usr/local/pgsql/doc and
- /usr/local/pgsql/man. To enable your system to find the man
- documentation, you need to add a line like the following to a shell
- startup file:
+/sbin/ldconfig -m /usr/local/pgsql/lib
- > MANPATH=$MANPATH:/usr/local/pgsql/man
+instead. Other systems are not known to have an equivalent command.
+ ------------------------------------------------------------------------
- The documentation is also available in Postscript format. If you have a
- Postscript printer, or have your machine already set up to accept
- Postscript files using a print filter, then to print the User's Guide
- simply type
+Environment Variables
- > cd /usr/local/pgsql/doc
- > gunzip -c user.ps.tz | lpr
+If you installed into "/usr/local/pgsql" or some other location that is not
+searched for programs by default, you need to add "/usr/local/pgsql/bin" (or
+whatever you set "--bindir" to in step 1) into your PATH. 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
- Here is how you might do it if you have Ghostscript on your system and
- are writing to a laserjet printer.
+If you are using "csh" or "tcsh", then use this command:
- > gunzip -c user.ps.gz \
- | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
- | lpr
+set path = ( /usr/local/pgsql/bin $path )
+To enable your system to find the man documentation, you need to add a line
+like the following to a shell start-up file:
- Printer setups can vary wildly from system to system. If in doubt,
- consult your manuals or your local expert.
+MANPATH=/usr/local/pgsql/man:$MANPATH
- The Adminstrator's Guide should probably be your first reading if you
- are completely new to PostgreSQL, as it contains information about how
- to set up database users and authentication.
+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.
- * Usually, you will want to modify your computer so that it will
- automatically start the database server whenever it boots. This is not
- required; the PostgreSQL server can be run successfully from
- non-privileged accounts without root intervention.
+ ------------------------------------------------------------------------
- Different systems have different conventions for starting up daemons at
- boot time, so you are advised to familiarize yourself with them. Most
- systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost
- certainly no bad place to put such a command. Whatever you do,
- postmaster must be run by the PostgreSQL superuser (postgres) and not
- by root or any other user. Therefore you probably always want to form
- your command lines along the lines of su -c '...' postgres.
+Getting Started
- It might be advisable to keep a log of the server output. To start the
- server that way try:
+The following is a quick summary of how to get PostgreSQL up and running
+once installed. The Administrator's Guide contains more information.
- > nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+ 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
- Here are a few more operating system specific suggestions.
+ 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.
- o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
- to contain the following single line:
+ 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
- > su postgres -c "/usr/local/pgsql/bin/postmaster -S -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. The previous step should have told you how to start up the database
+ server. Do so now. The command should look something like
- o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
- contain the following lines and make it chmod 755 and chown
- root:bin.
+ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
- #!/bin/sh
- [ -x /usr/local/pgsql/bin/postmaster ] && {
- su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
- -D/usr/local/pgsql/data
- -S -o -F > /usr/local/pgsql/errlog' &
- echo -n ' pgsql'
- }
+ This will start the server in the foreground. To put the server in the
+ background use something like
+ nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+ </dev/null >>server.log 2>&1 </dev/null &
- You may put the line breaks as shown above. The shell is smart
- enough to keep parsing beyond end-of-line if there is an
- expression unfinished. The exec saves one layer of shell under the
- postmaster process so the parent is init.
+ To stop a server running in the background you can type
- o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
- based on the example in contrib/linux/. Then make a softlink to
- this file from /etc/rc.d/rc5.d/S98postgres.init.
+ kill `cat /usr/local/pgsql/data/postmaster.pid`
- * Run the regression tests against the installed server (using the
- sequential test method). If you didn't run the tests before
- installation, you should definitely do it now. For detailed
- instructions see Regression Test.
+ In order to allow TCP/IP connections (rather than only Unix domain
+ socket ones) you need to pass the "-i" option to "postmaster".
+
+ 4. Create a database:
+
+ createdb testdb
+
+ Then enter
-To start experimenting with Postgres, set up the paths as explained above
-and start the server. To create a database, type
+ psql testdb
-> createdb testdb
+ to connect to that database. At the prompt you can enter SQL commands
+ and start experimenting.
+ ------------------------------------------------------------------------
-Then enter
+What Now?
-> psql testdb
+ * 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 Tutorial 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 the Administrator's Guide, which contains information
+ about how to set up the database server, database users, and
+ authentication.
-to connect to that database. At the prompt you can enter SQL commands and
-start experimenting.
+ * 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 Administrator's Guide.
+
+ * Run the regression tests against the installed server (using the
+ sequential test method). If you didn't run the tests before
+ installation, you should definitely do it now. This is also explained
+ in the Administrator's Guide.
+
+ ------------------------------------------------------------------------
+
+Supported Platforms
+
+PostgreSQL has been verified by the developer community to work on the
+platforms listed below. A supported platform generally means that PostgreSQL
+builds and installs according to these instructions and that the regression
+tests pass.
+
+ Note: If you are having problems with the installation on a
+ supported platform, please write to <pgsql-bugs@postgresql.org> or
+ <pgsql-ports@postgresql.org>, not to the people listed here.
+
+ OS Processor Version Reported Remarks
+ AIX RS6000 7.2 2001-12-19, Andreas Zeugswetter see also
+ (<ZeugswetterA@spardat.at>), doc/FAQ_AIX
+ Tatsuo Ishii
+ (<t-ishii@sra.co.jp>)
+ BeOS x86 7.2 2001-11-29, Cyril Velter 5.0.4
+ (<cyril.velter@libertysurf.fr>)
+ BSD/OS x86 7.2 2001-11-27, Bruce Momjian 4.2
+ (<pgman@candle.pha.pa.us>)
+ FreeBSDAlpha 7.2 2001-12-18, Chris Kings-Lynne
+ (<chriskl@familyhealth.com.au>)
+ FreeBSDx86 7.2 2001-11-14, Chris Kings-Lynne
+ (<chriskl@familyhealth.com.au>)
+ HP-UX PA-RISC 7.2 2001-11-29, Joseph Conway 11.00 and 10.20;
+ (<Joseph.Conway@home.com>), Tom see also
+ Lane (<tgl@sss.pgh.pa.us>) doc/FAQ_HPUX
+ IRIX MIPS 7.2 2001-11-28, Luis Amigo 6.5.13, MIPSPro
+ (<lamigo@atc.unican.es>) 7.30
+ Linux Alpha 7.2 2001-11-16, Tom Lane 2.2.18; tested at
+ (<tgl@sss.pgh.pa.us>) SourceForge
+ Linux armv4l 7.2 2001-12-10, Mark Knox 2.2.x
+ (<segfault@hardline.org>)
+ Linux MIPS 7.2 2001-11-15, Hisao Shibuya 2.0.x; Cobalt
+ (<shibuya@alpha.or.jp>) Qube2
+ Linux PlayStation 7.2 2001-12-12, Permaine Cheung #undef
+ 2 <pcheung@redhat.com>) HAS_TEST_AND_SET,
+ slock_t
+ Linux PPC74xx 7.2 2001-11-16, Tom Lane 2.2.18; Apple G3
+ (<tgl@sss.pgh.pa.us>)
+ Linux S/390 7.2 2001-12-12, Permaine Cheung
+ <pcheung@redhat.com>)
+ Linux Sparc 7.2 2001-11-28, Doug McNaught 2.2.19
+ (<doug@wireboard.com>)
+ Linux x86 7.2 2001-11-15, Thomas Lockhart 2.0.x, 2.2.x,
+ (<lockhart@fourpalms.org>) 2.4.x
+ MacOS XPPC 7.2 2001-11-28, Gavin Sherry 10.1.x
+ (<swm@linuxworld.com.au>)
+ NetBSD Alpha 7.2 2001-11-20, Thomas Thai 1.5W
+ (<tom@minnesota.com>)
+ NetBSD arm32 7.1 2001-03-21, Patrick Welche 1.5E
+ (<prlw1@cam.ac.uk>)
+ NetBSD m68k 7.0 2000-04-10, Henry B. Hotz Mac 8xx
+ (<hotz@jpl.nasa.gov>)
+ NetBSD PPC 7.2 2001-11-28, Bill Studenmund 1.5
+ (<wrstuden@netbsd.org>)
+ NetBSD Sparc 7.2 2001-12-03, Matthew Green 32- and 64-bit
+ (<mrg@eterna.com.au>) builds
+ NetBSD VAX 7.1 2001-03-30, Tom I. Helbekkmo 1.5
+ (<tih@kpnQwest.no>)
+ NetBSD x86 7.2 2001-11-28, Bill Studenmund 1.5
+ (<wrstuden@netbsd.org>)
+ OpenBSDSparc 7.2 2001-11-27, Brandon Palmer 3.0
+ (<bpalmer@crimelabs.net>)
+ OpenBSDx86 7.2 2001-11-26, Brandon Palmer 3.0
+ (<bpalmer@crimelabs.net>)
+ Open x86 7.2 2001-11-28, OU-8 Larry Rosenman see also
+ UNIX (<ler@lerctr.org>), UW-7 Olivier doc/FAQ_SCO
+ Prenant (<ohp@pyrenet.fr>)
+ QNX 4 x86 7.2 2001-12-10, Bernd Tegge 4.25; see also
+ RTOS (<tegge@repas-aeg.de>) doc/FAQ_QNX4
+ SolarisSparc 7.2 2001-11-12, Andrew Sullivan 2.6-8; see also
+ (<andrew@libertyrms.com>) doc/FAQ_Solaris
+ Solarisx86 7.2 2001-11-28, Martin Renters 2.8; see also
+ (<martin@datafax.com>) doc/FAQ_Solaris
+ SunOS 4Sparc 7.2 2001-12-04, Tatsuo Ishii
+ (<t-ishii@sra.co.jp>)
+ Tru64 Alpha 7.2 2001-11-26, Alessio Bragadini 5.0; 4.0g with cc
+ UNIX (<alessio@albourne.com>), Bernd and gcc
+ Tegge (<tegge@repas-aeg.de>)
+ Windowsx86 7.2 2001-12-13, Dave Page with Cygwin; see
+ (<dpage@vale-housing.co.uk>), doc/FAQ_MSWIN
+ Jason Tishler
+ (<jason@tishler.net>)
+ Windowsx86 7.2 2001-12-10, Dave Page native is
+ (<dpage@vale-housing.co.uk>) client-side only;
+ see
+ Administrator's
+ Guide
+
+Unsupported Platforms: The following platforms are either known not to work,
+or they used to work in a previous release and we did not receive explicit
+confirmation of a successful test with version 7.2 at the time this list was
+compiled. We include these here to let you know that these platforms *could*
+be supported if given some attention.
+
+ OS Processor Version Reported Remarks
+ DG/UX m88k 6.3 1998-03-01, Brian E Gallew no recent
+ 5.4R4.11 (<geek+@cmu.edu>) reports
+ MkLinux DR1PPC750 7.0 2001-04-03, Tatsuo Ishii 7.1 needs OS
+ (<t-ishii@sra.co.jp>) update?
+ NeXTSTEP x86 6.x 1998-03-01, David Wetzel bit rot
+ (<dave@turbocat.de>) suspected
+ QNX RTOS v6x86 7.2 2001-11-20, Igor Kovalenko patches
+ (<Igor.Kovalenko@motorola.com>) available in
+ archives,
+ but too late
+ for 7.2
+ SCO x86 6.5 1999-05-25, Andrew Merrill 7.2 should
+ OpenServer (<andrew@compclass.com>) work, but no
+ 5 reports; see
+ also
+ doc/FAQ_SCO
+ System V R4m88k 6.2.1 1998-03-01, Doug Winterburn needs new
+ (<dlw@seavme.xroads.com>) TAS spinlock
+ code
+ System V R4MIPS 6.4 1998-10-28, Frank Ridderbusch no recent
+ (<ridderbusch.pad@sni.de>) reports
+ Ultrix MIPS 7.1 2001-03-26 TAS spinlock
+ code not
+ detected
+ Ultrix VAX 6.x 1998-03-01