Document configure's --with-maxbackends switch.

[postgresql] / doc / src / sgml / install.sgml

<Chapter Id="install">
<Title>Installation</Title>

<Abstract>
<Para>
Complete installation instructions for 
<ProductName>Postgres</ProductName> v6.4.
</Para>
</Abstract>

<Para>
Before installing <ProductName>Postgres</ProductName>, you may wish to visit
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
for up to date information, patches, etc.
</Para>

<Para>
These installation instructions assume:

<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Commands are Unix-compatible. See note below.
</Para>
</ListItem>
<ListItem>
<Para>
Defaults are used except where noted.
</Para>
</ListItem>
<ListItem>
<Para>
User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
</Para>
</ListItem>
<ListItem>
<Para>
The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
<ListItem>
<Para>
The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
like <command>ps</command> and <command>tar</command> may vary wildly 
between platforms on what options you should use.
<Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para>

<Para>
Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document).  They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs.  If you
have GNU <Application>make</Application> installed under the name 
<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
command <command>make</command> instead. That's OK, but
you need to have the GNU form of <Application>make</Application> to succeed with
an installation.
</Para>

<Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>

<Para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/install.htm">
http://www.postgresql.org/docs/admin/install.htm</ulink>.

 In general, most Unix-compatible
platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows.
The rule is you can never have too much memory.
</para>
<Para>
Check that you have sufficient disk space.  You will need about
      30 Mbytes for <filename>/usr/src/pgsql</filename>, 
about 5 Mbytes for <filename>/usr/local/pgsql</filename>
      (excluding your database) and 1 Mbyte for an empty database.
      The database will temporarily grow to about 20 Mbytes during the
      regression tests.  You will also need about 3 Mbytes for the
      distribution tar file.
</Para>

<Para>
      We therefore recommend that during installation and testing you
      have well over 20 Mbytes free under <filename>/usr/local</filename> and another 25 Mbytes
      free on the disk partition containing your database.  Once you
      delete the source files, tar file and regression database, you
      will need 2 Mbytes for <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
      database, plus about five times the space you would require to
      store your database data in a flat file.
</Para>

<Para>
      To check for disk space, use 
<programlisting>
$ df -k
</programlisting>
</para>
</Sect1>

<Sect1>
<Title>Installation Procedure</Title>

<Procedure>
<Title><ProductName>Postgres</ProductName> Installation</Title>

<Para>
For a fresh install or upgrading from previous releases of
<ProductName>Postgres</ProductName>:
</Para>

<Step Performance="required">
<Para>
Read any last minute information and platform specific porting
     notes.  There are some platform specific notes at the end of this
     file for Ultrix4.x, Linux, BSD/OS and NeXT.  There are other
     files in directory <FileName>/usr/src/pgsql/doc</FileName>, including files FAQ-Irix
     and FAQ-Linux.  Also look in directory
<ULink url="ftp://ftp.postgresql.org/pub">ftp://ftp.postgresql.org/pub</ULink>.
     If there is a file called INSTALL in this directory then this
     file will contain the latest installation information.
</Para>

<Para>
     Please note that a "tested" platform in the list given earlier
     simply means that someone went to the effort at some point of making
     sure that a <ProductName>Postgres</ProductName> distribution would compile and run on this
     platform without modifying the code.  Since the current developers
     will not have access to all of these platforms, some of them may not
     compile cleanly and pass the regression tests in the current
     release due to minor problems.  Any such known problems and their
     solutions will be posted in 
<ULink url="ftp://ftp.postgresql.org/pub/INSTALL">ftp://ftp.postgresql.org/pub/INSTALL</ULink>.
</Para>
</Step>

<Step Performance="optional">
<Para>
Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist.
</para>
<para>
The owner of the Postgres files can be any unprivileged user account.
It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights, as that would create a security risk.
</para>
</Step>

<Step Performance="required">
<Para>
Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the
remaining steps in the installation will happen in this account.
</para>
</step>
<Step Performance="required">
<Para>
Ftp file 
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz">
 <filename>ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz</filename></ulink>
 from the Internet.  Store it in your home directory.
</Para>
</Step>

<Step Performance="required">
<Para>
Some platforms use <application>flex</application>.  
If your system uses <application>flex</application> then make sure
     you have a good version.  To check, type 
<programlisting>
$ flex --version
</programlisting>

