postgresql/INSTALL

POSTGRESQL INSTALLATION INSTRUCTIONS
Copyright (c) 1997 Regents of  the University of California

This is file /usr/src/pgsql/INSTALL.  It contains notes on how to install
PostgreSQL v6.1.  Up to date information on PostgreSQL may be found at
http://www.postgresql.org.

PostgreSQL is a database server.  It is not completely ANSI SQL
compliant, but with each release it gets closer.

PostgreSQL, formerly called Postgres95, is a derivative of Postgres 4.2
(the last release of the UC Berkeley research project).  For copyright
terms for PostgreSQL, please see the file named COPYRIGHT.  This version
was developed by a team of developers on the postgres developers mailing
list.  Version 1 (through 1.01) was developed by Jolly Chen and Andrew
Yu.

The installation notes below assume the following (except where noted):
  - Commands were tested on RedHat Linux version 4.0 using the bash
    shell.  Except where noted, they will probably work on most
    systems.  USE COMMON SENSE before typing in these commands.
    Commands like ps and tar vary wildly on what options you should
    use on each platform.
  - Defaults are assumed.
  - User postgres is the postgres superuser.

Our Makefiles require GNU make (called gmake in this document) and
also assume that "install" accepts BSD options. The INSTALL
variable in the Makefiles is set to the BSD-compatible version of
install. On some systems, you will have to find a BSD-compatible
install command (eg. bsdinst, which comes with the MIT X Window System
distribution) 


REQUIREMENTS TO RUN POSTGRESQL
------------------------------

PostgreSQL has been tested on the following platforms:

   aix            IBM on AIX 3.2.5
   alpha          DEC Alpha AXP on OSF/1 2.0
   BSD44_derived  OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
   bsdi           BSD/OS 2.0, 2.01, 2.1
   dgux           DG/UX 5.4R3.10
   hpux           HP PA-RISC on HP-UX 9.0
   i386_solaris   i386 Solaris
   irix5          SGI MIPS on IRIX 5.3
   linux          Intel x86 on Linux 1.2 and Linux ELF
                  (For non-ELF Linux, see LINUX_ELF below).
   sparc_solaris  SUN SPARC on Solaris 2.4
   sunos4         SUN SPARC on SunOS 4.1.3
   svr4           Intel x86 on Intel SVR4
   ultrix4        DEC MIPS on Ultrix 4.4

PostgreSQL has known problems/bugs on the following platforms:

   nextstep       Motorola MC68K or Intel x86 on NeXTSTEP 3.2

PostgreSQL is also known to work on a number of other platforms that the
authors have not personally tested.

You should have at least 8 MB of memory and at least 30 MB of disk space to
hold the source, binaries, and user databases.


