10 Steps to Installing PostgreSQL

Step 1: Creating the “postgres” User

Create a UNIX user account to own and manage the PostgreSQL database files. Typically, this user is named postgres, but it can be named anything that you choose. For consistency throughout the book, the user postgres is considered the PostgreSQL root or superuser.

You will need to have root privileges to create the PostgreSQL superuser. On a Linux machine, you can use the command shown in Example 2-5 to add the postgres user.

$ su - -c "useradd postgres"

Step 2: Installing the PostgreSQL Source Package

Once you have acquired the source for PostgreSQL, you should copy the PostgreSQL source package to a temporary compilation directory. This directory will be the path where you install and configure PostgreSQL. Within this path, you will extract the contents from the tar.gz file and proceed with installation.

Bear in mind that this will not be the location of the installed database files. This is a temporary location for configuration and compilation of the source package itself. If you have downloaded the PostgreSQL package from the Internet, it is probably not saved in your intended compilation directory (unless you explicitly chose to save there). A common convention for building source on UNIX and Linux machines is to build within the /usr/local/src path. You will most likely need root privileges to access this path. As such, the remaining examples in this chapter will involve the root user until otherwise specified.

To unpack PostgreSQL source code on a Linux system, first move (or copy, from the CD) the compressed source file into /usr/local/src (most people move their source files here to keep them separate from their home directories and/or other locations they may keep downloaded files). After moving it to the filesystem location where you wish to unpack it, use tar to unpack the source files. The commands to perform these actions are shown in Example 2-6.

[root@host root]# mv postgresql-7.1.3.tar.gz /usr/local/src
[root@host root]# cd /usr/local/src
[root@host src]# tar -xzvf postgresql-7.1.3.tar.gz
postgresql-7.1.3/
postgresql-7.1.3/ChangeLogs/
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1-7.1.1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC1-to-7.1RC2
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC2-to-7.1RC3
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC3-to-7.1rc4
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta1-to-7.1beta3
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta3-to-7.1beta4
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta4-to-7.1beta5
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta5-to-7.1beta6
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta6-7.1RC1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1rc4-7.1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1.1-7.1.2
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1.2-7.1.3
postgresql-7.1.3/COPYRIGHT
[...]
[root@host root]# chown -R postgres.postgres postgresql-7.1.3

Notice the last command used in Example 2-6. The command is chown -R postgres.postgres postgresql-7.1.3. This command grants the ownership of the PostgreSQL source directory tree to postgres, which in turn enables you to compile PostgreSQL as the postgres user. Once the extraction and ownership change has completed, you can switch to the postgres user to compile PostgreSQL, resulting in all compiled files automatically being owned by postgres.

For reference purposes, the following list is a description of the tar options used to extract the PostgreSQL source distribution:

After you have completed the extraction of the files, switch to the postgres user and change into the newly created directory (e.g., /usr/local/src/postgres-7.1.3). The remaining installation steps will take place in that directory.

Step 3: Configuring the Source Tree

Before compilation, you must configure the source, and specify installation options specific to your needs. This is done with the configure script.

The configure script is also used to check for software dependencies that are required to compile PostgreSQL. As configure checks for dependencies, it will create the necessary files for use with the gmake command.

To use the default installation script, issue the following command: ./configure. To specify options that will enable certain non-default features, append the option to the ./configure command. For a list of all the available configuration options, use ./configure --help

There is a good chance that the default source configuration that configure uses will not be the setup you require. For a well-rounded PostgreSQL installation, we recommend you use at least the following options:

You can also specify anything from the following complete list of configuration options:

If you compile PostgreSQL and find that you are missing a feature, you can return to this step, reconfigure, and continue with the subsequent steps to build and install PostgreSQL. If you choose to come back to this step and reconfigure the PostgreSQL source before installing, be sure to use the gmake clean command from the top-level directory of the source tree (usually, /usr/local/src/postgresql-[version] ). This will remove any leftover object files and partially compiled files.

Step 4: Compiling the Source

After using the configure command, you may begin compiling the PostgreSQL source by entering the gmake command.

[postgres@host postgresql-7.1.3]# gmake
gmake -C doc all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
gmake[1]: Nothing to be done for all'.
gmake[1]: Leaving directory /usr/local/src/postgresql-7.1.3/doc'
gmake -C src all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/src'
gmake -C backend all
gmake[2]: Entering directory /usr/local/src/postgresql-7.1.3/src/backend'
gmake -C utils fmgroids.h
gmake[3]: Entering directory /usr/local/src/postgresql-7.1.3/src/backend/utils'
[...]