</Para>

<Para>
     If the <application>flex</application> command is not found then you probably do not need it.
     If the version is 2.5.2 or 2.5.4 or greater then you are okay.  If it
     is 2.5.3 or before 2.5.2 then you will have to upgrade <application>flex</application>.  You may
     get it at 
<ulink url="ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz">ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz</ulink>.
</Para>

<Para>
     If you need <application>flex</application> and don't have it or have the wrong version, then
     you will be told so when you attempt to compile the program.  Feel
     free to skip this step if you aren't sure you need it.  If you do
     need it then you will be told to install/upgrade <application>flex</application> when you try to
     compile <productname>Postgres</productname>.
</Para>

<Para>
You may want to do the entire <application>flex</application> installation from
the root account, though that is not absolutely necessary.
Assuming that you want the installation to place files in the usual default
areas, type the following:
<ProgramListing>
$ su -
$ cd /usr/local/src
ftp prep.ai.mit.edu
ftp> cd /pub/gnu/
ftp> binary
ftp> get flex-2.5.4.tar.gz
ftp> quit
$ gunzip -c flex-2.5.4.tar.gz | tar xvf -
$ cd flex-2.5.4
$ configure --prefix=/usr
$ gmake
$ gmake check
# You must be root when typing the next line:
$ gmake install
$ cd /usr/local/src
$ rm -rf flex-2.5.4
</ProgramListing>
</Para>

<Para>
     This will update files <filename>/usr/man/man1/flex.1</filename>,
 <filename>/usr/bin/flex</filename>,
     <filename>/usr/lib/libfl.a</filename>,
 <filename>/usr/include/FlexLexer.h</filename> and will add a link
     <filename>/usr/bin/flex++</filename> which points to flex.
</Para>
</Step>

<Step Performance="required">
<Para>
If you are not upgrading an existing system then skip to 
<xref linkend="newdirs">.
If you are upgrading an existing system then back up your database.
     For alpha- and beta-level releases, the database format is liable
     to change, often every few weeks, with no notice besides a quick comment
     in the HACKERS mailing list.  Full releases always require a dump/reload
     from previous releases.  It is therefore a bad idea to skip this
     step.  
</para>
<tip>
<para>
Do not use the <application>pg_dumpall</application> 
script from v6.0 or everything
     will be owned by the <ProductName>Postgres</ProductName> super user.
</para>
</tip>

<para>
To dump your fairly recent post-v6.0 database installation, type

<programlisting>
$ pg_dumpall -z > db.out
</programlisting>
</para>
<para>
To use the latest <application>pg_dumpall</application> script on your
existing older database before upgrading <productname>Postgres</productname>,
pull the most recent version of <application>pg_dumpall</application>
from the new distribution:

<ProgramListing>
$ cd
$ gunzip -c postgresql-v6.4.tar.gz \
    | tar xvf - src/bin/pg_dump/pg_dumpall
$ chmod a+x src/bin/pg_dump/pg_dumpall
$ src/bin/pg_dump/pg_dumpall -z > db.out
$ rm -rf src
</ProgramListing>
</Para>

<Para>
     If you wish to preserve object id's (oids), then use the -o
     option when running <application>pg_dumpall</application>.  
However, unless you have a
     special reason for doing this (such as using OIDs as keys
in tables), don't do it.
</Para>

<Para>
     If the <application>pg_dumpall</application> command
 seems to take a long time and you think
     it might have died, then, from another terminal, type
<programlisting>
$ ls -l db.out
</programlisting>
     several times to see if the size of the file is growing.
</Para>

<Para>
     Please note that if you are upgrading from a version prior to
     <ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
 install
     <ProductName>Postgres95</ProductName> v1.09, restore your database,
 then back it up again.
     You should also read the release notes which should cover any
 release-specific issues.
</Para>

<caution>
<Para>
     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 <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
 to allow only you on, then
     bring <application>postmaster</application> back up.
</Para>
</caution>

</Step>

<Step Performance="required">
<Para>
If you are upgrading an existing system then kill the postmaster.  Type
<ProgramListing>
$ ps -ax | grep postmaster
</ProgramListing>

     This should list the process numbers for a number of processes.  Type
     the following line, with <replaceable>pid</replaceable>
 replaced by the process id for process
     <literal>postmaster</literal>.  
