Update for 7.0.2.

[postgresql] / INSTALL

     Installation instructions for PostgreSQL 7.0.2.

If you haven't gotten the PostgreSQL distribution, get it from
ftp.postgresql.org, then unpack it:

> gunzip postgresql-7.0.2.tar.gz
> tar -xf postgresql-7.0.2.tar
> mv postgresql-7.0.2 /usr/src


Before you start

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


If you need to get GNU make, you can find it at ftp://ftp.gnu.org.

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.

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.

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

To check for disk space, use

> df -k

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.


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:

     --prefix=BASEDIR

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

     --enable-locale

          If you want to use locales.

     --enable-multibyte

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

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

     --with-odbc

          Builds the ODBC driver package.

     --with-tcl

          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, skip to step 7.
     If you are running 7.*, skip to step 6.

     You now need to back up your existing database. To dump your 
     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.2's pg_dumpall should not be used on older
     databases.

                                        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.

      Rather than using pg_dumpall, pg_upgrade can often be used.

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

     > ps ax | grep postmaster


     or

     > 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


          works.

     If you used pg_dumpall, 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/ld.so.conf to add a line

     /usr/local/pgsql/lib


     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
     libpq.so.2.1: 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 did a pg_dumpall, reload 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:

   * 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):

     > PATH=$PATH:/usr/local/pgsql/bin


     Furthermore, if you set PGDATA in the environment of the PostgreSQL
     superuser, you can omit the -D for postmaster and initdb.

   * You probably want to install the man and HTML documentation. Type

     > cd /usr/src/pgsql/postgresql-7.0.2/doc
     > gmake install


     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:

     > MANPATH=$MANPATH:/usr/local/pgsql/man


     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

     > cd /usr/local/pgsql/doc
     > gunzip -c user.ps.tz | lpr


     Here is how you might do it if you have Ghostscript on your system and
     are writing to a laserjet printer.

     > gunzip -c user.ps.gz \
         | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
         | lpr


     Printer setups can vary wildly from system to system. If in doubt,
     consult your manuals or your local expert.

     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.

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

     It might be advisable to keep a log of the server output. To start the
     server that way try:

     > nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &


     Here are a few more operating system specific suggestions.

        o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
          to contain the following single line:

          > su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"


        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.

          #!/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'
          }


          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.

        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.

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

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.