Installation Procedure

PostgreSQL Installation

For a fresh install or upgrading from previous releases of PostgreSQL:

  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.

    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.

    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.

  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:

    > ./configure
    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:
    > ./configure --help
    Some of the more commonly used ones are:


    Selects a different base directory for the installation of PostgreSQL. The default is /usr/local/pgsql.


    If you want to use locales.


    Allows the use of multibyte character encodings. This is primarily for languages like Japanese, Korean, or Chinese.


    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.)


    Builds the ODBC driver package.


    Builds interface libraries and programs requiring Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.

  3. Compile the program. Type

    > gmake
    The compilation process can take anywhere from 10 minutes to an hour. Your mileage will most certainly vary. Remember to use GNU make.

    The last line displayed will hopefully be

    All of PostgreSQL is successfully made. Ready to install.

  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.)

  5. If you are not upgrading an existing system then skip to step 7.

    You now need to back up your existing database. To dump your fairly recent post-6.0 database installation, type

    > pg_dumpall > db.out
    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.

    Make sure to use the pg_dumpall command from the version you are currently running. 7.0's pg_dumpall will not work on older 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.


    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.

  6. If you are upgrading an existing system then kill the database server now. Type

    > ps ax | grep postmaster
    > ps -e | grep postmaster
    (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:
      263  ?  SW   0:00 (postmaster)
      777  p1 S    0:00 grep postmaster
    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".)
    > kill pid

    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

    > /etc/rc.d/init.d/postgres.init stop

    Also move the old directories out of the way. Type the following:

    > mv /usr/local/pgsql /usr/local/pgsql.old
    (substitute your particular paths).

  7. Install the PostgreSQL executable files and libraries. Type

    > gmake install

    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.

  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:

    > LD_LIBRARY_PATH=/usr/local/pgsql/lib
    > export LD_LIBRARY_PATH
    on sh, ksh, bash, zsh or
    > setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
    on csh or tcsh. You might want to put this into a shell startup file such as /etc/profile.

    On some systems the following is the preferred method, but you must have root access. Edit file /etc/ to add a line

    Then run command /sbin/ldconfig.

    If in doubt, refer to the manual pages of your system. If you later on get a message like

    psql: error in loading shared libraries cannot open shared object file: No such file or directory
    then the above was necessary. Simply do this step then.

  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.

    > mkdir /usr/local/pgsql/data
    > chown postgres /usr/local/pgsql/data
    > su - 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 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.)

  10. The previous 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/postmaster -D /usr/local/pgsql/data
    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
    > nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
        </dev/null >>server.log 2>>1 &

  11. If you are upgrading from an existing installation, dump your data back in:

    > /usr/local/pgsql/bin/psql -d template1 -f db.out
    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.

This concludes the installation proper. To make your life more productive and enjoyable you should look at the following optional steps and suggestions.

To start experimenting with Postgres, set up the paths as explained above and start the server. To create a database, type

> createdb testdb
Then enter
> psql testdb
to connect to that database. At the prompt you can enter SQL commands and start experimenting.