(Do not use the id for process "grep postmaster".)  Type
<programlisting>
$ kill <replaceable>pid</replaceable>
</programlisting>
to actually stop the process.

<tip>
<para>
On systems which have <productname>Postgres</productname> started at boot time, there
is probably a startup file which will accomplish the same thing. For example, on my
Linux system I can type
<programlisting>
$ /etc/rc.d/init.d/postgres.init stop
</programlisting>
to halt <productname>Postgres</productname>.
</para>
</tip>
</Para>
</Step>

<Step Performance="required">
<Para>
If you are upgrading an existing system then move the old directories
     out of the way.  If you are short of disk space then you may have to
     back up and delete the directories instead.  If you do this, save the
     old database in the <filename>/usr/local/pgsql/data</filename> directory tree.  At a
     minimum, save file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
</Para>

<Para>
     Type the following:
<programlisting>
$ su -
$ cd /usr/src
$ mv pgsql pgsql_6_0
$ cd /usr/local
$ mv pgsql pgsql_6_0
$ exit
</programlisting>
</Para>

<Para>
     If you are not using <filename>/usr/local/pgsql/data</filename>
 as your data directory
     (check to see if environment variable PGDATA is set to something
     else) then you will also want to move this directory in the same
     manner.
</Para>
</Step>

<Step Performance="required" id="newdirs">
<Para>
  Make new source and install directories.  The actual paths can be
     different for your installation but you must be consistent throughout this procedure.
</para>
<note>
<para>
There are two places in this installation procedure where you will have an opportunity
to specify installation locations for programs, libraries, documentation, and other files.
Usually it is sufficient to specify these at the <command>make install</command> stage
of installation.
</para>
</note>

<para>
     Type
<ProgramListing>
$ su
$ cd /usr/src
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ cd /usr/local
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ exit
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 Unzip and untar the new source file.  Type
<ProgramListing>
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 Configure the source code for your system.  It is this step at which
     you can specify your actual installation path for
     the build process (see the --prefix option below).  Type
<ProgramListing>
$ cd /usr/src/pgsql/src
$ ./configure [ <replaceable>options</replaceable> ]
</ProgramListing>
</Para>

<substeps>

<Step Performance="optional">
<Para>
     Among other chores, the configure script selects a system-specific
     "template" file from the files provided in the template subdirectory.
     If it cannot guess which one to use for your system, it will say so and
     exit.  In that case you'll need to figure out which one to use and run
     configure again, this time giving the 
<option>--with-template=TEMPLATE</option> option to
     make the right file be chosen.

<note>
<title>Please Report Problems</title>

<para>
If your system is not automatically recognized by configure and you have to do this, please
     send email to 
<ulink url="mailto:scrappy@hub.org">scrappy@hub.org</ulink> with the output of the program
     <application>./config.guess</application>. Indicate what the template file should be.
</para>
</note>

</Para>
</step>
<Step Performance="optional">
<Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config">
for details. However, for a plain-vanilla first installation with no extra
options like multi-byte character support or locale collation support it may
be adequate to have chosen the installation areas and to run configure without
extra options specified.

     The configure script accepts many additional options that you can use
     if you don't like the default configuration.  To see them all, type
<ProgramListing>
     ./configure --help
</ProgramListing>
     Some of the more commonly used ones are:
<ProgramListing>
       --prefix=BASEDIR   Selects a different base directory for the
                          installation of the <ProductName>Postgres</ProductName> configuration.
                          The default is /usr/local/pgsql.
       --with-template=TEMPLATE
                          Use template file TEMPLATE - the template
                          files are assumed to be in the directory
                          src/template, so look there for proper values.
       --with-tcl         Build interface libraries and programs requiring
                          Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
       --with-perl        Build the Perl interface library.
       --with-odbc        Build the ODBC driver package.
       --enable-hba       Enables Host Based Authentication (DEFAULT)
       --disable-hba      Disables Host Based Authentication
       --enable-locale    Enables USE_LOCALE
       --enable-cassert   Enables ASSERT_CHECKING
       --with-CC=compiler
                          Use a specific C compiler that the configure
                          script cannot find.
       --with-CXX=compiler
       --without-CXX
                          Use a specific C++ compiler that the configure
                          script cannot find, or exclude C++ compilation
                          altogether.   (This only affects libpq++ at
                          present.)