To upgrade to PostgreSQL v6.1 do the following:
----------------------------------------------

  1) 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 /usr/src/pgsql/doc, including files FAQ-Irix
     and FAQ-Linux.  Also look in directory ftp://ftp.postgresql.org/pub.
     If there is a file called INSTALL in this directory then this
     file will contain the latest installation information.

  2) Create account postgres if it does not already exist.

  3) Log into account postgres.

  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.1.tar.gz from the
     internet.

  5) Some platforms use flex.  If your system uses flex then make sure
     you have a good version.  Type
        flex -- version

     If the flex 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 flex.  You may
     get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.

     If you need flex 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 flex when you try to
     compile.

     To install it, type the following:
        cd
        gunzip -c flex-2.5.4.tar.gz | tar xvf -
        cd flex-2.5.4
        configure --prefix=/usr
        make
        make check
        # You must be root when typing the next line.
        make install
        cd
        rm -rf flex-2.5.4

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

  6) If you are upgrading an existing system from any version before
     version 6.1 beta release 970512 then back up the current
     database.  Type
        cd
        pg_dumpall > db.out
     If you wish to preserve object id's (oids), type
        cd
        pg_dumpall -o > db.out
     instead.  However, unless you have a special reason for doing this,
     don't do it.

     Please note that 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 should also read files /usr/src/pgsql/migration/*.

     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.

  7) If you are upgrading an existing system then kill the postmaster.  Type
       ps -ax | grep postmaster
     This should list the process numbers for a number of processes.  Type
     the following line, with "???" replaced by the process id for process
     "postmaster".  (Do not use the id for process "grep postmaster".)  Type
       kill ???
     with "???" modified as indicated.

  8) 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 /usr/local/pgsql/data directory tree.  At a
     minimum, save file /usr/local/pgsql/data/pg_hba.conf.

     Type the following:
        su
        cd /usr/src
        mv pgsql pgsql_6_0
        cd /usr/local
        mv pgsql pgsql_6_0
        exit

     If you are not using /usr/local/pgsql/data 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.

  9) Make new source and install directories.  Type
        su
        cd /usr/src
        mkdir pgsql
        chown postgres:postgres pgsql
        cd /usr/local
        mkdir pgsql
        chown postgres:postgres pgsql
        exit

 10) Unzip and untar the new source file.  Type
        cd /usr/src/pgsql
        gunzip -c ~/postgresql-v6.1.tar.gz | tar xvf -

 11) Configure the source code for your system.  Type
        cd /usr/src/pgsql/src
        ./configure

     The configure program will list the template files available and
     ask you to choose one.  A lot of times, an appropriate template
     file is chosen for you, and you can just press Enter to accept the
     default.  If the default is not appropriate, then type in the
     appropriate template file and press Enter.  (If you do this, then
     send email to scrappy@hub.org stating the output of the program
     './config.guess' and what the template file should be.)

     Once you have entered the template file, you will be asked a
     number of questions about your particular configuration.  These
     can be skipped by adding parameters to the configure command above.
     The following parameters can be tagged onto the end of the configure
     command:

       --prefix=BASEDIR   Selects a different base directory for the
                          installation of the PostgreSQL configuration.
                          The default is /usr/local/pgsql.

       --enable-hba       Enables Host Based Authentication

       --disable-hba      Disables Host Based Authentication

       --enable-locale    Enables USE_LOCALE

       --disable-locale   Disables USE_LOCALE

       --enable-cassert   Enables ASSERT_CHECKING

       --disable-cassert  Disables ASSERT_CHECKING

                          The default for ASSERT_CHECKING is normally
                          enabled for development versions and
                          disabled for release versions of PostgreSQL.
		
       --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.
                          (If the configure script cannot find the
                          specified template file, it will ask you for
                          one).

       --with-pgport=PORT Sets the port that the postmaster process
                          listens for incoming connections on.  The
                          default for this is port 5432.

     As an example, here is the configure script I use on a Sparc
     Solaris 2.5 system with /opt/postgres being the install base.

       % ./configure --prefix=/opt/postgres 
		--with-template=sparc_solaris-gcc --with-pgport=5432
		--enable-hba --disable-locale

     Of course, in a real shell, you would type these three lines all
     on the same line.

 12) Compile the program.  Type
        cd /usr/src/pgsql/src
        gmake all &> make.log &
        tail -f make.log
     The last line displayed will hopefully be "All of PostgreSQL is
     successfully made. Ready to install."  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.)

     If your computer does not have gmake (GNU make) then try running
     make instead throughout the rest of these notes.

     Please note that you will probably find a number of warning
     messages in make.log.  Unless you have problems later on, these
     messages may be safely ignored.

     If the compiler fails with an error stating that the flex command
     cannot be found then install flex as described earlier.  Next,
     change directory back to this directory, type "make clean", then
     recompile again.

 13) Install the program.  Type
        cd /usr/src/pgsql/src
        gmake install &> make.install.log &
        tail -f make.install.log
     The last line displayed will be "gmake[1]: Leaving directory
     `/usr/src/pgsql/src/man'".  At this point, or earlier if you wish,
     type control-C to get out of tail.

 14) If necessary, tell UNIX how to find your shared libraries.  If you
     are using Linux-ELF do ONE of the following, preferably the first:

       a) As root, edit file /etc/ld.so.conf.  Add line
             /usr/local/pgsql/lib
          to the file.  Then run command /sbin/ldconfig.

       b) In a bash shell, type
             export LD_LIBRARY_PATH=/usr/local/pgsql/lib

       c) In a csh shell, type
             setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

     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.

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

 15) If it has not already been done, then prepare account postgres
     for using PostgreSQL.  Any account that will use PostgreSQL must
     be similarily prepared.  (The following instructions are for a
     bash shell.  Adapt accordingly for other shells.)

     Add the following lines to your login shell, ~/.bash_profile:
        PATH=$PATH:/usr/local/pgsql/bin
        MANPATH=/usr/local/pgsql/man
        PGLIB=/usr/local/pgsql/lib
        PGDATA=/usr/local/pgsql/data
        export PATH MANPATH PGLIB PGDATA

     Make sure that you have defined these variables before continuing
     with the remaining steps.  The easiest way to do this is to type:
        source ~/.bash_profile

 16) Create the database.  DO NOT DO THE FOLLOWING AS ROOT!  This would
     be a major security hole.  Type
        initdb

 17) Set up permissions to access the database system.  Do this by editing
     file /usr/local/pgsql/data/pg_hba.conf.  The instructions are
     included in the file.  (If your database is not located in the
     default location, i.e. if PGDATA 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 finsihed.

     If you are upgrading from v6.0 you can copy file pg_hba.conf from
     your old database on top of the one in your new database, rather than
     redoing this from scratch.

 18) If you wish to skip the regression tests then skip to step 21.
     However, we think skipping the tests is a BAD idea!

     Start the postmaster in preparation for the regression tests.  First,
     set the timezone for Berkley, California.  On some systems you may do
     this by setting environment variable TZ.  I.e., using bash, type
        export TZ=PST8PDT7,M04.01.0,M10.0503
     Now start the postmaster daemon running in the background by typing
        cd
        nohup postmaster > regress.log 2>&1 &
     Run postmaster from your postgres super user account (typically
     account postgres).  DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.

 19) Run the regression tests.  Type

        cd /usr/src/pgsql/src/test/regress
        gmake clean
        gmake all runtest

     You do not need to type "gmake clean" if this is the first time you
     are running the tests.

     You should get on the screen (and also written to file ./regress.out)
     a series of statements stating which tests passed and which tests
     failed.  Please note that it is normal for some of the tests to
     "fail".

     For the tests that failed, i.e. if float8 failed, type something like:
        cd /usr/src/pgsql/src/test/regress
        diff -w expected/float8.out results
     Now do some intelligent interpretation of what you see before
     deciding if you have detected a bug in PostgreSQL as it compiled on
     you platform.

     For example.  On a SPARC/Linux-elf platform using the 970516 beta
     version of PostgreSQL v6.1 the following tests "failed".  float8
     and geometry "failed" due to minor precision differences in floating
     point numbers.  timespan and horology had different values from the
     expected "14 secs ago".  (This may be a real bug.  It may simply be
     problems with convincing the back end what timezone and time to
     use.)  datetime, abstime and tinterval failed because it used GMT
     where it should have used PST and PDT.  (Same comment.)  select_views
     failed for unknown reasons.  Conclusion?  There may be some real
     bugs exhibited here but will they effect what you intend to use
     PostgreSQL for?  (Note:  Most of these bugs also occur on the
     i86/Linux platform.  Also note that there will be significant
     changes made to the date and time types immediately after the
     v6.1 release so if you do need these functions, monitor the HACKERS
     and PORTS mailing lists to see what is going on.)

     After running the tests, type
        cd /usr/src/pgsql/src/test/regress
        gmake clean

 20) Stop the postmaster as described in step 7.  Then restore the
     timezone to it's normal setting.  If you changed the timezone by
     modifying environment variable TZ then one way to do this is to
     log out of, then back into, account postgres.

 21) Start the postmaster daemon running.  Type
        cd
        nohup postmaster > server.log 2>&1 &
     Run postmaster from your postgres super user account (typically
     account postgres).  DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.

 22) If you haven't already done so, this would be a good time to modify
     your computer so that it will automatically start postmaster whenever
     you boot your computer.

     Here are some suggestions on how to do this, contributed by various
     users.

     Whatever you do, postmaster must be run by user postgres, AND NOT BY
     ROOT.  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.

       a) 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"

       b) In RedHat v4.0 Linux edit file /etc/inittab to contain the
          following single line:
             pg:2345:respawn:/bin/su - postgres -c
                     "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
                     >> /usr/local/pgsql/server.log 2>&1" /dev/null
          (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.)

       c) 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.  Note:  Unlike the
          other examples, this one has been tested.

       d) In RedHat v4.0 Linux create file /etc/rc.d/init.d/postgres.init to
          contain the following single line:
             su -c "cd ~postgres; nohup /usr/local/pgsql/bin/postmaster
                     -D /usr/local/pgsql/data  > server.log 2>&1 &" postgres
          Next, type the following:
             cd /etc/rc3.d
             ln -s ../init.d/postgres.init S1000postgres
          Change "1000" to a number of your choice to indicate the
          loading order of the various programs pointed to in directory
          /etc/rc3.d.  (Note that this example has not been tested yet.)

     You might also want to modify your computer so that cron will run
     the vacuum command nightly and do regular backups.  Look at the
     man page for crontab for a starting point on how to do this.

 23) If you are upgrading an existing system then install your old database.
     Type
        cd
        psql -e template1 < db.out

 24) If you are a new user, you may wish to play with postgres as described
     below.

 25) Clean up after yourself.  Type
        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.1.tar.gz

 26) You will probably want to print out the documentation.  Here is how
     you might do it if you have Ghostscript on your system and are
     writing to a laserjet printer.
        alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
        export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
        # Print out the man pages.
        man -a -t /usr/local/pgsql/man/*/* > manpage.ps
        gshp -sOUTPUTFILE=manpage.hp manpage.ps
        rm manpage.ps
        lpr -l -s -r manpage.hp
        # Print out the Postgres95 User Manual, version 1.0,
        #  Sept. 5, 1996.
        cd /usr/src/pgsql/doc
        gshp -sOUTPUTFILE=userguide.hp userguide.ps
        lpr -l -s -r userguide.hp

     If you are a developer, you will probably want to also print out
     the Postgres Implemention Guide, version 1.0, October 1, 1995.
     This is a WWW document located at
     http://www.postgresql.org/docs/impguide.

 27) Now create, access and manipulate databases as desired.  Write client
     programs to access the database server.  In other words, ENJOY!


