2.3. 7 Steps to Installing PostgreSQL from source on Linux
PostgreSQL is not included with this book, but you may want to visit the PostgreSQL website to see if there is a newer version available. Many FTP sites make the source files for PostgreSQL available for download; a complete list of FTP mirrors can be found at http://www.postgresql.org.
Once you have connected to a PostgreSQL FTP mirror, you will see the stable releases located within a directory beginning with v followed by a version (such as v8.0.1/). There should also be a symbolic link to the most recent stable release’s directory called latest/.
Within this sub-directory is a list of package files. The complete PostgreSQL installation package is named postgresql-[version].tar.gz and should be the largest file in the list. The following sub-packages are also made available for download, and may be installed in any combination (though at least base is required):
- postgresql-[version].tar.gz
The base package contains all of the source code required to build and run the core PostgreSQL.
- postgresql-base-[version].tar.gz
The base package contains the bare minimum of source code required to build and run PostgreSQL.
- postgresql-docs-[version].tar.gz
The docs package contains the PostgreSQL documentation in HTML format. Note that the PostgreSQL man pages are automatically installed with the base package.
- postgresql-opt-[version].tar.gz
The opt package contains several optional extensions to PostgreSQL such as plPerl and some test tools for fsync. However it is our suggestion that you start with the full package listed above.
- postgresql-test-[version].tar.gz
The test package contains the regression test suite. This package is required to run regression tests after compiling PostgreSQL.
2.3.1. 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.
 | You can not use the root user as the PostgreSQL superuser. |