</ProgramListing>
</Para>
</step>
<Step Performance="required">
<Para>
Here is the configure script used on a Sparc Solaris 2.5 system
 with <filename>/opt/postgres</filename> specified as
 the installation base directory:

<ProgramListing>
$ ./configure --prefix=/opt/postgres \
    --with-template=sparc_solaris-gcc --with-pgport=5432 \
    --enable-hba --disable-locale
</ProgramListing>

<tip>
<para>
     Of course, you may type these three lines all
     on the same line.
</para>
</tip>

</Para>
</Step>

</substeps>
</step>
<Step Performance="required">
<Para>
Install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type

<ProgramListing>
$ cd /usr/src/pgsql/doc
$ gmake install
</ProgramListing>
</para>
<para>
The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory.
</para>
</step>
<Step Performance="required">
<Para>
Compile the program.  Type

<ProgramListing>
$ cd /usr/src/pgsql/src
$ gmake all >& make.log &
$ tail -f make.log
</ProgramListing>
</Para>

<Para>
     The last line displayed will hopefully be 
<programlisting>
All of PostgreSQL is successfully made. Ready to install.
</programlisting>

  At this point, or earlier
     if you wish, type control-C to get out of tail.  (If you have
     problems later on you may wish to examine file make.log for
     warning and error messages.)

<note>
<para>
You will probably find a number of warning
     messages in make.log.  Unless you have problems later on, these
     messages may be safely ignored.
</para>
</note>
</para>
<Para>
     If the compiler fails with a message stating that 
the <application>flex</application> command
     cannot be found then install <application>flex</application> as described earlier.
  Next,
     change directory back to this directory, type 
<programlisting>
$ make clean
</programlisting>
then recompile again.
</Para>

<Para>
     Compiler options, such as optimization and debugging, may 
     be specified on the command line using the COPT variable.
     For example, typing
<ProgramListing>
$ gmake COPT="-g" all >& make.log &
</ProgramListing>
     would invoke your compiler's <option>-g</option> option in all steps of the
     build.  See <filename>src/Makefile.global.in</filename> for further details.
</Para>
</Step>

<Step Performance="required">
<Para>
 Install the program.  Type
<ProgramListing>
$ cd /usr/src/pgsql/src
$ gmake install >& make.install.log &
$ tail -f make.install.log
</ProgramListing>
</Para>

<Para>
     The last line displayed will be 