PLAYING WITH POSTGRESQL
-----------------------

After PostgreSQL is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to 
see PostgreSQL do something.  That's easy.  Invoke the interactive interface
to PostgreSQL, psql, and start typing SQL:

  $ psql template1

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

The response from psql is:

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

Create the database foo:

template1=> CREATE DATABASE FOO;
INSERT 773248

(Don't ever forget those SQL semicolons.  Psql won't execute anything until it
sees the semicolon.)

template1=> \c foo
closing connection to database: template1
connecting to new database: foo

(\ commands aren't SQL, so no semicolon.  Use \? to see all the \ commands.)

template1=> CREATE TABLE bar (column1 int4, column2 char16);
CREATE

template1=> \d bar

...

You get the idea.


QUESTIONS?  BUGS?  FEEDBACK?
----------------------------

First, read the files in directory /usr/src/pgsql/doc.  The FAQ in
this directory may be particularly useful.

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

Mail questions to pgsql-questions@postgresql.org.  For more information
on the various mailing lists, see http://www.postgresql.org under mailing
lists.


----------------------------------------------------------------------

Porting Notes (these notes may be out of date):
-------------

Ultrix4.x:
        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

Linux:
        The linux port defaults to the ELF binary format. (Note that if you're
        using ELF, you don't need dld because you'll be using the dl library
        that comes with Linux ELF instead.)

        To compile on non-ELF Linux, comment out the LINUX_ELF line in
        src/mk/port/postgres.mk.linux. Also, the dld library MUST be obtained
        and installed on the system. It enables dynamic link loading capability
        to the postgres port. The dld library can be obtained from the sunsite
        linux distributions. The current name is dld-3.2.5.
                                (Jalon Q. Zimmerman
                                <sneaker@powergrid.electriciti.com> 5/11/95)

        To compile with flex, you need a recent version (2.5.2 or
        later). Otherwise, you will get a 'yy_flush_buffer' undefined error.
        Note, however, that flex v2.5.3 has a bug. See the FAQs.

BSD/OS:
        For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2
        as well as the GNU dld library.  Flex version 2.5.3 has a known bug.

NeXT:
        The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
        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 PostgreSQL for NEXTSTEP will be made available to
        the general public.  Contact Info@RnA.nl for information.

SPARC Linux-elf:
        There was not time to finish adding support for this in the v6.1
        release.  However, if you are running RedHat Linux v4.0 on a
        SPARC platform then install flex v2.5.4 and tell configure you
        have a Linux-elf platform.  Between configuring and compiling
        PostgreSQL, edit the following files:
          1) Edit src/GNUmakefile to comment out the call to lexflex and
             the if-then-else test that follows it.  (This may not be
             necessary by the time v6.1 gets released.)
          2) Edit src/Makefile.global to change "-O2" to "-O".
          3) Edit src/backend/libpq/pqcomprim.c, near the start to replace
                #ifdef        HAVE_ENDIAN_H
                #  include    <endian.h>
                #endif
             with
                /*
                #ifdef        HAVE_ENDIAN_H
                #  include    <endian.h>
                #endif
                */
                #define BYTE_ORDER LITTLE_ENDIAN 
        If you want to know the reasonilng behind the above instructions
        then look in ftp://ftp.postgresql.org/pub/majordomo/ports for a
        May 16, 1997 mail message called "regression tests on a
        SPARC/Linux platform".