At this point, depending on the speed of your machine, you may want to get some coffee because the PostgreSQL compilation could take 10 minutes, an hour, or even more. After the compilation has finished, the following message should appear:

All of PostgreSQL is successfully made.  Ready to install.

Step 5: Regression Testing

Regression tests are an optional but recommended step. The regression tests help verify that PostgreSQL will run as expected after you have compiled the source. The tests check tasks such as standard SQL operations, as well as extended capabilities of PostgreSQL. The regression tests can point out possible (but not necessarily probable) problems which may arise when running PostgreSQL.

If you decide you would like to run the regression tests, do so by using the following command: gmake check, as shown in Example 2-8.

[postgres@host postgresql-7.1.3]# gmake check
gmake -C doc all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
gmake[1]: Nothing to be done for all'.
gmake[1]: Leaving directory /usr/local/src/postgresql-7.1.3/doc'
[...]

The gmake check command will build a test installation of PostgreSQL within the source tree, and display a list of all the checks it is running. As each test completes, the success or failure will be reported. Items that fail the check will have a failed message printed, rather than the successful ok message. If any checks fail, gmake check will display output similar to that found in Example 2-9, though the number of tests failed may be higher on your system than the number in the example.

=======================
 1 of 76 tests failed.
=======================

The differences that caused some tests to fail can be viewed in the
file ./regression.diffs'.  A copy of the test summary that you see
above is saved in the file ./regression.out'.

The files referenced in Example 2-9 (regression.diffs and regression.out) are placed within the source tree at src/test/regress. If the source tree is located in /usr/local/src, the full path to the directory files would be /usr/local/src/postgresql-[version]/src/test/regress.

The regression tests will not always pick up every possible error. This can be due to inconsistencies in locale settings (such as time zone support), or hardware-specific issues (such as floating-point results). As with any application, be sure to perform your own requirements testing while developing with PostgreSQL.

Step 6: Installing Compiled Programs and Libraries

After you have configured and compiled the PostgreSQL source code, it is time to install the compiled libraries, binaries, and data files into a more appropriate home on the system. If you are upgrading from a previous version of PostgreSQL, be sure to back up your database before beginning this step. Information on performing PostgreSQL database backups can be found in Chapter 9.

Installation of the compiled files is accomplished with the commands demonstrated in Example 2-10. When executed in the manner shown in Example 2-10, the su command temporarily logs you in as the root user to execute the required commands. You must have the root password to execute both of the commands shown in Example 2-10.

$ su -c "gmake install"
Password:
gmake -C doc install
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
mkdir /usr/local/pgsql
mkdir /usr/local/pgsql/man
mkdir /usr/local/pgsql/doc
mkdir /usr/local/pgsql/doc/html
[...]
$ su -c "chown -R postgres.postgres /usr/local/pgsql"
Password:  

The su -c "gmake install" command will install the freshly compiled source either into the directory structure you chose in Step 3 with the --prefix configuration option, or, if this was left unspecified, into the default directory of /usr/local/pgsql. The use of the su -c "chown -R postgres.postgres /usr/local/pgsql" command will ensure that the postgres user owns the PostgreSQL installation directories. Using the su -c command lets you save a step by only logging you in as the root user for the duration of the command’s execution.

If you chose to configure the PostgreSQL source with the Perl or Python interface, but did not have root access, you can still install the interfaces manually. Use the commands demonstrated in Example 2-11 to install the Perl and Python modules manually.

$ su -c "gmake -C src/interfaces/perl5 install"
Password:
Password:
gmake: Entering directory /usr/local/src/postgresql-7.1.3/src/interfaces/perl5'
perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Pg
gmake -f Makefile clean
[...]
$ su -c "gmake -C src/interfaces/python install"
Password:
gmake: Entering directory /usr/local/src/postgresql-7.1.3/src/interfaces/python'                                                                  
sed -e 's,@libpq_srcdir@,../../../src/interfaces/libpq,g' \
    -e 's,@libpq_builddir@,../../../src/interfaces/libpq,g' \
    -e 's%@EXTRA_LIBS@% -lz -lcrypt -lresolv -lnsl -ldl -lm -lbsd -lreadline -ltermcap %g' \
    -e 's%@INCLUDES@%-I../../../src/include%g' \
[...]