<programlisting>
gmake[1]: Leaving directory `/usr/src/pgsql/src/man'
</programlisting>
At this point, or earlier if you wish,
     type control-C to get out of tail.
</Para>
</Step>

<Step Performance="required">
<Para>
If necessary, tell your system how to find the new shared libraries.  You can
do <emphasis>one</emphasis> of the following, preferably the first:
</para>
<SubSteps>
<Step Performance="optional">
<Para>
       As root, edit file <filename>/etc/ld.so.conf</filename>.  Add a line
<programlisting>
<FileName>/usr/local/pgsql/lib</FileName>
</programlisting>
to the file.  Then run command <Command>/sbin/ldconfig</Command>.
</Para>
</Step>

<Step Performance="optional">
<Para>
       In a bash shell, type
<ProgramListing>
    export LD_LIBRARY_PATH=/usr/local/pgsql/lib
</ProgramListing>
</Para>
</Step>
<Step Performance="optional">
<Para>
       In a csh shell, type
<ProgramListing>
    setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</ProgramListing>
</para>
</Step>
</SubSteps>

<Para>
     Please note that the above commands may vary wildly for different
     operating systems.  Check the platform specific notes, such as
     those for Ultrix4.x or and for non-ELF Linux.
</Para>

<Para>
     If, when you create the database, you get the message 
<programlisting>
pg_id: can't load library 'libpq.so'
</programlisting>
 then the above step was necessary.  Simply
     do this step, then try to create the database again.
</Para>
</Step>

   <Step Performance="optional">
    <Para>
     If you used the <option>--with-perl</option> option to configure, check
     the install log to see whether the Perl module was actually installed.
     If you've followed our advice to make the Postgres files be owned by
     an unprivileged userid, then the Perl module won't have been installed,
     for lack of write privileges on the Perl library directories.  You can
     complete its installation, either now or later, by becoming the user that
     does own the Perl library (often root) (via <command>su</command>) and doing
     <ProgramListing>
      $ cd /usr/src/pgsql/src/interfaces/perl5
      $ gmake install
     </ProgramListing>
    </Para>
   </Step>
   
   <Step Performance="required">
    <Para>
     If it has not already been done, then prepare account <literal>postgres</literal>
     for using <ProductName>Postgres</ProductName>.
     Any account that will use <ProductName>Postgres</ProductName> must
     be similarly prepared. 
    </para>
    <para>
     There are several ways to influence the runtime environment of the
     <ProductName>Postgres</ProductName>
     server. Refer to the <citetitle>Administrator's Guide</citetitle>
     for more information.
     <note>
      <para>
       The following instructions are for a
       bash/sh shell.  Adapt accordingly for other shells.
      </para>
     </note>
    </Para>
    
    <substeps>
     
     <Step Performance="required">
      <Para>
       Add the following lines to your login environment:
       
       shell, <filename>~/.bash_profile</filename>:
       <ProgramListing>
        PATH=$PATH:/usr/local/pgsql/bin
        MANPATH=$MANPATH:/usr/local/pgsql/man
        PGLIB=/usr/local/pgsql/lib
        PGDATA=/usr/local/pgsql/data
        export PATH MANPATH PGLIB PGDATA
       </ProgramListing>
      </Para>
     </step>
     <Step Performance="required">
      <para>
       Several regression tests could fail if the user's locale collation
       scheme is different from that of standard C locale.
      </para>
      <para>
       If you configure and compile <ProductName>Postgres</ProductName>
       with the <option>--enable-locale</option> option then
       set locale environment to C (or unset all LC_* variables)
       by putting these additional lines to your login environment
       before starting postmaster:
       <ProgramListing>
        LC_COLLATE=C
        LC_CTYPE=C
        LC_COLLATE=C
        export LC_COLLATE LC_CTYPE LC_COLLATE
       </ProgramListing>
       
       <ProgramListing>
        
       </ProgramListing>
      </para>
     </step>

     <Step Performance="required">
      <Para>
       Make sure that you have defined these variables before continuing
       with the remaining steps.  The easiest way to do this is to type:
       <ProgramListing>
        $ source ~/.bash_profile
       </ProgramListing>
      </Para>
     </Step>
     
    </substeps>
   </step>

<Step Performance="required">
<Para>
 Create the database installation from your <ProductName>Postgres</ProductName> 
superuser account (typically account <literal>postgres</literal>).

<Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole.  Type
<ProgramListing>
$ initdb
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 Set up permissions to access the database system.  Do this by editing
     file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.  The instructions are
     included in the file.  (If your database is not located in the
     default location, i.e. if <envar>PGDATA</envar> is set to point elsewhere, then the
     location of this file will change accordingly.)  This file should be
     made read only again once you are finished.

     If you are upgrading from v6.0 or later you can copy file <filename>pg_hba.conf</filename> from
     your old database on top of the one in your new database, rather than
     redoing the file from scratch.
</Para>
</Step>

<Step Performance="required">
<para>
Briefly test that the backend will start and run by running it from
the command line.
</para>
<substeps>

<Step Performance="required">
<para>
     Start the postmaster daemon running in the background by typing
<ProgramListing>
$ cd
$ postmaster -i
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<para>
Create a database by typing
<ProgramListing>
$ createdb
</ProgramListing>
</para>
</step>
<Step Performance="required">
<para>
Connect to the new database:
<ProgramListing>
$ psql
</ProgramListing>
</para>
</step>
<Step Performance="required">
<para>
And run a sample query:
<ProgramListing>
postgres=> SELECT datetime 'now';
</ProgramListing>
</para>
</step>
<Step Performance="required">
<para>
Exit <application>psql</application>:
<ProgramListing>
postgres=> \q
</ProgramListing>
</para>
</step>
<Step Performance="required">
<para>
Remove the test database (unless you will want to use it later for other tests):
<ProgramListing>
$ destroydb
</ProgramListing>
</para>
</step>
</substeps>
</step>
<Step Performance="required">
<Para>
     Run postmaster in the background from your <ProductName>Postgres</ProductName> 
superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application> 
from the root account!</emphasis>
</para>
<Para>
Usually, you will want to modify
     your computer so that it will automatically start postmaster whenever
    it boots. It is not required; the <ProductName>Postgres</ProductName> 
server can
be run successfully from non-privileged accounts without root intervention.
</para>
<para>
     Here are some suggestions on how to do this, contributed by various
     users.
</para>
<para>
     Whatever you do, postmaster must be run by 
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
<emphasis>and not by root</emphasis>.
This is why all of the examples below start by switching user
     (su) to postgres.  These commands also take into account the fact
     that environment variables like PATH and PGDATA may not be set properly.

     The examples are as follows.  Use them with extreme caution.

<itemizedlist mark="bullet">
<listitem>
<para>
If you are installing from a non-privileged account and have no root access, then
start the <application>postmaster</application> and send it to the background:

<ProgramListing>
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
</para>
</listitem>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
          2.5.1 to contain the following single line:
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
</para>
</listitem>

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

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

          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.
</para>
</listitem>

<listitem>
<para>
In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from
 <filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
</para>
</listitem>

<listitem>
<para>
In RedHat Linux edit file /etc/inittab to add the
          following as a single line:

<programlisting>
pg:2345:respawn:/bin/su - postgres -c
    "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
    &gt;&gt; /usr/local/pgsql/server.log 2&gt;&1 &lt;/dev/null"
</programlisting>

          (The author of this example says this example will revive the
          postmaster if it dies, but he doesn't know if there are other side
          effects.)
</para>
</listitem>

</itemizedlist>

</Para>
</Step>

<Step Performance="required">
<Para>
     Run the regression tests.
     The file <filename>/usr/src/pgsql/src/test/regress/README</filename> has detailed
     instructions for running and interpreting the regression tests.
     A short version follows here:
</Para>

<substeps>

<Step Performance="required">
<Para>
    Type
<ProgramListing>
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
$ gmake all runtest
</ProgramListing>
</Para>

<Para>
     You do not need to type <command>gmake clean</command>
 if this is the first time you
     are running the tests.
</Para>

<Para>
     You should get on the screen (and also written to file <filename>./regress.out</filename>)
     a series of statements stating which tests passed and which tests
     failed.  Please note that it can be normal for some tests to
     "fail" on some platforms.  
The script says a test has failed if there is any difference
     at all between the actual output of the test and the expected output.
     Thus, tests may "fail" due to minor differences in wording of error
     messages, small differences in floating-point roundoff, etc, between
     your system and the regression test reference platform.
     "Failures" of this type do not indicate a problem with
     <ProductName>Postgres</ProductName>.
     The file <filename>./regression.diffs</filename> contains the textual differences between
     the actual test output on your machine and the "expected" output
     (which is simply what the reference system produced).  You should
     carefully examine each difference listed to see whether it appears to
     be a significant issue.
</Para>

<para>
For example,

<itemizedlist>
<listitem>
<Para>
     For a i686/Linux-ELF platform, no tests failed since this is the
     v6.4 regression testing reference platform.
</Para>
</listitem>

<listitem>
<Para>
     For the SPARC/Linux-ELF platform, using the 970525 beta version of
     <ProductName>Postgres</ProductName> v6.2 the following tests "failed":
     float8 and geometry "failed" due to minor precision differences in
     floating point numbers.  select_views produces massively different output,
     but the differences are due to minor floating point differences.
</Para>
</listitem>

</itemizedlist>
</para>
<Para>
     Even if a test result clearly indicates a real failure, it may be a
     localized problem that will not affect you.  An example is that the
     <type>int8</type> test will fail, producing obviously incorrect output, if your
     machine and C compiler do not provide a 64-bit integer data type
     (or if they do but configure didn't discover it).  This is not
     something to worry about unless you need to store 64-bit integers.
</Para>

<Para>
     Conclusion?  If you do see failures, try to understand the nature of
     the differences and then decide if those differences will affect your
     intended use of <ProductName>Postgres</ProductName>.  The regression
     tests are a helpful tool, but they may require some study to be useful.
</Para>

<Para>
     After running the regression tests, type

<ProgramListing>
$ destroydb regression
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
</ProgramListing>

    to recover the disk space used for the tests.  (You may want to save
    the <filename>regression.diffs</filename> file in another place before doing this.)
</Para>
</Step>

</substeps>
</step>
<Step Performance="required">
<Para>
 If you haven't already done so, this would be a good time to modify
      your computer to do regular maintainence.  The following should be
      done at regular intervals:
</para>
<procedure>
<title>Minimal Backup Procedure</title>

<step performance="required">
<para>
Run the <acronym>SQL</acronym> command <command>VACUUM</command>.  
This will clean up your database.
</para>
</step>
<step performance="required">
<para>
Back up your system.  (You should probably keep the last few
           backups on hand.)  Preferably, no one else should be using the
           system at the time.
</para>
</step>
</procedure>

<para>
      Ideally, the above tasks should be done by a shell script that is
      run nightly or weekly by cron.  
Look at the man page for <application>crontab</application>
      for a starting point on how to do this.  (If you do it, please
      e-mail us a copy of your shell script.  We would like to set up
      our own systems to do this too.)
</Para>
</Step>

<Step Performance="required">
<Para>
 If you are upgrading an existing system then reinstall your old database.
     Type
<ProgramListing>
$ cd
$ psql -e template1 < db.out
</ProgramListing>

     If your pre-v6.2 database uses either path or polygon geometric data types,
     then you will need to upgrade any columns containing those types. To
     do so, type (from within psql)
<ProgramListing>
UPDATE <replaceable>FirstTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
UPDATE <replaceable>SecondTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
...
VACUUM;
</ProgramListing>

     UpgradePath() checks to see that a path value is consistant with the
     old syntax, and will not update a column which fails that examination.
     UpgradePoly() cannot verify that a polygon is in fact from an old
     syntax, but RevertPoly() is provided to reverse the effects of a
     mis-applied upgrade.
</Para>
</Step>

<Step Performance="required">
<Para>
 If you are a new user, you may wish to play with <ProductName>Postgres</ProductName> as described
     below.
</Para>
</Step>

<Step Performance="required">
<Para>
 Clean up after yourself.  Type
<ProgramListing>
$ rm -rf /usr/src/pgsql_6_0
$ rm -rf /usr/local/pgsql_6_0
# Also delete old database directory tree if it is not in
#  /usr/local/pgsql_6_0/data
$ rm ~/postgresql-v6.2.1.tar.gz
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 You will probably want to print out the documentation. 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

<programlisting>
$ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr
</programlisting>
</para>
<para>
  Here is how
     you might do it if you have Ghostscript on your system and are
     writing to a laserjet printer.

<programlisting>
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
</programlisting>
</para>
</Step>

<Step Performance="required">
<Para>
 The <ProductName>Postgres</ProductName> team wants
 to keep <ProductName>Postgres</ProductName> working on all of the
     supported platforms.  We therefore ask you to let us know if you did
     or did not get <ProductName>Postgres</ProductName> to work on you system.
  Please send a
     mail message to 
<ulink url="mailto:pgsql-ports@postgresql.org">pgsql-ports@postgresql.org</ulink>
 telling us the following:

<itemizedlist>
<listitem>
<para>
The version of <ProductName>Postgres</ProductName> (v6.4, 6.3.2, beta 981014, etc.).
</para>
</listitem>

<listitem>
<para>
Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
</para>
</listitem>

<listitem>
<para>
Your hardware (SPARC, i486, etc.).
</para>
</listitem>

<listitem>
<para>
Did you compile, install and run the regression tests cleanly?
         If not, what source code did you change (i.e. patches you
         applied, changes you made, etc.), what tests failed, etc.
         It is normal to get many warning when you compile.  You do
         not need to report these.
</para>
</listitem>

</itemizedlist>

</Para>
</Step>

<Step Performance="required">
<Para>
 Now create, access and manipulate databases as desired.  Write client
     programs to access the database server.  In other words, <emphasis>enjoy</emphasis>!
</Para>
</Step>
</Procedure>
</sect1>

<Sect1>
<Title>Playing with <ProductName>Postgres</ProductName></Title>

<Para>
After <ProductName>Postgres</ProductName> is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to 
see <ProductName>Postgres</ProductName> do something.  That's easy.  Invoke the interactive interface
to <ProductName>Postgres</ProductName>, <Application>psql</Application>:

<ProgramListing>
% psql template1
</ProgramListing>

(psql has to open a particular database, but at this point the only one
that exists is the template1 database, which always exists.  We will connect
to it only long enough to create another one and switch to it.)
</Para>

<Para>
The response from psql is:

<ProgramListing>
Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL

   type \? for help on slash commands
   type \q to quit
   type \g or terminate with semicolon to execute query
 You are currently connected to the database: template1

template1=>
</ProgramListing>
</Para>

<Para>
Create the database foo:

<ProgramListing>
template1=> create database foo;
CREATEDB
</ProgramListing>

(Get in the habit of including those SQL semicolons.  Psql won't execute
anything until it sees the semicolon or a "\g" and the semicolon is required
to delimit multiple statements.)
</Para>

<Para>
Now connect to the new database:

<ProgramListing>
template1=> \c foo
connecting to new database: foo
</ProgramListing>

("slash" commands aren't SQL, so no semicolon.  Use \? to see all the slash commands.)
</Para>

<Para>
And create a table:

<ProgramListing>
foo=> create table bar (i int4, c char(16));
CREATE
</ProgramListing>
</Para>

<Para>
Then inspect the new table:

<ProgramListing>
foo=> \d bar

Table    = bar
+----------------------------------+----------------------------------+-------+
|              Field               |              Type                | Length|
+----------------------------------+----------------------------------+-------+
| i                                | int4                             |     4 |
| c                                | (bp)char                         |    16 |
+----------------------------------+----------------------------------+-------+
</ProgramListing>
</Para>

<Para>
And so on.  You get the idea.
</Para>
</Sect1>

<Sect1>
<Title>The Next Step</Title>

<Para>
Questions? Bugs? Feedback?
First, read the files in directory <filename>/usr/src/pgsql/doc/</filename>.  
The FAQ in this directory may be particularly useful.
</Para>

<Para>
If <ProductName>Postgres</ProductName> failed to compile on your computer 
then fill out the form in file <filename>/usr/src/pgsql/doc/bug.template</filename>
 and mail it to the location indicated at the top of the form.
</Para>

<Para>
Check on the web site at
<ULink url="http://www.postgresql.org">http://www.postgresql.org</ULink>
For more information on the various support mailing lists.
</Para>
</Sect1>

<Sect1>
<Title>Porting Notes</Title>

<Note>
<Para>
Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
the source distribution. For some ports, the notes below may be out of date.
</Para>
</Note>

  <Sect2>
   <Title>Ultrix4.x</Title>
   
   <para>
    <note>
     <para>
      There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
     </para>
    </note>
   </para>
   <para>
    You need to install the libdl-1.1 package since Ultrix 4.x doesn't
    have a dynamic loader. It's available in
    s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
   </Para>
  </Sect2>
  
  <Sect2>
   <Title>Linux</Title>
   
   <Sect3>
    <Sect3Info>
     <Author>
      <FirstName>Thomas G.</FirstName>
      <SurName>Lockhart</SurName>
     </Author>
     <Date>1998-02-19</Date>
    </Sect3Info>
    <Title>Linux ELF</Title>
    
    <Para>
     The regression test reference machine is
     a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
     The linux-elf port installs cleanly. See the Linux FAQ for more details.
    </Para>
   </Sect3>

<Sect3>
<Sect3Info>
<Date>1995-05-11</Date>
</Sect3Info>
<Title>Linux a.out</Title>

<Para>
        For non-ELF Linux, the dld library MUST be obtained and installed on
        the system. It enables dynamic link loading capability to the <ProductName>Postgres</ProductName>
        port. The dld library can be obtained from the sunsite linux
        distributions. The current name is dld-3.2.5.
<ULink url="sneaker@powergrid.electriciti.com">Jalon Q. Zimmerman</ULink>
</Para>
</Sect3>
</Sect2>

<Sect2>
<Title>BSD/OS</Title>

<Para>
        For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
</Para>
</Sect2>

<Sect2>
<Title>NeXT</Title>

<Para>
        The NeXT port for v1.09 was supplied by 
<ULink url="mailto:tom@basil.icce.rug.nl">Tom R. Hageman</ULink>.
        It requires a SysV IPC emulation library and header files for
        shared libary and semaphore stuff.   Tom just happens to sell such
        a product so contact him for information.  He has also indicated that
        binary releases of <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to
        the general public.  Contact Info@RnA.nl for information.
</para>
<Para>
We have no recent reports of successful NeXT installations (as of v6.2.1). 
However, the client-side libraries should work even
if the backend is not supported.
</Para>
</Sect2>
</Sect1>

</Chapter>