2.3.2. Step 2: Installing the PostgreSQL Source Package
At the time of this writing postgresql-8.0.1 was the stable version of PostgreSQL. Although this book material covers the use of PostgreSQL 8.1.x we felt it was important to show a successful install of PostgreSQL from a stable release. All of the options described in this chapter will work for 8.1.x and all of the examples outside of this chapter were demonstrated on the 8.1dev branch of PostgreSQL.
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.
| If you are a user of a commercial Linux distribution, we strongly suggest that you verify whether or not you have PostgreSQL already installed. On RPM-based systems, such as SuSe, Mandrake, or RedHat, this can be done by using the following command: rpm -qa | grep -i postgres. If you do have PostgreSQL installed, there is a good chance that it is outdated. You will want to download and install the latest version of PostgreSQL available. An RPM installation of PostgreSQL will sometimes install scripts and programs such as postmaster and psql into globally accessible directories. This can cause conflicts with source-built versions, so before installing a new version, be sure to remove the RPM by using the rpm -e <package name> command. |
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.
Example 2-6. Unpacking the PostgreSQL source package
[root@host root]# mv postgresql-8.0.1.tar.gz /usr/local/src [root@host root]# cd /usr/local/src [root@host src]# tar -xzvf postgresql-8.0.1.tar.gz postgresql-8.0.1/ postgresql-8.0.1/doc/ postgresql-8.0.1/doc/src/ postgresql-8.0.1/doc/src/FAQ/ postgresql-8.0.1/doc/src/FAQ/FAQ.html postgresql-8.0.1/doc/src/FAQ/FAQ_DEV.html postgresql-8.0.1/doc/src/FAQ/FAQ_MINGW.html postgresql-8.0.1/doc/src/FAQ/FAQ_brazilian.html postgresql-8.0.1/doc/src/FAQ/FAQ_czech.html postgresql-8.0.1/doc/src/FAQ/FAQ_farsi.html postgresql-8.0.1/doc/src/FAQ/FAQ_french.html postgresql-8.0.1/doc/src/FAQ/FAQ_german.html postgresql-8.0.1/doc/src/FAQ/FAQ_japanese.html postgresql-8.0.1/doc/src/FAQ/FAQ_polish.html postgresql-8.0.1/doc/src/FAQ/FAQ_russian.html postgresql-8.0.1/doc/src/FAQ/FAQ_turkish.html postgresql-8.0.1/doc/src/Makefile postgresql-8.0.1/doc/src/sgml/ postgresql-8.0.1/doc/src/sgml/ref/ postgresql-8.0.1/doc/src/sgml/ref/abort.sgml [...] [root@host root]# chown -R postgres.postgres postgresql-8.0.1
Notice the last command used in Example 2-6. The command is chown -R postgres.postgres postgresql-8.0.1. 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:
- x (extract)
tar will extract from the passed filename (as opposed to creating a new file).
- v (verbose)
tar will print verbose output as files are extracted. You may omit this flag if you do not wish to see each file as it is unpacked.
- z (zipped)
tar will use gunzip to decompress the source. This option assumes that you are using the GNU tools; other versions of tar may not support the z flag. In the event that you are not using the GNU tools, you will need to manually unzip the file using gunzip before you can unpack it with tar.
- f (file)
tar will use the filename following the f parameter to determine which file to extract. In our examples, this file is postgresql-8.0.1.tar.gz.
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-8.0.1). The remaining installation steps will take place in that directory.
2.3.3. 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. The ./configure command assumes that you have readline , zlib and the associated development headers installed.
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:
- --with-perl
This will build PostgreSQL with the plPerl procedural language.
Perl will have to be compiled as a shared library for the --with-perl flag to work correctly.
- --with-python
This will build PostgreSQL with the plPython procedural language.
Python will have to be compiled as a shared library for the --with-python flag to work correctly.
- --with-openssl
Allows the use of encrypted connections to PostgreSQL. This is the server side option. In order to use a client API such as DBD::Pg it will have to have been built against a PostgreSQL that supports ssl connectivity.
You can also specify anything from the following common list of configuration options:
- --prefix=PREFIX
Specifies that files should be installed under the directory provided with PREFIX, instead of the default installation directory (/usr/local/pgsql).
- --exec-prefix=EXEC-PREFIX
Specifies that architecture-dependent executable files should be installed under the directory supplied with EXEC-PREFIX.
- --bindir=DIRECTORY
Specifies that user executable files (such as psql) should be installed into the directory supplied with DIRECTORY.
- --datadir=DIRECTORY
Specifies that the database should install data files used by PostgreSQL's program suite (as well as sample configuration files) into the directory supplied with DIRECTORY. Note that the directory here is not used as an alternate database data directory; it is merely the directory where read-only files used by the program suite are installed.
- --sysconfdir=DIRECTORY
Specifies that system configuration files should be installed into the directory supplied with DIRECTORY. By default, these are put into the etc folder within the specified base installation directory.
- --libdir=DIRECTORY
Specifies that library files should be stored in the directory supplied with DIRECTORY. If you are running Linux, this directory should also be entered into the ld.so.conf file.
- --includedir=DIRECTORY
Specifies that C and C++ header files should be installed into the directory supplied with DIRECTORY. By default, include files are stored in the include folder within the base installation directory.
- --docdir=DIRECTORY
Specifies that documentation files should be installed into the directory supplied with DIRECTORY. This does not include PostgreSQL's man files.
- --mandir=DIRECTORY
Specifies that man files should be installed into the directory supplied with DIRECTORY.
- --with-includes=DIRECTORIES
Specifies that the colon-separated list of directories supplied with DIRECTORIES should be searched with the purpose of locating additional header files.
- --with-libraries=DIRECTORIES
Specifies that the colon-separated list of directories supplied with DIRECTORIES should be searched with the purpose of locating additional libraries. You can also use --with-libs= as an alternative.
- --enable-multibyte
Enables multibyte encoding. Enabling this option allows the support of non-ASCII characters; this is most useful with languages such as Japanese, Korean, and Chinese, which all use nonstandard character encoding.
- --with-pgport=NUMBER
Specifies that the the port number supplied with NUMBER should be used as the default port by PostgreSQL. This can be changed when starting the postmaster application.
- --with-maxbackends=NUMBER
Sets NUMBER as the maximum number of allowed connections (32, by default).
- --with-tcl
Specifies that Tcl support should be included in the installation. This option will install PostgreSQL applications and extensions that require Tcl, such as pgaccess (a popular graphical database client) and the pl/Tcl procedural language.
- --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
Specifies that the Tcl or Tk (depending on the option) configuration file (either tclConfig.sh or tkConfig.sh) is located in the directory supplied with DIRECTORY, instead of the default directory. These two files are installed by Tcl/Tk, and the information within them is required by PostgreSQL's Tcl/Tk interface modules.
- --with-perl
Specifies that the PostgreSQL Perl interface module should be compiled during installation. This module will need to be installed in a directory that is usually owned by root, so you will most likely need to be logged in as the root user to complete installation with this option chosen. This configuration option is only required if you plan to use the pl/Perl procedural language.
- --with-python
Specifies that the PostgreSQL Python interface module should be compiled during installation. As with the --with-perl option, you will most likely need to log in as the root user to complete installation with this option. This option is only required if you plan to use the pl/Python procedural language.
- --with-krb4=DIRECTORY, --with-krb5=DIRECTORY
Enables support for the Kerberos authentication system. The use of Kerberos is not covered in this book.
- --with-krb-srvnam=NAME
Specifies the name of the Kerberos service principal. By default, postgres is set as the service principal name.
- --with-openssl=DIRECTORY
Enables the use of SSL to support encrypted database connections. To build support for SSL, OpenSSL must be configured correctly and installed in the directory supplied with DIRECTORY. This option is required if you plan on using the stunnel tool.
- --enable-syslog
Enables the use of the syslog daemon for logging. You will need to specify that you wish to use syslog for logging at runtime if you wish to use it.
- --enable-debug
Enables the compilation of all PostgreSQL libraries and applications with debugging symbols. This will slow down performance and increase binary file size, but the debugging symbols are useful for developers to help diagnose bugs and problems that can be encountered with PostgreSQL.
- --enable-cassert
Enables assertion checking. This feature slows down performance and should be used only during development of PostgreSQL database itself.
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.
2.3.4. Step 4: Compiling the Source
After using the configure command, you may begin compiling the PostgreSQL source by entering the make command.
| On Linux machines, you should be able to use make instead of gmake. BSD users should use gmake. |
Example 2-7. Compiling the source with GNU make
[postgres@host postgresql-8.0.1]# gmake [root@jd2 postgresql-8.0.1]# make make -C doc all make[1]: Entering directory `/usr/local/src/postgresql-8.0.1/doc' make[1]: Nothing to be done for `all'. make[1]: Leaving directory `/usr/local/src/postgresql-8.0.1/doc' make -C src all make[1]: Entering directory `/usr/local/src/postgresql-8.0.1/src' make -C port all make[2]: Entering directory `/usr/local/src/postgresql-8.0.1/src/port' make[2]: Nothing to be done for `all'. make[2]: Leaving directory `/usr/local/src/postgresql-8.0.1/src/port' make -C timezone all [...]
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.
2.3.5. 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.
Example 2-8. Making regression tests
[postgres@host postgresql-8.0.1]# make check gmake -C doc all gmake[1]: Entering directory /usr/local/src/postgresql-8.0.1/doc' gmake[1]: Nothing to be done for all'. gmake[1]: Leaving directory /usr/local/src/postgresql-8.0.1/doc' [...]
The make 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, make 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.
Example 2-9. Regression check output
======================= 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.
 | You cannot run the regression tests as the root user. Be sure to run make check as the postgres user. |
2.3.6. 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 4.
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.
| If you specified a non-default installation directory in Step 3, use the directory you specified instead of /usr/local/pgsql. |
Example 2-10. The make install command
$ su -c "make install" Password: make -C doc install make[1]: Entering directory /usr/local/src/postgresql-8.0.1/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 "make 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.
2.3.7. 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
| You must login to the system after the /etc/profile file has had environment variables added to it in order for your shell to utilize them. |
Depending on how your system handles shared libraries, you may need to inform the operating system of where your PostgreSQL shared libraries are located. Remember that our platform is Linux and the default shell on Linux is bash. Your Unix may differ and you will have to adjust the following to that system.
In a default installation, shared libraries will be located in /usr/local/pgsql/lib. You will almost certainly have to update your /etc/ld.so.conf to have the path to your PostgreSQL libraries. The /etc/ld.so.conf file is just a text file that looks similar to the following:
Example 2-11. The /etc/ld.so.conf file
[jd@localhost]cat /etc/ld.so.conf
include ld.so.conf.d/*.conf
/usr/local/pgsql/lib
If you take note of the last line we have added the /usr/local/pgsql/lib line. Once you have done so on your machine you need to execute ldconfig to have the changes take effect.