You may also want to install the header files for PostgreSQL. This is important, because the default installation will only install the header files for client application development. If you are going to be using some of PostgreSQL's advanced functionality, such as user-defined functions or developing applications in C that use the libpq library, you will need this functionality. To install the required header files, perform the commands demonstrated in Example 2-12.

$ su -c "gmake install-all-headers"
Password:
gmake -C src install-all-headers
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/src'
gmake -C include install-all-headers
[...]

Step 7: Setting Environment Variables

The use of the PostgreSQL environment variables is not required. However, they are helpful when performing tasks within PostgreSQL, including starting and shutting down the postmaster processes. The environment variables that should be set are for the man pages and the bin directory. You can do so by adding the following statements into the /etc/profile file. This should work for any sh-based shell, including bash and ksh.

PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
export PATH MANPATH

Depending on how your system handles shared libraries, you may need to inform the operating system of where your PostgreSQL shared libraries are located. Systems such as Linux, FreeBSD, NetBSD, OpenBSD, Irix, HP/UX, and Solaris will most likely not need to do this.

In a default installation, shared libraries will be located in /usr/local/pgsql/lib (this may be different, depending on whether you changed it with the --prefix configuration option). One of the most common ways to accomplish this is to set the LD_LIBRARY_PATH environment variable to /usr/local/pgsql/lib. See Example 2-13 for an example of doing this in Bourne-style shells and Example 2-14 for an example of doing this in csh and tcsh.

$ LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ export LD_LIBRARY_PATH

$ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Step 8: Initializing and Starting PostgreSQL

If you are logged in as the root user, instead of using the su -c command in the previous steps, you will now need to login as the postgres user you added in step 1. Once you are logged in as the postgres user, issue the command shown in Example 2-15.

$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data

The -D option in the previous command is the location where the data will be stored. This location can also be set with the PGDATA environment variable. If you have set PGDATA, the -D option is unnecessary. If you would like to use a different directory to hold these data files, make sure the postgres user account can write to that directory. When you execute initdb you will see something similar to what is shown in Example 2-16.

$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
This database system will be initialized with username "postgres."
This user will own all the data files and must also own the server process.

Creating directory /usr/local/pgsql/data
Creating directory /usr/local/pgsql/data/base
Creating directory /usr/local/pgsql/data/global
Creating directory /usr/local/pgsql/data/pg_xlog
Creating template1 database in /usr/local/pgsql/data/base/1
DEBUG:  database system was shut down at 2001-08-24 16:36:35 PDT
DEBUG:  CheckPoint record at (0, 8)
DEBUG:  Redo record at (0, 8); Undo record at (0, 8); Shutdown TRUE
DEBUG:  NextTransactionId: 514; NextOid: 16384
DEBUG:  database system is in production state
Creating global relations in /usr/local/pgsql/data/global
DEBUG:  database system was shut down at 2001-08-24 16:36:38 PDT
DEBUG:  CheckPoint record at (0, 108)
DEBUG:  Redo record at (0, 108); Undo record at (0, 0); Shutdown TRUE
DEBUG:  NextTransactionId: 514; NextOid: 17199
DEBUG:  database system is in production state
Initializing pg_shadow.
Enabling unlimited row width for system tables.
Creating system views.
Loading pg_description.
Setting lastsysoid.
Vacuuming database.
Copying template1 to template0.

Success. You can now start the database server using:

/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
or
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start

When the initdb command has completed, it will provide you with information on starting the PostgreSQL server. The first command displayed will start postmaster in the foreground. After entering the command as it is shown in Example 2-17, the prompt will be inaccessible until you press CTRL-C on the keyboard to shut down the postmaster process.

$ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
DEBUG:  database system was shut down at 2001-10-12 23:11:00 PST
DEBUG:  CheckPoint record at (0, 1522064)
DEBUG:  Redo record at (0, 1522064); Undo record at (0, 0); Shutdown TRUE
DEBUG:  NextTransactionId: 615; NextOid: 18720
DEBUG:  database system is in production state

Starting PostgreSQL in the foreground is not normally required. We suggest the use of the second command displayed. The second command will start postmaster in the background. It uses pg_ctl to start the postmaster service, as shown in Example 2-18.

$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /tmp/pgsql.log start
postmaster successfully started 

The major difference between the first command and the second command is that the second runs postmaster in the background, as well as redirects any debugging information to /tmp/pgsql.log. For normal operation, it is generally better to run postmaster in the background, with logging enabled.

Step 9: Configuring the PostgreSQL SysV Script

The SysV script will allow the graceful control of the PostgreSQL database through the use of the SysV runlevel system. The SysV script can be used for starting, stopping, and status-checking of PostgreSQL. It is known to work with most Red Hat based versions of Linux, including Mandrake; however, it should work with other SysV systems (e.g., UnixWare, Solaris, etc.) with little modification. The script is named linux. To use it, you will first need to copy the linux script to your init.d directory. You may require root access to do this.

First, change to the directory where you unpacked the PostgreSQL source. In our case, the path to that directory is /usr/local/src/postgresql-7.1.3/. Then, issue a cp command to copy the script from contrib/start-scripts into the init.d directory. Example 2-19 demonstrates how to do this on a Red Hat Linux system.

$ cd /usr/local/src/postgresql-7.1.3/
$ su -c "cp contrib/start-scripts/linux /etc/rc.d/init.d/postgresql"

Example 2-19 arbitrarily re-names the new copy to postgresql; you may call it whatever you prefer, though it is typically named either postgresql, or postgres.

You will need to make the script file executable after copying it. To do so, use the command shown in Example 2-20.

$ su -c "chmod a+x /etc/rc.d/init.d/postgresql"

There are no additional requirements to use the SysV script with Red Hat, if you do not intend on using it to start PostgreSQL automatically (i.e., if you wish to use the script manually). However, if you do wish for the script to startup PostgreSQL automatically when the machine boots up (or changes runlevels), you will need to have the chkconfig program installed. If chkconfig is installed, you will also need to add the following two lines, including the hash (#) symbol, at the beginning of the /etc/rc.d/init.d/postgresql file:

# chkconfig: 345 85 15
# description: PostgreSQL RDBMS

These example numbers should work on your system; however, it is good to know what role they perform. The first group of numbers (345) represent which runlevels PostgreSQL should be started at. The example shown would start PostgreSQL at runlevels 3, 4, and 5. The second group of numbers (85) represent the order in which PostgreSQL should be started within that runlevel, relative to other programs. You should probably keep the second number high, to indicate that it should be started later in the runlevel. The third number (15) represents the order in which PostgreSQL should be shutdown. It is a good idea to keep this number low, representing a shutdown order that is inverse from the startup order. As previously mentioned, the script should work on your system with the numbers provided, but you can change them if it is necessary.

Once these two lines have been added to the script, you can use the commands shown in Example 2-21 on Red Hat and Mandrake Linux distributions to start the PostgreSQL database. Be sure to execute these as the root user.

$ service postgresql start
Starting PostgreSQL: ok
$ service postgresql stop
Stopping PostgreSQL: ok

Step 10: Creating a Database

Now that the PostgreSQL database system is running, you have the option of using the default database, template1. If you create a new database, and you would like all of your consecutive databases to have the same system-wide options, then you should first configure the template1 database to have those options enabled. For instance, if you plan to use the PL/pgSQL language to program, then you should install the PL/pgSQL language into template1 before using createdb. Then when you use the createdb command, the database created will inherit template1’s objects, and thus, inherit the PL/pgSQL language. For more information on installing the PL/pgSQL language into a database, refer to Chapter 11.

The next step will be to create a new database. This will be a simple test database. We do not recommend using the default template1 database for testing purposes. As you have not created any users with database-creation rights, you will want to make sure that you are logged in as the postgres user when adding a new database. You can also create users that are allowed to add databases, which is discussed later in Chapter 10. To create a new database named testdb, enter the command shown in Example 2-22.

$ createdb testdb
CREATE DATABASE 

You should receive a message that says CREATE DATABASE, indicating that creation of the database was successful. You can now use PostgreSQL's command line interface, psql, to access the newly created database. To do so, enter the command shown in Example 2-23.

$ psql testdb

You can now start entering SQL commands (e.g., such as SELECT) at the psql prompt. If you are unfamiliar with psql, please see Chapter 4 for an introduction.

To verify that the database is working correctly, you can issue the command shown in Example 2-24, which should give you a listing of the languages installed in the database.

testdb=# SELECT * FROM pg_language;
 lanname  | lanispl | lanpltrusted | lanplcallfoid | lancompiler
----------+---------+--------------+---------------+-------------
 internal | f       | f            |             0 | n/a
 C        | f       | f            |             0 | /bin/cc
 sql      | f       | f            |             0 | postgres
(3 rows)