head	1.96;
access;
symbols
	REL7_2_8:1.86
	REL7_3_10:1.88.2.10
	REL7_2_7:1.86
	REL7_3_9:1.88.2.9
	REL7_3_8:1.88.2.8
	REL7_2_6:1.86
	REL7_2_5:1.86
	REL7_3_7:1.88.2.7
	REL7_4_2:1.92.2.7
	REL7_3_6:1.88.2.6
	REL7_4_1:1.92.2.5
	REL7_3_5:1.88.2.5
	REL7_4:1.92.2.2
	REL7_4_RC2:1.92
	REL7_4_STABLE:1.92.0.2
	REL7_4_RC1:1.92
	REL7_4_BETA5:1.91
	REL7_4_BETA4:1.90
	REL7_4_BETA3:1.90
	REL7_4_BETA2:1.90
	WIN32_DEV:1.90.0.2
	REL7_4_BETA1:1.90
	REL7_3_4:1.88.2.4
	REL7_3_2:1.88.2.3
	REL7_2_4:1.86
	REL7_3_STABLE:1.88.0.2
	REL7_2_3:1.86
	REL7_2_STABLE:1.86.0.2
	REL7_2:1.86
	REL7_2_RC2:1.85
	REL7_2_RC1:1.85
	REL7_2_BETA5:1.85
	REL7_2_BETA4:1.85
	REL7_2_BETA3:1.84
	REL7_2_BETA2:1.84
	REL7_2_BETA1:1.84
	REL7_1_2:1.83
	REL7_1_STABLE:1.83.0.2
	REL7_1_BETA:1.81
	REL7_1_BETA3:1.81
	REL7_1_BETA2:1.81
	REL7_1:1.83
	REL7_0_PATCHES:1.75.0.2
	REL7_0:1.74
	REL6_5_PATCHES:1.66.0.2
	REL6_5:1.66
	REL6_4:1.62.0.2
	release-6-3:1.46
	SUPPORT:1.1.1.1
	PG95-DIST:1.1.1;
locks; strict;
comment	@# @;


1.96
date	2004.03.10.00.28.10;	author momjian;	state dead;
branches;
next	1.95;

1.95
date	2004.01.04.16.43.52;	author petere;	state Exp;
branches;
next	1.94;

1.94
date	2003.12.11.19.56.54;	author petere;	state Exp;
branches;
next	1.93;

1.93
date	2003.11.13.18.03.11;	author petere;	state Exp;
branches;
next	1.92;

1.92
date	2003.10.23.16.40.14;	author momjian;	state Exp;
branches
	1.92.2.1;
next	1.91;

1.91
date	2003.10.04.03.14.13;	author momjian;	state Exp;
branches;
next	1.90;

1.90
date	2003.08.04.04.03.03;	author tgl;	state Exp;
branches;
next	1.89;

1.89
date	2002.11.21.23.33.22;	author petere;	state Exp;
branches;
next	1.88;

1.88
date	2002.10.22.13.46.59;	author tgl;	state Exp;
branches
	1.88.2.1;
next	1.87;

1.87
date	2002.08.22.22.43.08;	author scrappy;	state Exp;
branches;
next	1.86;

1.86
date	2002.01.31.00.46.26;	author petere;	state Exp;
branches;
next	1.85;

1.85
date	2001.11.28.20.54.04;	author petere;	state Exp;
branches;
next	1.84;

1.84
date	2001.10.01.17.46.44;	author momjian;	state Exp;
branches;
next	1.83;

1.83
date	2001.04.06.15.52.41;	author petere;	state Exp;
branches;
next	1.82;

1.82
date	2001.01.15.21.17.26;	author petere;	state Exp;
branches;
next	1.81;

1.81
date	2000.11.30.21.44.07;	author petere;	state Exp;
branches;
next	1.80;

1.80
date	2000.07.21.00.44.09;	author petere;	state Exp;
branches;
next	1.79;

1.79
date	2000.06.05.17.07.52;	author momjian;	state Exp;
branches;
next	1.78;

1.78
date	2000.06.05.10.57.57;	author momjian;	state Exp;
branches;
next	1.77;

1.77
date	2000.06.01.05.58.41;	author momjian;	state Exp;
branches;
next	1.76;

1.76
date	2000.06.01.05.48.42;	author momjian;	state Exp;
branches;
next	1.75;

1.75
date	2000.05.22.22.04.47;	author petere;	state Exp;
branches
	1.75.2.1;
next	1.74;

1.74
date	2000.05.04.16.12.05;	author thomas;	state Exp;
branches;
next	1.73;

1.73
date	2000.04.25.18.43.14;	author momjian;	state Exp;
branches;
next	1.72;

1.72
date	2000.03.09.12.00.06;	author petere;	state Exp;
branches;
next	1.71;

1.71
date	2000.01.23.01.27.34;	author petere;	state Exp;
branches;
next	1.70;

1.70
date	2000.01.20.22.21.30;	author momjian;	state Exp;
branches;
next	1.69;

1.69
date	2000.01.20.22.17.39;	author momjian;	state Exp;
branches;
next	1.68;

1.68
date	2000.01.20.21.50.50;	author petere;	state Exp;
branches;
next	1.67;

1.67
date	99.07.30.04.04.53;	author scrappy;	state Exp;
branches;
next	1.66;

1.66
date	99.06.14.07.24.32;	author thomas;	state Exp;
branches
	1.66.2.1;
next	1.65;

1.65
date	99.06.04.06.23.27;	author thomas;	state Exp;
branches;
next	1.64;

1.64
date	99.06.03.16.05.38;	author thomas;	state Exp;
branches;
next	1.63;

1.63
date	98.12.17.16.37.03;	author momjian;	state Exp;
branches;
next	1.62;

1.62
date	98.10.31.09.31.58;	author thomas;	state Exp;
branches
	1.62.2.1;
next	1.61;

1.61
date	98.10.10.03.08.01;	author momjian;	state Exp;
branches;
next	1.60;

1.60
date	98.10.09.21.41.35;	author momjian;	state Exp;
branches;
next	1.59;

1.59
date	98.10.09.19.53.08;	author momjian;	state Exp;
branches;
next	1.58;

1.58
date	98.08.30.05.09.03;	author momjian;	state Exp;
branches;
next	1.57;

1.57
date	98.08.30.01.40.38;	author momjian;	state Exp;
branches;
next	1.56;

1.56
date	98.06.16.03.28.57;	author momjian;	state Exp;
branches;
next	1.55;

1.55
date	98.06.08.16.48.49;	author momjian;	state Exp;
branches;
next	1.54;

1.54
date	98.06.01.16.44.08;	author mergl;	state Exp;
branches;
next	1.53;

1.53
date	98.05.12.23.14.00;	author momjian;	state Exp;
branches;
next	1.52;

1.52
date	98.05.12.21.43.57;	author momjian;	state Exp;
branches;
next	1.51;

1.51
date	98.04.17.01.30.10;	author scrappy;	state Exp;
branches;
next	1.50;

1.50
date	98.04.07.21.00.53;	author momjian;	state Exp;
branches;
next	1.49;

1.49
date	98.04.05.20.27.46;	author momjian;	state Exp;
branches;
next	1.48;

1.48
date	98.03.25.01.45.33;	author momjian;	state Exp;
branches;
next	1.47;

1.47
date	98.03.23.16.13.54;	author momjian;	state Exp;
branches;
next	1.46;

1.46
date	98.02.22.20.02.06;	author momjian;	state Exp;
branches;
next	1.45;

1.45
date	98.02.01.21.20.20;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	97.10.16.04.13.18;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	97.10.15.02.34.51;	author thomas;	state Exp;
branches;
next	1.42;

1.42
date	97.10.02.00.50.28;	author scrappy;	state Exp;
branches;
next	1.41;

1.41
date	97.09.14.02.09.01;	author momjian;	state Exp;
branches;
next	1.40;

1.40
date	97.07.30.14.55.20;	author momjian;	state Exp;
branches;
next	1.39;

1.39
date	97.07.29.14.17.43;	author momjian;	state Exp;
branches;
next	1.38;

1.38
date	97.07.28.22.37.33;	author momjian;	state Exp;
branches;
next	1.37;

1.37
date	97.07.28.02.08.05;	author momjian;	state Exp;
branches;
next	1.36;

1.36
date	97.07.16.02.20.45;	author momjian;	state Exp;
branches;
next	1.35;

1.35
date	97.07.15.01.01.51;	author momjian;	state Exp;
branches;
next	1.34;

1.34
date	97.07.14.21.18.20;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	97.07.14.16.47.25;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	97.07.14.16.37.30;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	97.07.13.19.59.46;	author momjian;	state Exp;
branches;
next	1.30;

1.30
date	97.06.25.21.16.24;	author momjian;	state Exp;
branches;
next	1.29;

1.29
date	97.06.07.03.42.17;	author scrappy;	state Exp;
branches;
next	1.28;

1.28
date	97.06.06.01.34.59;	author scrappy;	state Exp;
branches;
next	1.27;

1.27
date	97.06.03.15.25.45;	author thomas;	state Exp;
branches;
next	1.26;

1.26
date	97.06.02.03.02.43;	author scrappy;	state Exp;
branches;
next	1.25;

1.25
date	97.05.26.00.43.41;	author scrappy;	state Exp;
branches;
next	1.24;

1.24
date	97.05.17.14.26.30;	author thomas;	state Exp;
branches;
next	1.23;

1.23
date	97.05.17.03.00.24;	author scrappy;	state Exp;
branches;
next	1.22;

1.22
date	97.05.15.22.16.45;	author scrappy;	state Exp;
branches;
next	1.21;

1.21
date	97.05.07.03.15.36;	author scrappy;	state Exp;
branches;
next	1.20;

1.20
date	97.04.24.14.14.28;	author scrappy;	state Exp;
branches;
next	1.19;

1.19
date	97.04.21.18.26.27;	author scrappy;	state Exp;
branches;
next	1.18;

1.18
date	97.04.12.09.33.25;	author scrappy;	state Exp;
branches;
next	1.17;

1.17
date	97.03.06.22.59.38;	author momjian;	state Exp;
branches;
next	1.16;

1.16
date	97.03.02.02.09.19;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	97.01.30.03.58.15;	author scrappy;	state Exp;
branches;
next	1.14;

1.14
date	97.01.28.20.49.59;	author scrappy;	state Exp;
branches;
next	1.13;

1.13
date	97.01.16.16.14.36;	author scrappy;	state Exp;
branches;
next	1.12;

1.12
date	97.01.16.16.10.05;	author scrappy;	state Exp;
branches;
next	1.11;

1.11
date	97.01.10.21.22.02;	author momjian;	state Exp;
branches;
next	1.10;

1.10
date	97.01.03.06.08.16;	author momjian;	state Exp;
branches;
next	1.9;

1.9
date	96.11.07.15.24.27;	author momjian;	state Exp;
branches;
next	1.8;

1.8
date	96.11.06.22.34.18;	author momjian;	state Exp;
branches;
next	1.7;

1.7
date	96.11.05.05.17.28;	author scrappy;	state Exp;
branches;
next	1.6;

1.6
date	96.10.30.06.01.55;	author scrappy;	state Exp;
branches;
next	1.5;

1.5
date	96.10.28.22.12.42;	author scrappy;	state Exp;
branches;
next	1.4;

1.4
date	96.10.04.20.08.29;	author scrappy;	state Exp;
branches;
next	1.3;

1.3
date	96.09.28.00.57.41;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	96.09.23.08.27.04;	author scrappy;	state Exp;
branches;
next	1.1;

1.1
date	96.08.18.22.14.15;	author scrappy;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	96.08.18.22.14.15;	author scrappy;	state Exp;
branches;
next	;

1.62.2.1
date	98.12.17.16.37.34;	author momjian;	state Exp;
branches;
next	1.62.2.2;

1.62.2.2
date	98.12.18.05.25.53;	author momjian;	state Exp;
branches;
next	1.62.2.3;

1.62.2.3
date	98.12.29.05.06.04;	author momjian;	state Exp;
branches;
next	;

1.66.2.1
date	99.07.14.23.38.26;	author thomas;	state Exp;
branches;
next	1.66.2.2;

1.66.2.2
date	99.10.12.15.35.05;	author momjian;	state Exp;
branches;
next	1.66.2.3;

1.66.2.3
date	99.12.06.16.23.25;	author thomas;	state Exp;
branches;
next	;

1.75.2.1
date	2000.06.01.05.14.30;	author momjian;	state Exp;
branches;
next	1.75.2.2;

1.75.2.2
date	2000.06.01.05.58.54;	author momjian;	state Exp;
branches;
next	1.75.2.3;

1.75.2.3
date	2000.06.05.10.59.13;	author momjian;	state Exp;
branches;
next	1.75.2.4;

1.75.2.4
date	2000.06.05.17.02.26;	author momjian;	state Exp;
branches;
next	1.75.2.5;

1.75.2.5
date	2000.11.03.03.42.53;	author momjian;	state Exp;
branches;
next	;

1.88.2.1
date	2002.11.21.23.31.09;	author petere;	state Exp;
branches;
next	1.88.2.2;

1.88.2.2
date	2002.12.18.20.07.02;	author momjian;	state Exp;
branches;
next	1.88.2.3;

1.88.2.3
date	2002.12.18.23.38.08;	author petere;	state Exp;
branches;
next	1.88.2.4;

1.88.2.4
date	2003.07.23.04.09.40;	author momjian;	state Exp;
branches;
next	1.88.2.5;

1.88.2.5
date	2003.12.02.16.26.00;	author tgl;	state Exp;
branches;
next	1.88.2.6;

1.88.2.6
date	2004.03.02.00.44.51;	author tgl;	state Exp;
branches;
next	1.88.2.7;

1.88.2.7
date	2004.08.15.00.51.57;	author tgl;	state Exp;
branches;
next	1.88.2.8;

1.88.2.8
date	2004.10.22.00.27.01;	author tgl;	state Exp;
branches;
next	1.88.2.9;

1.88.2.9
date	2005.01.30.20.08.13;	author tgl;	state Exp;
branches;
next	1.88.2.10;

1.88.2.10
date	2005.05.05.20.09.09;	author tgl;	state Exp;
branches;
next	1.88.2.11;

1.88.2.11
date	2005.05.08.23.32.37;	author tgl;	state dead;
branches;
next	;

1.92.2.1
date	2003.11.13.17.59.35;	author petere;	state Exp;
branches;
next	1.92.2.2;

1.92.2.2
date	2003.11.15.17.20.39;	author petere;	state Exp;
branches;
next	1.92.2.3;

1.92.2.3
date	2003.12.11.19.57.24;	author petere;	state Exp;
branches;
next	1.92.2.4;

1.92.2.4
date	2003.12.15.22.31.04;	author momjian;	state Exp;
branches;
next	1.92.2.5;

1.92.2.5
date	2003.12.20.15.32.18;	author petere;	state Exp;
branches;
next	1.92.2.6;

1.92.2.6
date	2004.01.04.16.44.22;	author petere;	state Exp;
branches;
next	1.92.2.7;

1.92.2.7
date	2004.03.05.19.57.17;	author momjian;	state Exp;
branches;
next	1.92.2.8;

1.92.2.8
date	2004.03.10.00.28.27;	author momjian;	state dead;
branches;
next	;


desc
@@


1.96
log
@Remove HISTORY and INSTALL.  Have them generated by the tarball scripts.

Add README.CVS to help CVS folks find this information.
@
text
@                      PostgreSQL Installation Instructions

This document describes the installation of PostgreSQL from the source code
distribution.

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

Short Version

  ./configure
  gmake
  su
  gmake install
  adduser postgres
  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data
  su - postgres
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
  /usr/local/pgsql/bin/createdb test
  /usr/local/pgsql/bin/psql test

The long version is the rest of this document.

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

Requirements

In general, a modern Unix-compatible platform should be able to run PostgreSQL.
The platforms that had received specific testing at the time of release are
listed in the Section called Supported Platforms below. In the "doc"
subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble. The following
software packages are required for building PostgreSQL:

    * GNU make is required; other make programs will *not* work. GNU make is
      often installed under the name "gmake"; this document will always refer
      to it by that name. (On some systems GNU make is the default tool with
      the name "make".) To test for GNU make enter

        gmake --version

      It is recommended to use version 3.76.1 or later.

    * You need an ISO/ANSI C compiler. Recent versions of GCC are
      recommendable, but PostgreSQL is known to build with a wide variety of
      compilers from different vendors.

    * gzip is needed to unpack the distribution in the first place. If you are
      reading this, you probably already got past that hurdle.

    * The GNU Readline library (for comfortable line editing and command
      history retrieval) will be used by default. If you don't want to use it
      then you must specify the "--without-readline" option for "configure".
      (On NetBSD, the "libedit" library is Readline-compatible and is used if
      "libreadline" is not found.)

    * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
      packages. See the file "doc/FAQ_MSWIN" for details.

The following packages are optional. They are not required in the default
configuration, but they are needed when certain build options are enabled, as
explained below.

    * To build the server programming language PL/Perl you need a full Perl
      installation, including the "libperl" library and the header files. Since
      PL/Perl will be a shared library, the "libperl" library must be a shared
      library also on most platforms. This appears to be the default in recent
      Perl versions, but it was not in earlier versions, and in general it is
      the choice of whomever installed Perl at your site.
      If you don't have the shared library but you need one, a message like
      this will appear during the build to point out this fact:

        *** Cannot build PL/Perl because libperl is not a shared library.
        *** You might have to rebuild your Perl installation.  Refer to
        *** the documentation for details.

      (If you don't follow the on-screen output you will merely notice that the
      PL/Perl library object, "plperl.so" or similar, will not be installed.)
      If you see this, you will have to rebuild and install Perl manually to be
      able to build PL/Perl. During the configuration process for Perl, request
      a shared library.

    * To build the PL/Python server programming language, you need a Python
      installation, including the header files. Since PL/Python will be a
      shared library, the "libpython" library must be a shared library also on
      most platforms. This is not the case in a default Python installation.
      If after building and installing you have a file called "plpython.so"
      (possibly a different extension), then everything went well. Otherwise
      you should have seen a notice like this flying by:

        *** Cannot build PL/Python because libpython is not a shared library.
        *** You might have to rebuild your Python installation.  Refer to
        *** the documentation for details.

      That means you have to rebuild (part of) your Python installation to
      supply this shared library.
      The catch is that the Python distribution or the Python maintainers do
      not provide any direct way to do this. The closest thing we can offer you
      is the information in Python FAQ 3.30. On some operating systems you
      don't really have to build a shared library, but then you will have to
      convince the PostgreSQL build system of this. Consult the "Makefile" in
      the "src/pl/plpython" directory for details.

    * If you want to build Tcl or Tk components (clients and the PL/Tcl
      language) you of course need a Tcl installation.

    * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
      special tool for building Java-based packages. It can be downloaded from
      the Ant web site.
      If you have several Java compilers installed, it depends on the Ant
      configuration which one gets used. Precompiled Ant distributions are
      typically set up to read a file ".antrc" in the current user's home
      directory for configuration. For example, to use a different JDK than the
      default, this may work:

        JAVA_HOME=/usr/local/sun-jdk1.3
        JAVACMD=$JAVA_HOME/bin/java

           Note: Do not try to build the driver by calling "ant" or even
           "javac" directly. This will not work. Run "gmake" normally as
           described below.

    * To enable Native Language Support (NLS), that is, the ability to display
      a program's messages in a language other than English, you need an
      implementation of the Gettext API. Some operating systems have this
      built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
      download an add-on package from here: http://developer.postgresql.org/~petere/
      bsd-gettext/. If you are using the Gettext implementation in the GNU C
      library then you will additionally need the GNU Gettext package for some
      utility programs. For any of the other implementations you will not need
      it.

    * Kerberos, OpenSSL, or PAM, if you want to support authentication using
      these services.

If you are building from a CVS tree instead of using a released source package,
or if you want to do development, you also need the following packages:

    * Flex and Bison are needed to build a CVS checkout or if you changed the
      actual scanner and parser definition files. If you need them, be sure to
      get Flex 2.5.4 or later and Bison 1.875 or later. Other yacc programs can
      sometimes be used, but doing so requires extra effort and is not
      recommended. Other lex programs will definitely not work.

If you need to get a GNU package, you can find it at your local GNU mirror site
(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for
the source tree during compilation and about 15 MB for the installation
directory. An empty database cluster takes about 25 MB, databases take about
five times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need up
to an extra 90 MB. Use the "df" command to check for disk space.

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

If You Are Upgrading

The internal data storage format changes with new releases of PostgreSQL.
Therefore, if you are upgrading an existing installation that does not have a
version number "7.4.x", you must back up and restore your data as shown here.
These instructions assume that your existing installation is under the "/usr/
local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
Substitute your paths appropriately.

   1. Make sure that your database is not updated during or after the backup.
      This does not affect the integrity of the backup, but the changed data
      would of course not be included. If necessary, edit the permissions in
      the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
      access from everyone except you.

   2. To back up your database installation, type:

        pg_dumpall > outputfile

      If you need to preserve OIDs (such as when using them as foreign keys),
      then use the "-o" option when running "pg_dumpall".
      "pg_dumpall" does not save large objects. Check the documentation if you
      need to do this.
      To make the backup, you can use the "pg_dumpall" command from the version
      you are currently running. For best results, however, try to use the
      "pg_dumpall" command from PostgreSQL 7.4, since this version contains
      bug fixes and improvements over older versions. While this advice might
      seem idiosyncratic since you haven't installed the new version yet, it is
      advisable to follow it if you plan to install the new version in parallel
      with the old version. In that case you can complete the installation
      normally and transfer the data later. This will also decrease the
      downtime.

   3. If you are installing the new version at the same location as the old one
      then shut down the old server, at the latest before you install the new
      files:

        kill -INT `cat /usr/local/pgsql/data/postmaster.pid | sed 1q`

      Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
      using such a version you must find out the process ID of the server
      yourself, for example by typing "ps ax | grep postmaster", and supply it
      to the "kill" command.
      On systems that have PostgreSQL started at boot time, there is probably a
      start-up file that will accomplish the same thing. For example, on a Red
      Hat Linux system one might find that

        /etc/rc.d/init.d/postgresql stop

      works. Another possibility is "pg_ctl stop".

   4. If you are installing in the same place as the old version then it is
      also a good idea to move the old installation out of the way, in case you
      have trouble and need to revert to it. Use a command like this:

        mv /usr/local/pgsql /usr/local/pgsql.old

After you have installed PostgreSQL 7.4, create a new database directory and
start the new server. Remember that you must execute these commands while
logged in to the special database user account (which you already have if you
are upgrading).

  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

Finally, restore your data with

  /usr/local/pgsql/bin/psql -d template1 -f outputfile

using the *new* psql.
These topics are discussed at length in the documentation, which you are
encouraged to read in any case.

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

Installation Procedure

   1. Configuration
      The first step of the installation procedure is to configure the source
      tree for your system and choose the options you would like. This is done
      by running the "configure" script. For a default installation simply
      enter

        ./configure

      This script will run a number of tests to guess values for various system
      dependent variables and detect some quirks of your operating system, and
      finally will create several files in the build tree to record what it
      found. (You can also run "configure" in a directory outside the source
      tree if you want to keep the build directory separate.)
      The default configuration will build the server and utilities, as well as
      all client applications and interfaces that require only a C compiler.
      All files will be installed under "/usr/local/pgsql" by default.
      You can customize the build and installation process by supplying one or
      more of the following command line options to "configure":

        --prefix=PREFIX

            Install all files under the directory "PREFIX" instead of "/usr/
            local/pgsql". The actual files will be installed into various
            subdirectories; no files will ever be installed directly into the
            "PREFIX" directory.
            If you have special needs, you can also customize the individual
            subdirectories with the following options.

        --exec-prefix=EXEC-PREFIX

            You can install architecture-dependent files under a different
            prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
            useful to share architecture-independent files between hosts. If
            you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
            architecture-dependent and independent files will be installed
            under the same tree, which is probably what you want.

        --bindir=DIRECTORY

            Specifies the directory for executable programs. The default is
            "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

        --datadir=DIRECTORY

            Sets the directory for read-only data files used by the installed
            programs. The default is "PREFIX/share". Note that this has nothing
            to do with where your database files will be placed.

        --sysconfdir=DIRECTORY

            The directory for various configuration files, "PREFIX/etc" by
            default.

        --libdir=DIRECTORY

            The location to install libraries and dynamically loadable modules.
            The default is "EXEC-PREFIX/lib".

        --includedir=DIRECTORY

            The directory for installing C and C++ header files. The default is
            "PREFIX/include".

        --docdir=DIRECTORY

            Documentation files, except "man" pages, will be installed into
            this directory. The default is "PREFIX/doc".

        --mandir=DIRECTORY

            The man pages that come with PostgreSQL will be installed under
            this directory, in their respective "manx" subdirectories. The
            default is "PREFIX/man".

           Note: Care has been taken to make it possible to install
           PostgreSQL into shared installation locations (such as "/usr/
           local/include") without interfering with the namespace of the
           rest of the system. First, the string "/postgresql" is
           automatically appended to datadir, sysconfdir, and docdir,
           unless the fully expanded directory name already contains the
           string "postgres" or "pgsql". For example, if you choose "/usr/
           local" as prefix, the documentation will be installed in "/usr/
           local/doc/postgresql", but if the prefix is "/opt/postgres",
           then it will be in "/opt/postgres/doc". The public C header
           files of the client interfaces are installed into includedir
           and are namespace-clean. The internal header files and the
           server header files are installed into private directories
           under includedir. See the documentation of each interface for
           information about how to get at the its header files. Finally,
           a private subdirectory will also be created, if appropriate,
           under libdir for dynamically loadable modules.

        --with-includes=DIRECTORIES

            "DIRECTORIES" is a colon-separated list of directories that will be
            added to the list the compiler searches for header files. If you
            have optional packages (such as GNU Readline) installed in a non-
            standard location, you have to use this option and probably also
            the corresponding "--with-libraries" option.
            Example: --with-includes=/opt/gnu/include:/usr/sup/include.

        --with-libraries=DIRECTORIES

            "DIRECTORIES" is a colon-separated list of directories to search
            for libraries. You will probably have to use this option (and the
            corresponding "--with-includes" option) if you have packages
            installed in non-standard locations.
            Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

        --enable-nls[=LANGUAGES]

            Enables Native Language Support (NLS), that is, the ability to
            display a program's messages in a language other than English.
            "LANGUAGES" is a space separated list of codes of the languages
            that you want supported, for example --enable-nls='de fr'. (The
            intersection between your list and the set of actually provided
            translations will be computed automatically.) If you do not specify
            a list, then all available translations are installed.
            To use this option, you will need an implementation of the Gettext
            API; see above.

        --with-pgport=NUMBER

            Set "NUMBER" as the default port number for server and clients. The
            default is 5432. The port can always be changed later on, but if
            you specify it here then both server and clients will have the same
            default compiled in, which can be very convenient. Usually the only
            good reason to select a non-default value is if you intend to run
            multiple PostgreSQL servers on the same machine.

        --with-perl

            Build the PL/Perl server-side language.

        --with-python

            Build the PL/Python server-side language.

        --with-tcl

            Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
            pgtksh, and PL/Tcl. But see below about "--without-tk".

        --without-tk

            If you specify "--with-tcl" and this option, then the program that
            requires Tk (pgtksh) will be excluded.

        --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY

            Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
            contain configuration information needed to build modules
            interfacing to Tcl or Tk. These files are normally found
            automatically at their well-known locations, but if you want to use
            a different version of Tcl or Tk you can specify the directory in
            which to find them.

        --with-java

            Build the JDBC driver and associated Java packages.

        --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY]

            Build with support for Kerberos authentication. You can use either
            Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
            specifies the root directory of the Kerberos installation; "/usr/
            athena" is assumed as default. If the relevant header files and
            libraries are not under a common parent directory, then you must
            use the "--with-includes" and "--with-libraries" options in
            addition to this option. If, on the other hand, the required files
            are in a location that is searched by default (e.g., "/usr/lib"),
            then you can leave off the argument.
            "configure" will check for the required header files and libraries
            to make sure that your Kerberos installation is sufficient before
            proceeding.

        --with-krb-srvnam=NAME

            The name of the Kerberos service principal. postgres is the
            default. There's probably no reason to change this.

        --with-openssl[=DIRECTORY]

            Build with support for SSL (encrypted) connections. This requires
            the OpenSSL package to be installed. The "DIRECTORY" argument
            specifies the root directory of the OpenSSL installation; the
            default is "/usr/local/ssl".
            "configure" will check for the required header files and libraries
            to make sure that your OpenSSL installation is sufficient before
            proceeding.

        --with-pam

            Build with PAM (Pluggable Authentication Modules) support.

        --without-readline

            Prevents the use of the Readline library. This disables command-
            line editing and history in psql, so it is not recommended.

        --with-rendezvous

            Build with Rendezvous support.

        --disable-spinlocks

            Allow the builds to succeed even if PostgreSQL has no CPU spinlock
            support for the platform. The lack of spinlock support will result
            in poor performance; therefore, this option should only be used if
            the build aborts and informs you that the platform lacks spinlock
            support.

        --enable-thread-safety

            Make the client libraries thread-safe. This allows concurrent
            threads in libpq and ECPG programs to safely control their private
            connection handles.

        --without-zlib

            Prevents the use of the Zlib library. This disables compression
            support in pg_dump. This option is only intended for those rare
            systems where this library is not available.

        --enable-debug

            Compiles all programs and libraries with debugging symbols. This
            means that you can run the programs through a debugger to analyze
            problems. This enlarges the size of the installed executables
            considerably, and on non-GCC compilers it usually also disables
            compiler optimization, causing slowdowns. However, having the
            symbols available is extremely helpful for dealing with any
            problems that may arise. Currently, this option is recommended for
            production installations only if you use GCC. But you should always
            have it on if you are doing development work or running a beta
            version.

        --enable-cassert

            Enables assertion checks in the server, which test for many "can't
            happen" conditions. This is invaluable for code development
            purposes, but the tests slow things down a little. Also, having the
            tests turned on won't necessarily enhance the stability of your
            server! The assertion checks are not categorized for severity, and
            so what might be a relatively harmless bug will still lead to
            server restarts if it triggers an assertion failure. Currently,
            this option is not recommended for production use, but you should
            have it on for development work or when running a beta version.

        --enable-depend

            Enables automatic dependency tracking. With this option, the
            makefiles are set up so that all affected object files will be
            rebuilt when any header file is changed. This is useful if you are
            doing development work, but is just wasted overhead if you intend
            only to compile once and install. At present, this option will work
            only if you use GCC.

      If you prefer a C compiler different from the one "configure" picks then
      you can set the environment variable CC to the program of your choice. By
      default, "configure" will pick "gcc" unless this is inappropriate for the
      platform. Similarly, you can override the default compiler flags with the
      CFLAGS variable.

      You can specify environment variables on the "configure" command line,
      for example:

        ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'

   2. Build
      To start the build, type

        gmake

      (Remember to use GNU make.) The build may take anywhere from 5 minutes to
      half an hour depending on your hardware. The last line displayed should
      be

        All of PostgreSQL is successfully made. Ready to install.

   3. Regression Tests
      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. Type

        gmake check

      (This won't work as root; do it as an unprivileged user.) The file "src/
      test/regress/README" and the documentation contain detailed information
      about interpreting the test results. You can repeat this test at any
      later time by issuing the same command.

   4. Installing The Files
           Note: If you are upgrading an existing system and are going to
           install the new files over the old ones, then you should have
           backed up your data and shut down the old server by now, as
           explained in
           the Section called If You Are Upgrading
            above.
      To install PostgreSQL enter

        gmake install

      This will install files into the directories that were specified in step
      1. Make sure that you have appropriate permissions to write into that
      area. Normally you need to do this step as root. Alternatively, you could
      create the target directories in advance and arrange for appropriate
      permissions to be granted.
      You can use gmake install-strip instead of gmake install to strip the
      executable files and libraries as they are installed. This will save some
      space. If you built with debugging support, stripping will effectively
      remove the debugging support, so it should only be done if debugging is
      no longer needed. install-strip tries to do a reasonable job saving
      space, but it does not have perfect knowledge of how to strip every
      unneeded byte from an executable file, so if you want to save all the
      disk space you possibly can, you will have to do manual work.
      The standard installation provides only the header files needed for
      client application development. If you plan to do any server-side program
      development (such as custom functions or data types written in C), then
      you may want to install the entire PostgreSQL include tree into your
      target include directory. To do that, enter

        gmake install-all-headers

      This adds a megabyte or two to the installation footprint, and is only
      useful if you don't plan to keep the whole source tree around for
      reference. (If you do, you can just use the source's include directory
      when building server-side software.)
      Client-only installation: If you want to install only the client
      applications and interface libraries, then you can use these commands:

        gmake -C src/bin install
        gmake -C src/include install
        gmake -C src/interfaces install
        gmake -C doc install

Uninstallation: To undo the installation use the command "gmake uninstall".
However, this will not remove any created directories.
Cleaning: After the installation you can make room by removing the built files
from the source tree with the command "gmake clean". This will preserve the
files made by the "configure" program, so that you can rebuild everything with
"gmake" later on. To reset the source tree to the state in which it was
distributed, use "gmake distclean". If you are going to build for several
platforms from the same source tree you must do this and re-configure for each
build.
If you perform a build and then discover that your "configure" options were
wrong, or if you change anything that "configure" investigates (for example,
software upgrades), then it's a good idea to do "gmake distclean" before
reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.

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

Post-Installation Setup

Shared Libraries

On some systems that have shared libraries (which most systems do) you need to
tell your system how to find the newly installed shared libraries. The systems
on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
The method to set the shared library search path varies between platforms, but
the most widely usable method is to set the environment variable
LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh")

  LD_LIBRARY_PATH=/usr/local/pgsql/lib
  export LD_LIBRARY_PATH

or in "csh" or "tcsh"

  setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
should put these commands into a shell start-up file such as "/etc/profile" or
"~/.bash_profile". Some good information about the caveats associated with this
method can be found at http://www.visi.com/~barr/ldpath.html.
On some systems it might be preferable to set the environment variable
LD_RUN_PATH *before* building.
On Cygwin, put the library directory in the PATH or move the ".dll" files into
the "bin" directory.
If in doubt, refer to the manual pages of your system (perhaps "ld.so" or
"rld"). 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 this step was necessary. Simply take care of it then.
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run

  /sbin/ldconfig /usr/local/pgsql/lib

(or equivalent directory) after installation to enable the run-time linker to
find the shared libraries faster. Refer to the manual page of "ldconfig" for
more information. On FreeBSD, NetBSD, and OpenBSD the command is

  /sbin/ldconfig -m /usr/local/pgsql/lib

instead. Other systems are not known to have an equivalent command.

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

Environment Variables

If you installed into "/usr/local/pgsql" or some other location that is not
searched for programs by default, you should add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as
"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):

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

If you are using "csh" or "tcsh", then use this command:

  set path = ( /usr/local/pgsql/bin $path )

To enable your system to find the man documentation, you need to add lines like
the following to a shell start-up file unless you installed into a location
that is searched by default.

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

The environment variables PGHOST and PGPORT specify to client applications the
host and port of the database server, overriding the compiled-in defaults. If
you are going to run client applications remotely then it is convenient if
every user that plans to use the database sets PGHOST. This is not required,
however: the settings can be communicated via command line options to most
client programs.

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

Getting Started

The following is a quick summary of how to get PostgreSQL up and running once
installed. The main documentation contains more information.

   1. Create a user account for the PostgreSQL server. 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,
      but running the server as root is a security risk and will not work.

        adduser postgres

   2. Create a database installation with the "initdb" command. To run "initdb"
      you must be logged in to your PostgreSQL server account. It will not work
      as root.

        root# mkdir /usr/local/pgsql/data
        root# chown postgres /usr/local/pgsql/data
        root# su - postgres
        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 server account can write to the
      directory (or create it, if it doesn't already exist) before starting
      "initdb", as illustrated here.

   3. 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 put the server in the
      background use something like

        nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
            </dev/null >>server.log 2>&1 </dev/null &

      To stop a server running in the background you can type

        kill `cat /usr/local/pgsql/data/postmaster.pid`

      In order to allow TCP/IP connections (rather than only Unix domain socket
      ones) you need to pass the "-i" option to "postmaster".

   4. Create a database:

        createdb testdb

      Then enter

        psql testdb

      to connect to that database. At the prompt you can enter SQL commands and
      start experimenting.

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

What Now?

    * The PostgreSQL distribution contains a comprehensive documentation set,
      which you should read sometime. After installation, the documentation can
      be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
      index.html", unless you changed the installation directories.
      The first few chapters of the main documentation are the Tutorial, which
      should be your first reading if you are completely new to SQL databases.
      If you are familiar with database concepts then you want to proceed with
      part on server administration, which contains information about how to
      set up the database server, database users, and authentication.

    * Usually, you will want to modify your computer so that it will
      automatically start the database server whenever it boots. Some
      suggestions for this are in the documentation.

    * Run the regression tests against the installed server (using "gmake
      installcheck"). If you didn't run the tests before installation, you
      should definitely do it now. This is also explained in the documentation.

    * By default, PostgreSQL is configured to run on minimal hardware. This
      allows it to start up with almost any hardware configuration. The default
      configuration is, however, not designed for optimum performance. To
      achieve optimum performance, several server parameters must be adjusted,
      the two most common being shared_buffers and sort_mem mentioned in the
      documentation. Other parameters mentioned in the documentation also
      affect performance.

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

Supported Platforms

PostgreSQL has been verified by the developer community to work on the
platforms listed below. A supported platform generally means that PostgreSQL
builds and installs according to these instructions and that the regression
tests pass.
     Note: If you are having problems with the installation on a supported
     platform, please write to <pgsql-bugs@@postgresql.org> or <pgsql-
     ports@@postgresql.org>, not to the people listed here.
 _____________________________________________________________________________
|OS__________|Processor|Version|Reported______________________|Remarks________|
|AIX         |RS6000   |7.4    |2003-10-25, Hans-Jrgen       |see also doc/  |
|____________|_________|_______|Schnig_(<hs@@cybertec.at>)____|FAQ_AIX________|
|BSD/OS      |x86      |7.4    |2003-10-24, Bruce Momjian     |4.3            |
|____________|_________|_______|(<pgman@@candle.pha.pa.us>)____|_______________|
|FreeBSD     |Alpha    |7.4    |2003-10-25, Peter Eisentraut  |4.8            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|FreeBSD     |x86      |7.4    |2003-10-24, Peter Eisentraut  |4.9            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|HP-UX       |PA-RISC  |7.4    |2003-10-31, 10.20, Tom Lane   |gcc and cc; see|
|            |         |       |(<tgl@@sss.pgh.pa.us>); 2003-  |also doc/      |
|            |         |       |11-04, 11.00, Peter Eisentraut|FAQ_HPUX       |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|IRIX        |MIPS     |7.4    |2003-11-12, Robert E.         |6.5.20, cc only|
|            |         |       |Bruccoleri                    |               |
|____________|_________|_______|(<bruc@@stone.congenomics.com>)|_______________|
|Linux       |Alpha    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |arm41    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Itanium  |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |m68k     |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |MIPS     |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Opteron  |7.4    |2003-11-01, Jani Averbach     |2.6            |
|____________|_________|_______|(<jaa@@cc.jyu.fi>)_____________|_______________|
|Linux       |PPC      |7.4    |2003-10-25, Nol Kthe        |               |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |S/390    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Sparc    |7.4    |2003-10-24, Peter Eisentraut  |2.4, 32-bit    |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|Linux       |x86      |7.4    |2003-10-24, Peter Eisentraut  |2.4            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|MacOS X     |PPC      |7.4    |2003-10-24, 10.2.8, Adam      |               |
|            |         |       |Witney                        |               |
|            |         |       |(<awitney@@sghms.ac.uk>), 10.3,|               |
|            |         |       |Marko Karppinen               |               |
|____________|_________|_______|(<marko@@karppinen.fi>)________|_______________|
|NetBSD      |arm32    |7.4    |2003-11-12, Patrick Welche    |1.6ZE/acorn32  |
|____________|_________|_______|(<prlw1@@newn.cam.ac.uk>)______|_______________|
|NetBSD      |x86      |7.4    |2003-10-24, Peter Eisentraut  |1.6            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|OpenBSD     |Sparc    |7.4    |2003-11-01, Peter Eisentraut  |3.4            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|OpenBSD     |x86      |7.4    |2003-10-24, Peter Eisentraut  |3.2            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|Solaris     |Sparc    |7.4    |2003-10-26, Christopher Browne|2.8; see also  |
|____________|_________|_______|(<cbbrowne@@libertyrms.info>)__|doc/FAQ_Solaris|
|Solaris     |x86      |7.4    |2003-10-26, Kurt Roeckx       |2.6 see also   |
|____________|_________|_______|(<Q@@ping.be>)_________________|doc/FAQ_Solaris|
|Tru64 UNIX  |Alpha    |7.4    |2003-10-25, 5.1b, Peter       |               |
|            |         |       |Eisentraut                    |               |
|            |         |       |(<peter_e@@gmx.net>); 2003-10- |               |
|            |         |       |29, 4.0g, Alessio Bragadini   |               |
|____________|_________|_______|(<alessio@@albourne.com>)______|_______________|
|UnixWare    |x86      |7.4    |2003-11-03, Larry Rosenman    |7.1.3; join    |
|            |         |       |(<ler@@lerctr.org>)            |test may fail, |
|            |         |       |                              |see also doc/  |
|____________|_________|_______|______________________________|FAQ_SCO________|
|Windows with|x86      |7.4    |2003-10-24, Peter Eisentraut  |see doc/       |
|Cygwin______|_________|_______|(<peter_e@@gmx.net>)___________|FAQ_MSWIN______|
|Windows     |x86      |7.4    |2003-10-27, Dave Page         |native is      |
|            |         |       |(<dpage@@vale-housing.co.uk>)  |client-side    |
|            |         |       |                              |only, see      |
|____________|_________|_______|______________________________|documentation__|

Unsupported Platforms: The following platforms are either known not to work, or
they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.4 at the time this list was
compiled. We include these here to let you know that these platforms *could* be
supported if given some attention.
 ________________________________________________________________________________
|OS________|Processor__|Version|Reported_______________________|Remarks__________|
|BeOS      |x86        |7.2    |2001-11-29, Cyril Velter       |needs updates to |
|__________|___________|_______|(<cyril.velter@@libertysurf.fr>)|semaphore_code___|
|Linux     |PlayStation|7.4    |2003-11-02, Peter Eisentraut   |needs new        |
|          |2          |       |(<peter_e@@gmx.net>)            |config.guess, -- |
|          |           |       |                               |disable-         |
|          |           |       |                               |spinlocks, #undef|
|          |           |       |                               |HAS_TEST_AND_SET,|
|          |           |       |                               |disable tas_dummy|
|__________|___________|_______|_______________________________|()_______________|
|Linux     |PA-RISC    |7.4    |2003-10-25, Nol Kthe         |needs --disable- |
|          |           |       |(<noel@@debian.org>)            |spinlocks,       |
|__________|___________|_______|_______________________________|otherwise_OK_____|
|NetBSD    |Alpha      |7.2    |2001-11-20, Thomas Thai        |1.5W             |
|__________|___________|_______|(<tom@@minnesota.com>)__________|_________________|
|NetBSD    |MIPS       |7.2.1  |2002-06-13, Warwick Hunter     |1.5.3            |
|__________|___________|_______|(<whunter@@agile.tv>)___________|_________________|
|NetBSD    |PPC        |7.2    |2001-11-28, Bill Studenmund    |1.5              |
|__________|___________|_______|(<wrstuden@@netbsd.org>)________|_________________|
|NetBSD    |Sparc      |7.2    |2001-12-03, Matthew Green      |32- and 64-bit   |
|__________|___________|_______|(<mrg@@eterna.com.au>)__________|builds___________|
|NetBSD    |VAX        |7.1    |2001-03-30, Tom I. Helbekkmo   |1.5              |
|__________|___________|_______|(<tih@@kpnQwest.no>)____________|_________________|
|QNX 4 RTOS|x86        |7.2    |2001-12-10, Bernd Tegge        |needs updates to |
|          |           |       |(<tegge@@repas-aeg.de>)         |semaphore code;  |
|          |           |       |                               |see also doc/    |
|__________|___________|_______|_______________________________|FAQ_QNX4_________|
|QNX RTOS  |x86        |7.2    |2001-11-20, Igor Kovalenko     |patches available|
|v6        |           |       |(<Igor.Kovalenko@@motorola.com>)|in archives, but |
|__________|___________|_______|_______________________________|too_late_for_7.2_|
|SCO       |x86        |7.3.1  |2002-12-11, Shibashish Satpathy|5.0.4, gcc; see  |
|OpenServer|___________|_______|(<shib@@postmark.net>)__________|also_doc/FAQ_SCO_|
|SunOS 4   |Sparc      |7.2    |2001-12-04, Tatsuo Ishii (<t-  |                 |
|__________|___________|_______|ishii@@sra.co.jp>)______________|_________________|
@


1.95
log
@Correct gettext URL.
@
text
@@


1.94
log
@Fix instructions how to shut down postmaster.
@
text
@d128 2
a129 2
      download an add-on package from here: http://www.postgresql.org/~petere/
      gettext.html. If you are using the Gettext implementation in the GNU C
@


1.93
log
@Regenerate text files.
@
text
@d195 1
a195 1
        kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
@


1.92
log
@Update INSTALL to say beta5.
@
text
@d1 252
a253 234
                    PostgreSQL Installation Instructions
                                      
   This document describes the installation of PostgreSQL from the source
   code distribution.
     _________________________________________________________________
   
                               Short Version
                                      
./configure
gmake
su
gmake install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test

   The long version is the rest of this document.
     _________________________________________________________________
   
                                Requirements
                                      
   In general, a modern Unix-compatible platform should be able to run
   PostgreSQL. The platforms that had received specific testing at the
   time of release are listed in the section called Supported Platforms
   below. In the "doc" subdirectory of the distribution there are several
   platform-specific FAQ documents you might wish to consult if you are
   having trouble.
   
   The following software packages are required for building PostgreSQL:
   
     * GNU make is required; other make programs will *not* work. GNU
       make is often installed under the name "gmake"; this document will
       always refer to it by that name. (On some systems GNU make is the
       default tool with the name "make".) To test for GNU make enter
gmake --version
       It is recommended to use version 3.76.1 or later.
     * You need an ISO/ANSI C compiler. Recent versions of GCC are
       recommendable, but PostgreSQL is known to build with a wide
       variety of compilers from different vendors.
     * gzip is needed to unpack the distribution in the first place. If
       you are reading this, you probably already got past that hurdle.
     * The GNU Readline library (for comfortable line editing and command
       history retrieval) will be used by default. If you don't want to
       use it then you must specify the "--without-readline" option for
       "configure". (On NetBSD, the "libedit" library is
       Readline-compatible and is used if "libreadline" is not found.)
     * To build on Windows NT or Windows 2000 you need the Cygwin and
       cygipc packages. See the file "doc/FAQ_MSWIN" for details.
       
   The following packages are optional. They are not required in the
   default configuration, but they are needed when certain build options
   are enabled, as explained below.
   
     * To build the server programming language PL/Perl you need a full
       Perl installation, including the "libperl" library and the header
       files. Since PL/Perl will be a shared library, the "libperl"
       library must be a shared library also on most platforms. This
       appears to be the default in recent Perl versions, but it was not
       in earlier versions, and in general it is the choice of whomever
       installed Perl at your site.
       If you don't have the shared library but you need one, a message
       like this will appear during the build to point out this fact:
*** Cannot build PL/Perl because libperl is not a shared library.
*** You might have to rebuild your Perl installation.  Refer to
*** the documentation for details.
       (If you don't follow the on-screen output you will merely notice
       that the PL/Perl library object, "plperl.so" or similar, will not
       be installed.) If you see this, you will have to rebuild and
       install Perl manually to be able to build PL/Perl. During the
       configuration process for Perl, request a shared library.
     * To build the PL/Python server programming language, you need a
       Python installation, including the header files. Since PL/Python
       will be a shared library, the "libpython" library must be a shared
       library also on most platforms. This is not the case in a default
       Python installation.
       If after building and installing you have a file called
       "plpython.so" (possibly a different extension), then everything
       went well. Otherwise you should have seen a notice like this
       flying by:
*** Cannot build PL/Python because libpython is not a shared library.
*** You might have to rebuild your Python installation.  Refer to
*** the documentation for details.
       That means you have to rebuild (part of) your Python installation
       to supply this shared library.
       The catch is that the Python distribution or the Python
       maintainers do not provide any direct way to do this. The closest
       thing we can offer you is the information in Python FAQ 3.30. On
       some operating systems you don't really have to build a shared
       library, but then you will have to convince the PostgreSQL build
       system of this. Consult the "Makefile" in the "src/pl/plpython"
       directory for details.
     * If you want to build Tcl or Tk components (clients and the PL/Tcl
       language) you of course need a Tcl installation.
     * To build the JDBC driver, you need Ant 1.5 or higher and a JDK.
       Ant is a special tool for building Java-based packages. It can be
       downloaded from the Ant web site.
       If you have several Java compilers installed, it depends on the
       Ant configuration which one gets used. Precompiled Ant
       distributions are typically set up to read a file ".antrc" in the
       current user's home directory for configuration. For example, to
       use a different JDK than the default, this may work:
JAVA_HOME=/usr/local/sun-jdk1.3
JAVACMD=$JAVA_HOME/bin/java
       
     Note: Do not try to build the driver by calling "ant" or even
     "javac" directly. This will not work. Run "gmake" normally as
     described below.
     * To enable Native Language Support (NLS), that is, the ability to
       display a program's messages in a language other than English, you
       need an implementation of the Gettext API. Some operating systems
       have this built-in (e.g., Linux, NetBSD, Solaris), for other
       systems you can download an add-on package from here:
       http://www.postgresql.org/~petere/gettext.html. If you are using
       the Gettext implementation in the GNU C library then you will
       additionally need the GNU Gettext package for some utility
       programs. For any of the other implementations you will not need
       it.
     * Kerberos, OpenSSL, or PAM, if you want to support authentication
       using these services.
       
   If you are building from a CVS tree instead of using a released source
   package, or if you want to do development, you also need the following
   packages:
   
     * Flex and Bison are needed to build a CVS checkout or if you
       changed the actual scanner and parser definition files. If you
       need them, be sure to get Flex 2.5.4 or later and Bison 1.875 or
       later. Other yacc programs can sometimes be used, but doing so
       requires extra effort and is not recommended. Other lex programs
       will definitely not work.
       
   If you need to get a GNU package, you can find it at your local GNU
   mirror site (see http://www.gnu.org/order/ftp.html for a list) or at
   ftp://ftp.gnu.org/gnu/.
   
   Also check that you have sufficient disk space. You will need about 65
   MB for the source tree during compilation and about 15 MB for the
   installation directory. An empty database cluster takes about 25 MB,
   databases take about five times the amount of space that a flat text
   file with the same data would take. If you are going to run the
   regression tests you will temporarily need up to an extra 90 MB. Use
   the "df" command to check for disk space.
     _________________________________________________________________
   
                            If You Are Upgrading
                                      
   The internal data storage format changes with new releases of
   PostgreSQL. Therefore, if you are upgrading an existing installation
   that does not have a version number "7.4.x", you must back up and
   restore your data as shown here. These instructions assume that your
   existing installation is under the "/usr/local/pgsql" directory, and
   that the data area is in "/usr/local/pgsql/data". Substitute your
   paths appropriately.
    1. Make sure that your database is not updated during or after the
       backup. This does not affect the integrity of the backup, but the
       changed data would of course not be included. If necessary, edit
       the permissions in the file "/usr/local/pgsql/data/pg_hba.conf"
       (or equivalent) to disallow access from everyone except you.
    2. To back up your database installation, type:
pg_dumpall > outputfile
       If you need to preserve OIDs (such as when using them as foreign
       keys), then use the "-o" option when running "pg_dumpall".
       "pg_dumpall" does not save large objects. Check the documentation
       if you need to do this.
       To make the backup, you can use the "pg_dumpall" command from the
       version you are currently running. For best results, however, try
       to use the "pg_dumpall" command from PostgreSQL 7.4beta5, since
       this version contains bug fixes and improvements over older
       versions. While this advice might seem idiosyncratic since you
       haven't installed the new version yet, it is advisable to follow
       it if you plan to install the new version in parallel with the old
       version. In that case you can complete the installation normally
       and transfer the data later. This will also decrease the downtime.
    3. If you are installing the new version at the same location as the
       old one then shut down the old server, at the latest before you
       install the new files:
kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
       Versions prior to 7.0 do not have this "postmaster.pid" file. If
       you are using such a version you must find out the process ID of
       the server yourself, for example by typing "ps ax | grep
       postmaster", and supply it to the "kill" command.
       On systems that have PostgreSQL started at boot time, there is
       probably a start-up file that will accomplish the same thing. For
       example, on a Red Hat Linux system one might find that
/etc/rc.d/init.d/postgresql stop
       works. Another possibility is "pg_ctl stop".
    4. If you are installing in the same place as the old version then it
       is also a good idea to move the old installation out of the way,
       in case you have trouble and need to revert to it. Use a command
       like this:
mv /usr/local/pgsql /usr/local/pgsql.old
       
   After you have installed PostgreSQL 7.4beta5, create a new database
   directory and start the new server. Remember that you must execute
   these commands while logged in to the special database user account
   (which you already have if you are upgrading).
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

   Finally, restore your data with
/usr/local/pgsql/bin/psql -d template1 -f outputfile

   using the *new* psql.
   
   These topics are discussed at length in the documentation, which you
   are encouraged to read in any case.
     _________________________________________________________________
   
                           Installation Procedure
                                      
    1. Configuration
       The first step of the installation procedure is to configure the
       source tree for your system and choose the options you would like.
       This is done by running the "configure" script. For a default
       installation simply enter
./configure
       This script will run a number of tests to guess values for various
       system dependent variables and detect some quirks of your
       operating system, and finally will create several files in the
       build tree to record what it found. (You can also run "configure"
       in a directory outside the source tree if you want to keep the
       build directory separate.)
       The default configuration will build the server and utilities, as
       well as all client applications and interfaces that require only a
       C compiler. All files will be installed under "/usr/local/pgsql"
       by default.
       You can customize the build and installation process by supplying
       one or more of the following command line options to "configure":
       
d255 8
a262 8
                Install all files under the directory "PREFIX" instead of
                "/usr/local/pgsql". The actual files will be installed
                into various subdirectories; no files will ever be
                installed directly into the "PREFIX" directory.
                
                If you have special needs, you can also customize the
                individual subdirectories with the following options.
                
d264 8
a271 9
                You can install architecture-dependent files under a
                different prefix, "EXEC-PREFIX", than what "PREFIX" was
                set to. This can be useful to share
                architecture-independent files between hosts. If you omit
                this, then "EXEC-PREFIX" is set equal to "PREFIX" and
                both architecture-dependent and independent files will be
                installed under the same tree, which is probably what you
                want.
                
d273 4
a276 4
                Specifies the directory for executable programs. The
                default is "EXEC-PREFIX/bin", which normally means
                "/usr/local/pgsql/bin".
                
d278 5
a282 5
                Sets the directory for read-only data files used by the
                installed programs. The default is "PREFIX/share". Note
                that this has nothing to do with where your database
                files will be placed.
                
d284 4
a287 3
                The directory for various configuration files,
                "PREFIX/etc" by default.
                
d289 4
a292 3
                The location to install libraries and dynamically
                loadable modules. The default is "EXEC-PREFIX/lib".
                
d294 4
a297 3
                The directory for installing C and C++ header files. The
                default is "PREFIX/include".
                
d299 4
a302 4
                Documentation files, except "man" pages, will be
                installed into this directory. The default is
                "PREFIX/doc".
                
d304 23
a326 21
                The man pages that come with PostgreSQL will be installed
                under this directory, in their respective "manx"
                subdirectories. The default is "PREFIX/man".
                
     Note: Care has been taken to make it possible to install PostgreSQL
     into shared installation locations (such as "/usr/local/include")
     without interfering with the namespace of the rest of the system.
     First, the string "/postgresql" is automatically appended to
     datadir, sysconfdir, and docdir, unless the fully expanded
     directory name already contains the string "postgres" or "pgsql".
     For example, if you choose "/usr/local" as prefix, the
     documentation will be installed in "/usr/local/doc/postgresql", but
     if the prefix is "/opt/postgres", then it will be in
     "/opt/postgres/doc". The public C header files of the client
     interfaces are installed into includedir and are namespace-clean.
     The internal header files and the server header files are installed
     into private directories under includedir. See the documentation of
     each interface for information about how to get at the its header
     files. Finally, a private subdirectory will also be created, if
     appropriate, under libdir for dynamically loadable modules.
       
d328 8
a335 10
                "DIRECTORIES" is a colon-separated list of directories
                that will be added to the list the compiler searches for
                header files. If you have optional packages (such as GNU
                Readline) installed in a non-standard location, you have
                to use this option and probably also the corresponding
                "--with-libraries" option.
                
                Example:
                --with-includes=/opt/gnu/include:/usr/sup/include.
                
d337 7
a343 7
                "DIRECTORIES" is a colon-separated list of directories to
                search for libraries. You will probably have to use this
                option (and the corresponding "--with-includes" option)
                if you have packages installed in non-standard locations.
                
                Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
                
d345 11
a355 12
                Enables Native Language Support (NLS), that is, the
                ability to display a program's messages in a language
                other than English. "LANGUAGES" is a space separated list
                of codes of the languages that you want supported, for
                example --enable-nls='de fr'. (The intersection between
                your list and the set of actually provided translations
                will be computed automatically.) If you do not specify a
                list, then all available translations are installed.
                
                To use this option, you will need an implementation of
                the Gettext API; see above.
                
d357 8
a364 8
                Set "NUMBER" as the default port number for server and
                clients. The default is 5432. The port can always be
                changed later on, but if you specify it here then both
                server and clients will have the same default compiled
                in, which can be very convenient. Usually the only good
                reason to select a non-default value is if you intend to
                run multiple PostgreSQL servers on the same machine.
                
d366 3
a368 2
                Build the PL/Perl server-side language.
                
d370 3
a372 2
                Build the PL/Python server-side language.
                
d374 4
a377 4
                Build components that require Tcl/Tk, which are libpgtcl,
                pgtclsh, pgtksh, and PL/Tcl. But see below about
                "--without-tk".
                
d379 4
a382 3
                If you specify "--with-tcl" and this option, then the
                program that requires Tk (pgtksh) will be excluded.
                
d384 8
a391 8
                Tcl/Tk installs the files "tclConfig.sh" and
                "tkConfig.sh", which contain configuration information
                needed to build modules interfacing to Tcl or Tk. These
                files are normally found automatically at their
                well-known locations, but if you want to use a different
                version of Tcl or Tk you can specify the directory in
                which to find them.
                
d393 3
a395 2
                Build the JDBC driver and associated Java packages.
                
d397 14
a410 16
                Build with support for Kerberos authentication. You can
                use either Kerberos version 4 or 5, but not both. The
                "DIRECTORY" argument specifies the root directory of the
                Kerberos installation; "/usr/athena" is assumed as
                default. If the relevant header files and libraries are
                not under a common parent directory, then you must use
                the "--with-includes" and "--with-libraries" options in
                addition to this option. If, on the other hand, the
                required files are in a location that is searched by
                default (e.g., "/usr/lib"), then you can leave off the
                argument.
                
                "configure" will check for the required header files and
                libraries to make sure that your Kerberos installation is
                sufficient before proceeding.
                
d412 4
a415 3
                The name of the Kerberos service principal. postgres is
                the default. There's probably no reason to change this.
                
d417 9
a425 9
                Build with support for SSL (encrypted) connections. This
                requires the OpenSSL package to be installed. The
                "DIRECTORY" argument specifies the root directory of the
                OpenSSL installation; the default is "/usr/local/ssl".
                
                "configure" will check for the required header files and
                libraries to make sure that your OpenSSL installation is
                sufficient before proceeding.
                
d427 3
a429 3
                Build with PAM (Pluggable Authentication Modules)
                support.
                
d431 4
a434 4
                Prevents the use of the Readline library. This disables
                command-line editing and history in psql, so it is not
                recommended.
                
d436 3
a438 2
                Build with Rendezvous support.
                
d440 7
a446 5
                Allows source builds to succeed without CPU spinlock
                support. Lack of spinlock support will produce poor
                performance. This option is to be used only by platforms
                lacking spinlock support.
                
d448 5
a452 3
                Allow separate libpq and ecpg threads to safely control
                their private connection handles.
                
d454 5
a458 5
                Prevents the use of the Zlib library. This disables
                compression support in pg_dump. This option is only
                intended for those rare systems where this library is not
                available.
                
d460 12
a471 12
                Compiles all programs and libraries with debugging
                symbols. This means that you can run the programs through
                a debugger to analyze problems. This enlarges the size of
                the installed executables considerably, and on non-GCC
                compilers it usually also disables compiler optimization,
                causing slowdowns. However, having the symbols available
                is extremely helpful for dealing with any problems that
                may arise. Currently, this option is recommended for
                production installations only if you use GCC. But you
                should always have it on if you are doing development
                work or running a beta version.
                
d473 11
a483 12
                Enables assertion checks in the server, which test for
                many "can't happen" conditions. This is invaluable for
                code development purposes, but the tests slow things down
                a little. Also, having the tests turned on won't
                necessarily enhance the stability of your server! The
                assertion checks are not categorized for severity, and so
                what might be a relatively harmless bug will still lead
                to server restarts if it triggers an assertion failure.
                Currently, this option is not recommended for production
                use, but you should have it on for development work or
                when running a beta version.
                
d485 393
a877 355
                Enables automatic dependency tracking. With this option,
                the makefiles are set up so that all affected object
                files will be rebuilt when any header file is changed.
                This is useful if you are doing development work, but is
                just wasted overhead if you intend only to compile once
                and install. At present, this option will work only if
                you use GCC.
                
       If you prefer a C compiler different from the one "configure"
       picks then you can set the environment variable CC to the program
       of your choice. By default, "configure" will pick "gcc" unless
       this is inappropriate for the platform. Similarly, you can
       override the default compiler flags with the CFLAGS variable.
       You can specify environment variables on the "configure" command
       line, for example:
./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'
    2. Build
       To start the build, type
gmake
       (Remember to use GNU make.) The build may take anywhere from 5
       minutes to half an hour depending on your hardware. The last line
       displayed should be
All of PostgreSQL is successfully made. Ready to install.
    3. Regression Tests
       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. Type
gmake check
       (This won't work as root; do it as an unprivileged user.) It is
       possible that some tests fail, due to differences in error message
       wording or floating point results. The file
       "src/test/regress/README" and the documentation contain detailed
       information about interpreting the test results. You can repeat
       this test at any later time by issuing the same command.
    4. Installing The Files
       
     Note: If you are upgrading an existing system and are going to
     install the new files over the old ones, then you should have
     backed up your data and shut down the old server by now, as
     explained in the section called If You Are Upgrading above.
       To install PostgreSQL enter
gmake install
       This will install files into the directories that were specified
       in step 1. Make sure that you have appropriate permissions to
       write into that area. Normally you need to do this step as root.
       Alternatively, you could create the target directories in advance
       and arrange for appropriate permissions to be granted.
       You can use gmake install-strip instead of gmake install to strip
       the executable files and libraries as they are installed. This
       will save some space. If you built with debugging support,
       stripping will effectively remove the debugging support, so it
       should only be done if debugging is no longer needed.
       install-strip tries to do a reasonable job saving space, but it
       does not have perfect knowledge of how to strip every unneeded
       byte from an executable file, so if you want to save all the disk
       space you possibly can, you will have to do manual work.
       The standard installation provides only the header files needed
       for client application development. If you plan to do any
       server-side program development (such as custom functions or data
       types written in C), then you may want to install the entire
       PostgreSQL include tree into your target include directory. To do
       that, enter
gmake install-all-headers
       This adds a megabyte or two to the installation footprint, and is
       only useful if you don't plan to keep the whole source tree around
       for reference. (If you do, you can just use the source's include
       directory when building server-side software.)
       Client-only installation: If you want to install only the client
       applications and interface libraries, then you can use these
       commands:
gmake -C src/bin install
gmake -C src/include install
gmake -C src/interfaces install
gmake -C doc install
       
   Uninstallation: To undo the installation use the command "gmake
   uninstall". However, this will not remove any created directories.
   
   Cleaning: After the installation you can make room by removing the
   built files from the source tree with the command "gmake clean". This
   will preserve the files made by the "configure" program, so that you
   can rebuild everything with "gmake" later on. To reset the source tree
   to the state in which it was distributed, use "gmake distclean". If
   you are going to build for several platforms from the same source tree
   you must do this and re-configure for each build.
   
   If you perform a build and then discover that your "configure" options
   were wrong, or if you change anything that "configure" investigates
   (for example, software upgrades), then it's a good idea to do "gmake
   distclean" before reconfiguring and rebuilding. Without this, your
   changes in configuration choices may not propagate everywhere they
   need to.
     _________________________________________________________________
   
                          Post-Installation Setup
                                      
                                   Tuning
                                      
   By default, PostgreSQL is configured to run on minimal hardware. This
   allows it to start up with almost any hardware configuration. However,
   the default configuration is not designed for optimum performance. To
   achieve optimum performance, several server variables must be
   adjusted, the two most common being shared_buffers and sort_mem
   mentioned in the documentation . Other parameters in the documentation
   also affect performance.
     _________________________________________________________________
   
                              Shared Libraries
                                      
   On some systems that have shared libraries (which most systems do) you
   need to tell your system how to find the newly installed shared
   libraries. The systems on which this is *not* necessary include
   BSD/OS, FreeBSD, HP-UX, IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX
   (formerly Digital UNIX), and Solaris.
   
   The method to set the shared library search path varies between
   platforms, but the most widely usable method is to set the environment
   variable LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh",
   "bash", "zsh")
LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH

   or in "csh" or "tcsh"
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

   Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in
   step 1. You should put these commands into a shell start-up file such
   as "/etc/profile" or "~/.bash_profile". Some good information about
   the caveats associated with this method can be found at
   http://www.visi.com/~barr/ldpath.html.
   
   On some systems it might be preferable to set the environment variable
   LD_RUN_PATH *before* building.
   
   On Cygwin, put the library directory in the PATH or move the ".dll"
   files into the "bin" directory.
   
   If in doubt, refer to the manual pages of your system (perhaps "ld.so"
   or "rld"). 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 this step was necessary. Simply take care of it then.
   
   If you are on BSD/OS, Linux, or SunOS 4 and you have root access you
   can run
/sbin/ldconfig /usr/local/pgsql/lib

   (or equivalent directory) after installation to enable the run-time
   linker to find the shared libraries faster. Refer to the manual page
   of "ldconfig" for more information. On FreeBSD, NetBSD, and OpenBSD
   the command is
/sbin/ldconfig -m /usr/local/pgsql/lib

   instead. Other systems are not known to have an equivalent command.
     _________________________________________________________________
   
                           Environment Variables
                                      
   If you installed into "/usr/local/pgsql" or some other location that
   is not searched for programs by default, you should add
   "/usr/local/pgsql/bin" (or whatever you set "--bindir" to in step 1)
   into your PATH. Strictly speaking, this is not necessary, but it will
   make the use of PostgreSQL much more convenient.
   
   To do this, add the following to your shell start-up file, such as
   "~/.bash_profile" (or "/etc/profile", if you want it to affect every
   user):
PATH=/usr/local/pgsql/bin:$PATH
export PATH

   If you are using "csh" or "tcsh", then use this command:
set path = ( /usr/local/pgsql/bin $path )

   To enable your system to find the man documentation, you need to add
   lines like the following to a shell start-up file unless you installed
   into a location that is searched by default.
MANPATH=/usr/local/pgsql/man:$MANPATH
export MANPATH

   The environment variables PGHOST and PGPORT specify to client
   applications the host and port of the database server, overriding the
   compiled-in defaults. If you are going to run client applications
   remotely then it is convenient if every user that plans to use the
   database sets PGHOST. This is not required, however: the settings can
   be communicated via command line options to most client programs.
     _________________________________________________________________
   
                              Getting Started
                                      
   The following is a quick summary of how to get PostgreSQL up and
   running once installed. The main documentation contains more
   information.
    1. Create a user account for the PostgreSQL server. 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, but running the server as root is a
       security risk and will not work.
adduser postgres
    2. Create a database installation with the "initdb" command. To run
       "initdb" you must be logged in to your PostgreSQL server account.
       It will not work as root.
root# mkdir /usr/local/pgsql/data
root# chown postgres /usr/local/pgsql/data
root# su - postgres
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 server
       account can write to the directory (or create it, if it doesn't
       already exist) before starting "initdb", as illustrated here.
    3. 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 put the server in
       the background use something like
nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
    </dev/null >>server.log 2>&1 </dev/null &
       To stop a server running in the background you can type
kill `cat /usr/local/pgsql/data/postmaster.pid`
       In order to allow TCP/IP connections (rather than only Unix domain
       socket ones) you need to pass the "-i" option to "postmaster".
    4. Create a database:
createdb testdb
       Then enter
psql testdb
       to connect to that database. At the prompt you can enter SQL
       commands and start experimenting.
     _________________________________________________________________
   
                                 What Now?
                                      
     * The PostgreSQL distribution contains a comprehensive documentation
       set, which you should read sometime. After installation, the
       documentation can be accessed by pointing your browser to
       "/usr/local/pgsql/doc/html/index.html", unless you changed the
       installation directories.
       The first few chapters of the main documentation are the Tutorial,
       which should be your first reading if you are completely new to
       SQL databases. If you are familiar with database concepts then you
       want to proceed with part on server administration, which contains
       information about how to set up the database server, database
       users, and authentication.
     * Usually, you will want to modify your computer so that it will
       automatically start the database server whenever it boots. Some
       suggestions for this are in the documentation.
     * 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. This is also
       explained in the documentation.
     _________________________________________________________________
   
                            Supported Platforms
                                      
   PostgreSQL has been verified by the developer community to work on the
   platforms listed below. A supported platform generally means that
   PostgreSQL builds and installs according to these instructions and
   that the regression tests pass.
   
     Note: If you are having problems with the installation on a
     supported platform, please write to <pgsql-bugs@@postgresql.org> or
     <pgsql-ports@@postgresql.org>, not to the people listed here.
     
   OS Processor Version Reported Remarks
   AIX RS6000 7.3 2002-11-12, Andreas Zeugswetter
   (<ZeugswetterA@@spardat.at>) see also doc/FAQ_AIX
   BSD/OS x86 7.3 2002-10-25, Bruce Momjian (<pgman@@candle.pha.pa.us>)
   4.2
   FreeBSD Alpha 7.3 2002-11-13, Chris Kings-Lynne
   (<chriskl@@familyhealth.com.au>)
   FreeBSD x86 7.3 2002-10-29, 3.3, Nigel J. Andrews
   (<nandrews@@investsystems.co.uk>), 4.7, Larry Rosenman
   (<ler@@lerctr.org>), 5.0, Sean Chittenden (<sean@@chittenden.org>)
   HP-UX PA-RISC 7.3 2002-10-28, 10.20 Tom Lane (<tgl@@sss.pgh.pa.us>),
   11.00, 11.11, 32 and 64 bit, Giles Lean (<giles@@nemeton.com.au>) gcc
   and cc; see also doc/FAQ_HPUX
   IRIX MIPS 7.3 2002-10-27, Ian Barwick (<barwick@@gmx.net>) Irix64 Komma
   6.5
   Linux Alpha 7.3 2002-10-28, Magnus Naeslund (<mag@@fbab.net>)
   2.4.19-pre6
   Linux armv4l 7.2 2001-12-10, Mark Knox (<segfault@@hardline.org>) 2.2.x
   Linux MIPS 7.2 2001-11-15, Hisao Shibuya (<shibuya@@alpha.or.jp>)
   2.0.x; Cobalt Qube2
   Linux PlayStation 2 7.3 2002-11-19, Permaine Cheung
   <pcheung@@redhat.com>) #undef HAS_TEST_AND_SET, remove slock_t typedef
   Linux PPC74xx 7.3 2002-10-26, Tom Lane (<tgl@@sss.pgh.pa.us>) bye
   2.2.18; Apple G3
   Linux S/390 7.3 2002-11-22, Permaine Cheung <pcheung@@redhat.com>) both
   s390 and s390x (32 and 64 bit)
   Linux Sparc 7.3 2002-10-26, Doug McNaught (<doug@@mcnaught.org>) 3.0
   Linux x86 7.3 2002-10-26, Alvaro Herrera (<alvherre@@dcc.uchile.cl>)
   2.4
   MacOS X PPC 7.3 2002-10-28, 10.1, Tom Lane (<tgl@@sss.pgh.pa.us>),
   10.2.1, Adam Witney (<awitney@@sghms.ac.uk>)
   NetBSD Alpha 7.2 2001-11-20, Thomas Thai (<tom@@minnesota.com>) 1.5W
   NetBSD arm32 7.3 2002-11-19, Patrick Welche (<prlw1@@newn.cam.ac.uk>)
   1.6
   NetBSD m68k 7.0 2000-04-10, Henry B. Hotz (<hotz@@jpl.nasa.gov>) Mac
   8xx
   NetBSD MIPS 7.2.1 2002-06-13, Warwick Hunter (<whunter@@agile.tv>)
   1.5.3
   NetBSD PPC 7.2 2001-11-28, Bill Studenmund (<wrstuden@@netbsd.org>) 1.5
   NetBSD Sparc 7.2 2001-12-03, Matthew Green (<mrg@@eterna.com.au>) 32-
   and 64-bit builds
   NetBSD VAX 7.1 2001-03-30, Tom I. Helbekkmo (<tih@@kpnQwest.no>) 1.5
   NetBSD x86 7.3 2002-11-14, Patrick Welche (<prlw1@@newn.cam.ac.uk>) 1.6
   OpenBSD Sparc 7.3 2002-11-17, Christopher Kings-Lynne
   (<chriskl@@familyhealth.com.au>) 3.2
   OpenBSD x86 7.3 2002-11-14, 3.1 Magnus Naeslund (<mag@@fbab.net>), 3.2
   Christopher Kings-Lynne (<chriskl@@familyhealth.com.au>)
   SCO OpenServer 5 x86 7.3.1 2002-12-11, Shibashish Satpathy
   (<shib@@postmark.net>) 5.0.4, gcc; see also doc/FAQ_SCO
   Solaris Sparc 7.3 2002-10-28, Andrew Sullivan
   (<andrew@@libertyrms.info>) Solaris 7 and 8; see also doc/FAQ_Solaris
   Solaris x86 7.3 2002-11-20, Martin Renters (<martin@@datafax.com>) 5.8;
   see also doc/FAQ_Solaris
   SunOS 4 Sparc 7.2 2001-12-04, Tatsuo Ishii (<t-ishii@@sra.co.jp>)
   Tru64 UNIX Alpha 7.3 2002-11-05, Alessio Bragadini
   (<alessio@@albourne.com>)
   UnixWare x86 7.3 2002-11-01, 7.1.3 Larry Rosenman (<ler@@lerctr.org>),
   7.1.1 and 7.1.2(8.0.0) Olivier Prenant (<ohp@@pyrenet.fr>) see also
   doc/FAQ_SCO
   Windows x86 7.3 2002-10-29, Dave Page (<dpage@@vale-housing.co.uk>),
   Jason Tishler (<jason@@tishler.net>) with Cygwin; see doc/FAQ_MSWIN
   Windows x86 7.3 2002-11-05, Dave Page (<dpage@@vale-housing.co.uk>)
   native is client-side only; see documentation
   
   Unsupported Platforms: The following platforms are either known not to
   work, or they used to work in a previous release and we did not
   receive explicit confirmation of a successful test with version 7.4 at
   the time this list was compiled. We include these here to let you know
   that these platforms *could* be supported if given some attention.
   
   OS Processor Version Reported Remarks
   BeOS x86 7.2 2001-11-29, Cyril Velter (<cyril.velter@@libertysurf.fr>)
   needs updates to semaphore code
   DG/UX 5.4R4.11 m88k 6.3 1998-03-01, Brian E Gallew (<geek+@@cmu.edu>)
   no recent reports
   MkLinux DR1 PPC750 7.0 2001-04-03, Tatsuo Ishii (<t-ishii@@sra.co.jp>)
   7.1 needs OS update?
   NeXTSTEP x86 6.x 1998-03-01, David Wetzel (<dave@@turbocat.de>) bit rot
   suspected
   QNX 4 RTOS x86 7.2 2001-12-10, Bernd Tegge (<tegge@@repas-aeg.de>)
   needs updates to semaphore code; see also doc/FAQ_QNX4
   QNX RTOS v6 x86 7.2 2001-11-20, Igor Kovalenko
   (<Igor.Kovalenko@@motorola.com>) patches available in archives, but too
   late for 7.2
   System V R4 m88k 6.2.1 1998-03-01, Doug Winterburn
   (<dlw@@seavme.xroads.com>) needs new TAS spinlock code
   System V R4 MIPS 6.4 1998-10-28, Frank Ridderbusch
   (<ridderbusch.pad@@sni.de>) no recent reports
   Ultrix MIPS 7.1 2001-03-26 TAS spinlock code not detected
   Ultrix VAX 6.x 1998-03-01
@


1.92.2.1
log
@Regenerate text files.
@
text
@a0 252
                      PostgreSQL Installation Instructions

This document describes the installation of PostgreSQL from the source code
distribution.

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

Short Version

  ./configure
  gmake
  su
  gmake install
  adduser postgres
  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data
  su - postgres
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
  /usr/local/pgsql/bin/createdb test
  /usr/local/pgsql/bin/psql test

The long version is the rest of this document.

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

Requirements

In general, a modern Unix-compatible platform should be able to run PostgreSQL.
The platforms that had received specific testing at the time of release are
listed in the Section called Supported Platforms below. In the "doc"
subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble. The following
software packages are required for building PostgreSQL:

    * GNU make is required; other make programs will *not* work. GNU make is
      often installed under the name "gmake"; this document will always refer
      to it by that name. (On some systems GNU make is the default tool with
      the name "make".) To test for GNU make enter

        gmake --version

      It is recommended to use version 3.76.1 or later.

    * You need an ISO/ANSI C compiler. Recent versions of GCC are
      recommendable, but PostgreSQL is known to build with a wide variety of
      compilers from different vendors.

    * gzip is needed to unpack the distribution in the first place. If you are
      reading this, you probably already got past that hurdle.

    * The GNU Readline library (for comfortable line editing and command
      history retrieval) will be used by default. If you don't want to use it
      then you must specify the "--without-readline" option for "configure".
      (On NetBSD, the "libedit" library is Readline-compatible and is used if
      "libreadline" is not found.)

    * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
      packages. See the file "doc/FAQ_MSWIN" for details.

The following packages are optional. They are not required in the default
configuration, but they are needed when certain build options are enabled, as
explained below.

    * To build the server programming language PL/Perl you need a full Perl
      installation, including the "libperl" library and the header files. Since
      PL/Perl will be a shared library, the "libperl" library must be a shared
      library also on most platforms. This appears to be the default in recent
      Perl versions, but it was not in earlier versions, and in general it is
      the choice of whomever installed Perl at your site.
      If you don't have the shared library but you need one, a message like
      this will appear during the build to point out this fact:

        *** Cannot build PL/Perl because libperl is not a shared library.
        *** You might have to rebuild your Perl installation.  Refer to
        *** the documentation for details.

      (If you don't follow the on-screen output you will merely notice that the
      PL/Perl library object, "plperl.so" or similar, will not be installed.)
      If you see this, you will have to rebuild and install Perl manually to be
      able to build PL/Perl. During the configuration process for Perl, request
      a shared library.

    * To build the PL/Python server programming language, you need a Python
      installation, including the header files. Since PL/Python will be a
      shared library, the "libpython" library must be a shared library also on
      most platforms. This is not the case in a default Python installation.
      If after building and installing you have a file called "plpython.so"
      (possibly a different extension), then everything went well. Otherwise
      you should have seen a notice like this flying by:

        *** Cannot build PL/Python because libpython is not a shared library.
        *** You might have to rebuild your Python installation.  Refer to
        *** the documentation for details.

      That means you have to rebuild (part of) your Python installation to
      supply this shared library.
      The catch is that the Python distribution or the Python maintainers do
      not provide any direct way to do this. The closest thing we can offer you
      is the information in Python FAQ 3.30. On some operating systems you
      don't really have to build a shared library, but then you will have to
      convince the PostgreSQL build system of this. Consult the "Makefile" in
      the "src/pl/plpython" directory for details.

    * If you want to build Tcl or Tk components (clients and the PL/Tcl
      language) you of course need a Tcl installation.

    * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
      special tool for building Java-based packages. It can be downloaded from
      the Ant web site.
      If you have several Java compilers installed, it depends on the Ant
      configuration which one gets used. Precompiled Ant distributions are
      typically set up to read a file ".antrc" in the current user's home
      directory for configuration. For example, to use a different JDK than the
      default, this may work:

        JAVA_HOME=/usr/local/sun-jdk1.3
        JAVACMD=$JAVA_HOME/bin/java

           Note: Do not try to build the driver by calling "ant" or even
           "javac" directly. This will not work. Run "gmake" normally as
           described below.

    * To enable Native Language Support (NLS), that is, the ability to display
      a program's messages in a language other than English, you need an
      implementation of the Gettext API. Some operating systems have this
      built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
      download an add-on package from here: http://www.postgresql.org/~petere/
      gettext.html. If you are using the Gettext implementation in the GNU C
      library then you will additionally need the GNU Gettext package for some
      utility programs. For any of the other implementations you will not need
      it.

    * Kerberos, OpenSSL, or PAM, if you want to support authentication using
      these services.

If you are building from a CVS tree instead of using a released source package,
or if you want to do development, you also need the following packages:

    * Flex and Bison are needed to build a CVS checkout or if you changed the
      actual scanner and parser definition files. If you need them, be sure to
      get Flex 2.5.4 or later and Bison 1.875 or later. Other yacc programs can
      sometimes be used, but doing so requires extra effort and is not
      recommended. Other lex programs will definitely not work.

If you need to get a GNU package, you can find it at your local GNU mirror site
(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for
the source tree during compilation and about 15 MB for the installation
directory. An empty database cluster takes about 25 MB, databases take about
five times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need up
to an extra 90 MB. Use the "df" command to check for disk space.

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

If You Are Upgrading

The internal data storage format changes with new releases of PostgreSQL.
Therefore, if you are upgrading an existing installation that does not have a
version number "7.4.x", you must back up and restore your data as shown here.
These instructions assume that your existing installation is under the "/usr/
local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
Substitute your paths appropriately.

   1. Make sure that your database is not updated during or after the backup.
      This does not affect the integrity of the backup, but the changed data
      would of course not be included. If necessary, edit the permissions in
      the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
      access from everyone except you.

   2. To back up your database installation, type:

        pg_dumpall > outputfile

      If you need to preserve OIDs (such as when using them as foreign keys),
      then use the "-o" option when running "pg_dumpall".
      "pg_dumpall" does not save large objects. Check the documentation if you
      need to do this.
      To make the backup, you can use the "pg_dumpall" command from the version
      you are currently running. For best results, however, try to use the
      "pg_dumpall" command from PostgreSQL 7.4, since this version contains
      bug fixes and improvements over older versions. While this advice might
      seem idiosyncratic since you haven't installed the new version yet, it is
      advisable to follow it if you plan to install the new version in parallel
      with the old version. In that case you can complete the installation
      normally and transfer the data later. This will also decrease the
      downtime.

   3. If you are installing the new version at the same location as the old one
      then shut down the old server, at the latest before you install the new
      files:

        kill -INT `cat /usr/local/pgsql/data/postmaster.pid`

      Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
      using such a version you must find out the process ID of the server
      yourself, for example by typing "ps ax | grep postmaster", and supply it
      to the "kill" command.
      On systems that have PostgreSQL started at boot time, there is probably a
      start-up file that will accomplish the same thing. For example, on a Red
      Hat Linux system one might find that

        /etc/rc.d/init.d/postgresql stop

      works. Another possibility is "pg_ctl stop".

   4. If you are installing in the same place as the old version then it is
      also a good idea to move the old installation out of the way, in case you
      have trouble and need to revert to it. Use a command like this:

        mv /usr/local/pgsql /usr/local/pgsql.old

After you have installed PostgreSQL 7.4, create a new database directory and
start the new server. Remember that you must execute these commands while
logged in to the special database user account (which you already have if you
are upgrading).

  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

Finally, restore your data with

  /usr/local/pgsql/bin/psql -d template1 -f outputfile

using the *new* psql.
These topics are discussed at length in the documentation, which you are
encouraged to read in any case.

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

Installation Procedure

   1. Configuration
      The first step of the installation procedure is to configure the source
      tree for your system and choose the options you would like. This is done
      by running the "configure" script. For a default installation simply
      enter

        ./configure

      This script will run a number of tests to guess values for various system
      dependent variables and detect some quirks of your operating system, and
      finally will create several files in the build tree to record what it
      found. (You can also run "configure" in a directory outside the source
      tree if you want to keep the build directory separate.)
      The default configuration will build the server and utilities, as well as
      all client applications and interfaces that require only a C compiler.
      All files will be installed under "/usr/local/pgsql" by default.
      You can customize the build and installation process by supplying one or
      more of the following command line options to "configure":
d2 234
d237 8
a244 8

            Install all files under the directory "PREFIX" instead of "/usr/
            local/pgsql". The actual files will be installed into various
            subdirectories; no files will ever be installed directly into the
            "PREFIX" directory.
            If you have special needs, you can also customize the individual
            subdirectories with the following options.

d246 9
a254 8

            You can install architecture-dependent files under a different
            prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
            useful to share architecture-independent files between hosts. If
            you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
            architecture-dependent and independent files will be installed
            under the same tree, which is probably what you want.

d256 4
a259 4

            Specifies the directory for executable programs. The default is
            "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

d261 5
a265 5

            Sets the directory for read-only data files used by the installed
            programs. The default is "PREFIX/share". Note that this has nothing
            to do with where your database files will be placed.

d267 3
a269 4

            The directory for various configuration files, "PREFIX/etc" by
            default.

d271 3
a273 4

            The location to install libraries and dynamically loadable modules.
            The default is "EXEC-PREFIX/lib".

d275 3
a277 4

            The directory for installing C and C++ header files. The default is
            "PREFIX/include".

d279 4
a282 4

            Documentation files, except "man" pages, will be installed into
            this directory. The default is "PREFIX/doc".

d284 21
a304 23

            The man pages that come with PostgreSQL will be installed under
            this directory, in their respective "manx" subdirectories. The
            default is "PREFIX/man".

           Note: Care has been taken to make it possible to install
           PostgreSQL into shared installation locations (such as "/usr/
           local/include") without interfering with the namespace of the
           rest of the system. First, the string "/postgresql" is
           automatically appended to datadir, sysconfdir, and docdir,
           unless the fully expanded directory name already contains the
           string "postgres" or "pgsql". For example, if you choose "/usr/
           local" as prefix, the documentation will be installed in "/usr/
           local/doc/postgresql", but if the prefix is "/opt/postgres",
           then it will be in "/opt/postgres/doc". The public C header
           files of the client interfaces are installed into includedir
           and are namespace-clean. The internal header files and the
           server header files are installed into private directories
           under includedir. See the documentation of each interface for
           information about how to get at the its header files. Finally,
           a private subdirectory will also be created, if appropriate,
           under libdir for dynamically loadable modules.

d306 10
a315 8

            "DIRECTORIES" is a colon-separated list of directories that will be
            added to the list the compiler searches for header files. If you
            have optional packages (such as GNU Readline) installed in a non-
            standard location, you have to use this option and probably also
            the corresponding "--with-libraries" option.
            Example: --with-includes=/opt/gnu/include:/usr/sup/include.

d317 7
a323 7

            "DIRECTORIES" is a colon-separated list of directories to search
            for libraries. You will probably have to use this option (and the
            corresponding "--with-includes" option) if you have packages
            installed in non-standard locations.
            Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

d325 12
a336 11

            Enables Native Language Support (NLS), that is, the ability to
            display a program's messages in a language other than English.
            "LANGUAGES" is a space separated list of codes of the languages
            that you want supported, for example --enable-nls='de fr'. (The
            intersection between your list and the set of actually provided
            translations will be computed automatically.) If you do not specify
            a list, then all available translations are installed.
            To use this option, you will need an implementation of the Gettext
            API; see above.

d338 8
a345 8

            Set "NUMBER" as the default port number for server and clients. The
            default is 5432. The port can always be changed later on, but if
            you specify it here then both server and clients will have the same
            default compiled in, which can be very convenient. Usually the only
            good reason to select a non-default value is if you intend to run
            multiple PostgreSQL servers on the same machine.

d347 2
a348 3

            Build the PL/Perl server-side language.

d350 2
a351 3

            Build the PL/Python server-side language.

d353 4
a356 4

            Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
            pgtksh, and PL/Tcl. But see below about "--without-tk".

d358 3
a360 4

            If you specify "--with-tcl" and this option, then the program that
            requires Tk (pgtksh) will be excluded.

d362 8
a369 8

            Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
            contain configuration information needed to build modules
            interfacing to Tcl or Tk. These files are normally found
            automatically at their well-known locations, but if you want to use
            a different version of Tcl or Tk you can specify the directory in
            which to find them.

d371 2
a372 3

            Build the JDBC driver and associated Java packages.

d374 16
a389 14

            Build with support for Kerberos authentication. You can use either
            Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
            specifies the root directory of the Kerberos installation; "/usr/
            athena" is assumed as default. If the relevant header files and
            libraries are not under a common parent directory, then you must
            use the "--with-includes" and "--with-libraries" options in
            addition to this option. If, on the other hand, the required files
            are in a location that is searched by default (e.g., "/usr/lib"),
            then you can leave off the argument.
            "configure" will check for the required header files and libraries
            to make sure that your Kerberos installation is sufficient before
            proceeding.

d391 3
a393 4

            The name of the Kerberos service principal. postgres is the
            default. There's probably no reason to change this.

d395 9
a403 9

            Build with support for SSL (encrypted) connections. This requires
            the OpenSSL package to be installed. The "DIRECTORY" argument
            specifies the root directory of the OpenSSL installation; the
            default is "/usr/local/ssl".
            "configure" will check for the required header files and libraries
            to make sure that your OpenSSL installation is sufficient before
            proceeding.

d405 3
a407 3

            Build with PAM (Pluggable Authentication Modules) support.

d409 4
a412 4

            Prevents the use of the Readline library. This disables command-
            line editing and history in psql, so it is not recommended.

d414 2
a415 3

            Build with Rendezvous support.

d417 5
a421 7

            Allow the builds to succeed even if PostgreSQL has no CPU spinlock
            support for the platform. The lack of spinlock support will result
            in poor performance; therefore, this option should only be used if
            the build aborts and informs you that the platform lacks spinlock
            support.

d423 3
a425 5

            Make the client libraries thread-safe. This allows concurrent
            threads in libpq and ECPG programs to safely control their private
            connection handles.

d427 5
a431 5

            Prevents the use of the Zlib library. This disables compression
            support in pg_dump. This option is only intended for those rare
            systems where this library is not available.

d433 12
a444 12

            Compiles all programs and libraries with debugging symbols. This
            means that you can run the programs through a debugger to analyze
            problems. This enlarges the size of the installed executables
            considerably, and on non-GCC compilers it usually also disables
            compiler optimization, causing slowdowns. However, having the
            symbols available is extremely helpful for dealing with any
            problems that may arise. Currently, this option is recommended for
            production installations only if you use GCC. But you should always
            have it on if you are doing development work or running a beta
            version.

d446 12
a457 11

            Enables assertion checks in the server, which test for many "can't
            happen" conditions. This is invaluable for code development
            purposes, but the tests slow things down a little. Also, having the
            tests turned on won't necessarily enhance the stability of your
            server! The assertion checks are not categorized for severity, and
            so what might be a relatively harmless bug will still lead to
            server restarts if it triggers an assertion failure. Currently,
            this option is not recommended for production use, but you should
            have it on for development work or when running a beta version.

d459 355
a813 393

            Enables automatic dependency tracking. With this option, the
            makefiles are set up so that all affected object files will be
            rebuilt when any header file is changed. This is useful if you are
            doing development work, but is just wasted overhead if you intend
            only to compile once and install. At present, this option will work
            only if you use GCC.

      If you prefer a C compiler different from the one "configure" picks then
      you can set the environment variable CC to the program of your choice. By
      default, "configure" will pick "gcc" unless this is inappropriate for the
      platform. Similarly, you can override the default compiler flags with the
      CFLAGS variable.

      You can specify environment variables on the "configure" command line,
      for example:

        ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'

   2. Build
      To start the build, type

        gmake

      (Remember to use GNU make.) The build may take anywhere from 5 minutes to
      half an hour depending on your hardware. The last line displayed should
      be

        All of PostgreSQL is successfully made. Ready to install.

   3. Regression Tests
      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. Type

        gmake check

      (This won't work as root; do it as an unprivileged user.) The file "src/
      test/regress/README" and the documentation contain detailed information
      about interpreting the test results. You can repeat this test at any
      later time by issuing the same command.

   4. Installing The Files
           Note: If you are upgrading an existing system and are going to
           install the new files over the old ones, then you should have
           backed up your data and shut down the old server by now, as
           explained in
           the Section called If You Are Upgrading
            above.
      To install PostgreSQL enter

        gmake install

      This will install files into the directories that were specified in step
      1. Make sure that you have appropriate permissions to write into that
      area. Normally you need to do this step as root. Alternatively, you could
      create the target directories in advance and arrange for appropriate
      permissions to be granted.
      You can use gmake install-strip instead of gmake install to strip the
      executable files and libraries as they are installed. This will save some
      space. If you built with debugging support, stripping will effectively
      remove the debugging support, so it should only be done if debugging is
      no longer needed. install-strip tries to do a reasonable job saving
      space, but it does not have perfect knowledge of how to strip every
      unneeded byte from an executable file, so if you want to save all the
      disk space you possibly can, you will have to do manual work.
      The standard installation provides only the header files needed for
      client application development. If you plan to do any server-side program
      development (such as custom functions or data types written in C), then
      you may want to install the entire PostgreSQL include tree into your
      target include directory. To do that, enter

        gmake install-all-headers

      This adds a megabyte or two to the installation footprint, and is only
      useful if you don't plan to keep the whole source tree around for
      reference. (If you do, you can just use the source's include directory
      when building server-side software.)
      Client-only installation: If you want to install only the client
      applications and interface libraries, then you can use these commands:

        gmake -C src/bin install
        gmake -C src/include install
        gmake -C src/interfaces install
        gmake -C doc install

Uninstallation: To undo the installation use the command "gmake uninstall".
However, this will not remove any created directories.
Cleaning: After the installation you can make room by removing the built files
from the source tree with the command "gmake clean". This will preserve the
files made by the "configure" program, so that you can rebuild everything with
"gmake" later on. To reset the source tree to the state in which it was
distributed, use "gmake distclean". If you are going to build for several
platforms from the same source tree you must do this and re-configure for each
build.
If you perform a build and then discover that your "configure" options were
wrong, or if you change anything that "configure" investigates (for example,
software upgrades), then it's a good idea to do "gmake distclean" before
reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.

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

Post-Installation Setup

Shared Libraries

On some systems that have shared libraries (which most systems do) you need to
tell your system how to find the newly installed shared libraries. The systems
on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
The method to set the shared library search path varies between platforms, but
the most widely usable method is to set the environment variable
LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh")

  LD_LIBRARY_PATH=/usr/local/pgsql/lib
  export LD_LIBRARY_PATH

or in "csh" or "tcsh"

  setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
should put these commands into a shell start-up file such as "/etc/profile" or
"~/.bash_profile". Some good information about the caveats associated with this
method can be found at http://www.visi.com/~barr/ldpath.html.
On some systems it might be preferable to set the environment variable
LD_RUN_PATH *before* building.
On Cygwin, put the library directory in the PATH or move the ".dll" files into
the "bin" directory.
If in doubt, refer to the manual pages of your system (perhaps "ld.so" or
"rld"). 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 this step was necessary. Simply take care of it then.
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run

  /sbin/ldconfig /usr/local/pgsql/lib

(or equivalent directory) after installation to enable the run-time linker to
find the shared libraries faster. Refer to the manual page of "ldconfig" for
more information. On FreeBSD, NetBSD, and OpenBSD the command is

  /sbin/ldconfig -m /usr/local/pgsql/lib

instead. Other systems are not known to have an equivalent command.

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

Environment Variables

If you installed into "/usr/local/pgsql" or some other location that is not
searched for programs by default, you should add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as
"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):

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

If you are using "csh" or "tcsh", then use this command:

  set path = ( /usr/local/pgsql/bin $path )

To enable your system to find the man documentation, you need to add lines like
the following to a shell start-up file unless you installed into a location
that is searched by default.

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

The environment variables PGHOST and PGPORT specify to client applications the
host and port of the database server, overriding the compiled-in defaults. If
you are going to run client applications remotely then it is convenient if
every user that plans to use the database sets PGHOST. This is not required,
however: the settings can be communicated via command line options to most
client programs.

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

Getting Started

The following is a quick summary of how to get PostgreSQL up and running once
installed. The main documentation contains more information.

   1. Create a user account for the PostgreSQL server. 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,
      but running the server as root is a security risk and will not work.

        adduser postgres

   2. Create a database installation with the "initdb" command. To run "initdb"
      you must be logged in to your PostgreSQL server account. It will not work
      as root.

        root# mkdir /usr/local/pgsql/data
        root# chown postgres /usr/local/pgsql/data
        root# su - postgres
        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 server account can write to the
      directory (or create it, if it doesn't already exist) before starting
      "initdb", as illustrated here.

   3. 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 put the server in the
      background use something like

        nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
            </dev/null >>server.log 2>&1 </dev/null &

      To stop a server running in the background you can type

        kill `cat /usr/local/pgsql/data/postmaster.pid`

      In order to allow TCP/IP connections (rather than only Unix domain socket
      ones) you need to pass the "-i" option to "postmaster".

   4. Create a database:

        createdb testdb

      Then enter

        psql testdb

      to connect to that database. At the prompt you can enter SQL commands and
      start experimenting.

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

What Now?

    * The PostgreSQL distribution contains a comprehensive documentation set,
      which you should read sometime. After installation, the documentation can
      be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
      index.html", unless you changed the installation directories.
      The first few chapters of the main documentation are the Tutorial, which
      should be your first reading if you are completely new to SQL databases.
      If you are familiar with database concepts then you want to proceed with
      part on server administration, which contains information about how to
      set up the database server, database users, and authentication.

    * Usually, you will want to modify your computer so that it will
      automatically start the database server whenever it boots. Some
      suggestions for this are in the documentation.

    * Run the regression tests against the installed server (using "gmake
      installcheck"). If you didn't run the tests before installation, you
      should definitely do it now. This is also explained in the documentation.

    * By default, PostgreSQL is configured to run on minimal hardware. This
      allows it to start up with almost any hardware configuration. The default
      configuration is, however, not designed for optimum performance. To
      achieve optimum performance, several server parameters must be adjusted,
      the two most common being shared_buffers and sort_mem mentioned in the
      documentation. Other parameters mentioned in the documentation also
      affect performance.

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

Supported Platforms

PostgreSQL has been verified by the developer community to work on the
platforms listed below. A supported platform generally means that PostgreSQL
builds and installs according to these instructions and that the regression
tests pass.
     Note: If you are having problems with the installation on a supported
     platform, please write to <pgsql-bugs@@postgresql.org> or <pgsql-
     ports@@postgresql.org>, not to the people listed here.
 _____________________________________________________________________________
|OS__________|Processor|Version|Reported______________________|Remarks________|
|AIX         |RS6000   |7.4    |2003-10-25, Hans-Jrgen       |see also doc/  |
|____________|_________|_______|Schnig_(<hs@@cybertec.at>)____|FAQ_AIX________|
|BSD/OS      |x86      |7.4    |2003-10-24, Bruce Momjian     |4.3            |
|____________|_________|_______|(<pgman@@candle.pha.pa.us>)____|_______________|
|FreeBSD     |Alpha    |7.4    |2003-10-25, Peter Eisentraut  |4.8            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|FreeBSD     |x86      |7.4    |2003-10-24, Peter Eisentraut  |4.9            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|HP-UX       |PA-RISC  |7.4    |2003-10-31, 10.20, Tom Lane   |gcc and cc; see|
|            |         |       |(<tgl@@sss.pgh.pa.us>); 2003-  |also doc/      |
|            |         |       |11-04, 11.00, Peter Eisentraut|FAQ_HPUX       |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|IRIX        |MIPS     |7.4    |2003-11-12, Robert E.         |6.5.20, cc only|
|            |         |       |Bruccoleri                    |               |
|____________|_________|_______|(<bruc@@stone.congenomics.com>)|_______________|
|Linux       |Alpha    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |arm41    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Itanium  |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |m68k     |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |MIPS     |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Opteron  |7.4    |2003-11-01, Jani Averbach     |2.6            |
|____________|_________|_______|(<jaa@@cc.jyu.fi>)_____________|_______________|
|Linux       |PPC      |7.4    |2003-10-25, Nol Kthe        |               |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |S/390    |7.4    |2003-10-25, Nol Kthe        |2.4            |
|____________|_________|_______|(<noel@@debian.org>)___________|_______________|
|Linux       |Sparc    |7.4    |2003-10-24, Peter Eisentraut  |2.4, 32-bit    |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|Linux       |x86      |7.4    |2003-10-24, Peter Eisentraut  |2.4            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|MacOS X     |PPC      |7.4    |2003-10-24, 10.2.8, Adam      |               |
|            |         |       |Witney                        |               |
|            |         |       |(<awitney@@sghms.ac.uk>), 10.3,|               |
|            |         |       |Marko Karppinen               |               |
|____________|_________|_______|(<marko@@karppinen.fi>)________|_______________|
|NetBSD      |arm32    |7.4    |2003-11-12, Patrick Welche    |1.6ZE/acorn32  |
|____________|_________|_______|(<prlw1@@newn.cam.ac.uk>)______|_______________|
|NetBSD      |x86      |7.4    |2003-10-24, Peter Eisentraut  |1.6            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|OpenBSD     |Sparc    |7.4    |2003-11-01, Peter Eisentraut  |3.4            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|OpenBSD     |x86      |7.4    |2003-10-24, Peter Eisentraut  |3.2            |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
|Solaris     |Sparc    |7.4    |2003-10-26, Christopher Browne|2.8; see also  |
|____________|_________|_______|(<cbbrowne@@libertyrms.info>)__|doc/FAQ_Solaris|
|Solaris     |x86      |7.4    |2003-10-26, Kurt Roeckx       |2.6 see also   |
|____________|_________|_______|(<Q@@ping.be>)_________________|doc/FAQ_Solaris|
|Tru64 UNIX  |Alpha    |7.4    |2003-10-25, 5.1b, Peter       |               |
|            |         |       |Eisentraut                    |               |
|            |         |       |(<peter_e@@gmx.net>); 2003-10- |               |
|            |         |       |29, 4.0g, Alessio Bragadini   |               |
|____________|_________|_______|(<alessio@@albourne.com>)______|_______________|
|UnixWare    |x86      |7.4    |2003-11-03, Larry Rosenman    |7.1.3; join    |
|            |         |       |(<ler@@lerctr.org>)            |test may fail, |
|            |         |       |                              |see also doc/  |
|____________|_________|_______|______________________________|FAQ_SCO________|
|Windows with|x86      |7.4    |2003-10-24, Peter Eisentraut  |see doc/       |
|Cygwin______|_________|_______|(<peter_e@@gmx.net>)___________|FAQ_MSWIN______|
|Windows     |x86      |7.4    |2003-10-27, Dave Page         |native is      |
|            |         |       |(<dpage@@vale-housing.co.uk>)  |client-side    |
|            |         |       |                              |only, see      |
|____________|_________|_______|______________________________|documentation__|

Unsupported Platforms: The following platforms are either known not to work, or
they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.4 at the time this list was
compiled. We include these here to let you know that these platforms *could* be
supported if given some attention.
 ________________________________________________________________________________
|OS________|Processor__|Version|Reported_______________________|Remarks__________|
|BeOS      |x86        |7.2    |2001-11-29, Cyril Velter       |needs updates to |
|__________|___________|_______|(<cyril.velter@@libertysurf.fr>)|semaphore_code___|
|Linux     |PlayStation|7.4    |2003-11-02, Peter Eisentraut   |needs new        |
|          |2          |       |(<peter_e@@gmx.net>)            |config.guess, -- |
|          |           |       |                               |disable-         |
|          |           |       |                               |spinlocks, #undef|
|          |           |       |                               |HAS_TEST_AND_SET,|
|          |           |       |                               |disable tas_dummy|
|__________|___________|_______|_______________________________|()_______________|
|Linux     |PA-RISC    |7.4    |2003-10-25, Nol Kthe         |needs --disable- |
|          |           |       |(<noel@@debian.org>)            |spinlocks,       |
|__________|___________|_______|_______________________________|otherwise_OK_____|
|NetBSD    |Alpha      |7.2    |2001-11-20, Thomas Thai        |1.5W             |
|__________|___________|_______|(<tom@@minnesota.com>)__________|_________________|
|NetBSD    |MIPS       |7.2.1  |2002-06-13, Warwick Hunter     |1.5.3            |
|__________|___________|_______|(<whunter@@agile.tv>)___________|_________________|
|NetBSD    |PPC        |7.2    |2001-11-28, Bill Studenmund    |1.5              |
|__________|___________|_______|(<wrstuden@@netbsd.org>)________|_________________|
|NetBSD    |Sparc      |7.2    |2001-12-03, Matthew Green      |32- and 64-bit   |
|__________|___________|_______|(<mrg@@eterna.com.au>)__________|builds___________|
|NetBSD    |VAX        |7.1    |2001-03-30, Tom I. Helbekkmo   |1.5              |
|__________|___________|_______|(<tih@@kpnQwest.no>)____________|_________________|
|QNX 4 RTOS|x86        |7.2    |2001-12-10, Bernd Tegge        |needs updates to |
|          |           |       |(<tegge@@repas-aeg.de>)         |semaphore code;  |
|          |           |       |                               |see also doc/    |
|__________|___________|_______|_______________________________|FAQ_QNX4_________|
|QNX RTOS  |x86        |7.2    |2001-11-20, Igor Kovalenko     |patches available|
|v6        |           |       |(<Igor.Kovalenko@@motorola.com>)|in archives, but |
|__________|___________|_______|_______________________________|too_late_for_7.2_|
|SCO       |x86        |7.3.1  |2002-12-11, Shibashish Satpathy|5.0.4, gcc; see  |
|OpenServer|___________|_______|(<shib@@postmark.net>)__________|also_doc/FAQ_SCO_|
|SunOS 4   |Sparc      |7.2    |2001-12-04, Tatsuo Ishii (<t-  |                 |
|__________|___________|_______|ishii@@sra.co.jp>)______________|_________________|
@


1.92.2.2
log
@Punctuation improvements
@
text
@d805 1
a805 1
|Mac OS X    |PPC      |7.4    |2003-10-24, 10.2.8, Adam      |               |
d820 1
a820 1
|Solaris     |x86      |7.4    |2003-10-26, Kurt Roeckx       |2.6; see also  |
@


1.92.2.3
log
@Fix instructions how to shut down postmaster.
@
text
@d195 1
a195 1
        kill -INT `cat /usr/local/pgsql/data/postmaster.pid | sed 1q`
@


1.92.2.4
log
@Update INSTALL for 7.4.1.
@
text
@d183 1
a183 1
      "pg_dumpall" command from PostgreSQL 7.4.1, since this version contains
d215 1
a215 1
After you have installed PostgreSQL 7.4.1, create a new database directory and
@


1.92.2.5
log
@Update INSTALL file for 7.4.1.
@
text
@a811 2
|NetBSD      |Sparc    |7.4.1  |2003-11-26, Peter Eisentraut  |1.6.1, 32-bit  |
|____________|_________|_______|(<peter_e@@gmx.net>)___________|_______________|
d863 2
@


1.92.2.6
log
@Correct gettext URL.
@
text
@d128 2
a129 2
      download an add-on package from here: http://developer.postgresql.org/~petere/
      bsd-gettext/. If you are using the Gettext implementation in the GNU C
@


1.92.2.7
log
@Brand 7.4.2.  Release notes still need work.
@
text
@d183 1
a183 1
      "pg_dumpall" command from PostgreSQL 7.4.2, since this version contains
d215 1
a215 1
After you have installed PostgreSQL 7.4.2, create a new database directory and
@


1.92.2.8
log
@Remove HISTORY and INSTALL.  Have them generated by the tarball scripts.

Add README.CVS to help CVS folks find this information.
@
text
@@


1.91
log
@Update INSTALL file for 7.4.
@
text
@d173 1
a173 1
       to use the "pg_dumpall" command from PostgreSQL 7.4beta4, since
d199 1
a199 1
   After you have installed PostgreSQL 7.4beta4, create a new database
@


1.90
log
@Remove --enable-recode feature, since it's been broken by IPv6 changes,
and seems to have too few users to justify maintaining.
@
text
@d2 234
a235 254
                     PostgreSQL Installation Instructions

This document describes the installation of PostgreSQL from the source code
distribution.

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

                                 Short Version

  ./configure
  gmake
  su
  gmake install
  adduser postgres
  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data
  su - postgres
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
  /usr/local/pgsql/bin/createdb test
  /usr/local/pgsql/bin/psql test

The long version is the rest of this document.

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

                                 Requirements

In general, a modern Unix-compatible platform should be able to run PostgreSQL.
The platforms that had received specific testing at the time of release are
listed in the Section called Supported Platforms below. In the "doc"
subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble.
The following software packages are required for building PostgreSQL:

    * GNU make is required; other make programs will *not* work. GNU make is
      often installed under the name "gmake"; this document will always refer
      to it by that name. (On some systems GNU make is the default tool with
      the name "make".) To test for GNU make enter

        gmake --version

      It is recommended to use version 3.76.1 or later.

    * You need an ISO/ANSI C compiler. Recent versions of GCC are
      recommendable, but PostgreSQL is known to build with a wide variety of
      compilers from different vendors.

    * gzip is needed to unpack the distribution in the first place. If you are
      reading this, you probably already got past that hurdle.

    * The GNU Readline library (for comfortable line editing and command
      history retrieval) will be used by default. If you don't want to use it
      then you must specify the "--without-readline" option for "configure".
      (On NetBSD, the "libedit" library is readline-compatible and is used if
      "libreadline" is not found.)

    * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
      packages. See the file "doc/FAQ_MSWIN" for details.

The following packages are optional. They are not required in the default
configuration, but they are needed when certain build options are enabled, as
explained below.

    * To build the server programming language PL/Perl you need a full Perl
      installation, including the "libperl" library and the header files. Since
      PL/Perl will be a shared library, the "libperl" library must be a shared
      library also on most platforms. This appears to be the default in recent
      Perl versions, but it was not in earlier versions, and in general it is
      the choice of whomever installed Perl at your site.
      If you don't have the shared library but you need one, a message like
      this will appear during the build to point out this fact:

        *** Cannot build PL/Perl because libperl is not a shared library.
        *** You might have to rebuild your Perl installation.  Refer to
        *** the documentation for details.

      (If you don't follow the on-screen output you will merely notice that the
      PL/Perl library object, "plperl.so" or similar, will not be installed.)
      If you see this, you will have to rebuild and install Perl manually to be
      able to build PL/Perl. During the configuration process for Perl, request
      a shared library.

    * To build the Python interface module or the PL/Python server programming
      language, you need a Python installation, including the header files.
      Since PL/Python will be a shared library, the "libpython" library must be
      a shared library also on most platforms. This is not the case in a
      default Python installation.
      If after building and installing you have a file called "plpython.so"
      (possibly a different extension), then everything went well. Otherwise
      you should have seen a notice like this flying by:

        *** Cannot build PL/Python because libpython is not a shared library.
        *** You might have to rebuild your Python installation.  Refer to
        *** the documentation for details.

      That means you have to rebuild (part of) your Python installation to
      supply this shared library.
      The catch is that the Python distribution or the Python maintainers do
      not provide any direct way to do this. The closest thing we can offer you
      is the information in Python FAQ 3.30. On some operating systems you
      don't really have to build a shared library, but then you will have to
      convince the PostgreSQL build system of this. Consult the "Makefile" in
      the "src/pl/plpython" directory for details.

    * If you want to build Tcl or Tk components (clients and the PL/Tcl
      language) you of course need a Tcl installation.

    * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
      special tool for building Java-based packages. It can be downloaded from
      the Ant web site.
      If you have several Java compilers installed, it depends on the Ant
      configuration which one gets used. Precompiled Ant distributions are
      typically set up to read a file ".antrc" in the current user's home
      directory for configuration. For example, to use a different JDK than the
      default, this may work:

        JAVA_HOME=/usr/local/sun-jdk1.3
        JAVACMD=$JAVA_HOME/bin/java

           Note: Do not try to build the driver by calling "ant" or even
           "javac" directly. This will not work. Run "gmake" normally as
           described below.

    * To enable Native Language Support (NLS), that is, the ability to display
      a program's messages in a language other than English, you need an
      implementation of the Gettext API. Some operating systems have this
      built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
      download an add-on package from here: http://www.postgresql.org/~petere/
      gettext.html. If you are using the gettext implementation in the GNU C
      library then you will additionally need the GNU Gettext package for some
      utility programs. For any of the other implementations you will not need
      it.

    * Kerberos, OpenSSL, or PAM, if you want to support authentication using
      these services.

If you are build from a CVS tree instead of using a released source package, or
if you want to do development, you also need the following packages:

    * Flex and Bison are needed to build a CVS checkout or if you changed the
      actual scanner and parser definition files. If you need them, be sure to
      get Flex 2.5.4 or later and Bison 1.50 or later. Other yacc programs can
      sometimes be used, but doing so requires extra effort and is not
      recommended. Other lex programs will definitely not work.

If you need to get a GNU package, you can find it at your local GNU mirror site
(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for
the source tree during compilation and about 15 MB for the installation
directory. An empty database cluster takes about 25 MB, databases take about
five times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need up
to an extra 90 MB. Use the "df" command to check for disk space.

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

                             If You Are Upgrading

The internal data storage format changes with new releases of PostgreSQL.
Therefore, if you are upgrading an existing installation that does not have a
version number "7.3.x", you must back up and restore your data as shown here.
These instructions assume that your existing installation is under the "/usr/
local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
Substitute your paths appropriately.

   1. Make sure that your database is not updated during or after the backup.
      This does not affect the integrity of the backup, but the changed data
      would of course not be included. If necessary, edit the permissions in
      the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
      access from everyone except you.

   2. To back up your database installation, type:

        pg_dumpall > outputfile

      If you need to preserve OIDs (such as when using them as foreign keys),
      then use the "-o" option when running "pg_dumpall".
      "pg_dumpall" does not save large objects. Check the Administrator's Guide
      if you need to do this.
      To make the backup, you can use the "pg_dumpall" command from the version
      you are currently running. For best results, however, try to use the
      "pg_dumpall" command from PostgreSQL 7.3, since this version contains
      bug fixes and improvements over older versions. While this advice might
      seem idiosyncratic since you haven't installed the new version yet, it is
      advisable to follow it if you plan to install the new version in parallel
      with the old version. In that case you can complete the installation
      normally and transfer the data later. This will also decrease the
      downtime.

   3. If you are installing the new version at the same location as the old one
      then shut down the old server, at the latest before you install the new
      files:

        kill -INT `cat /usr/local/pgsql/data/postmaster.pid`

      Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
      using such a version you must find out the process id of the server
      yourself, for example by typing "ps ax | grep postmaster", and supply it
      to the "kill" command.
      On systems that have PostgreSQL started at boot time, there is probably a
      start-up file that will accomplish the same thing. For example, on a Red
      Hat Linux system one might find that

        /etc/rc.d/init.d/postgresql stop

      works. Another possibility is "pg_ctl stop".

   4. If you are installing in the same place as the old version then it is
      also a good idea to move the old installation out of the way, in case you
      have trouble and need to revert to it. Use a command like this:

        mv /usr/local/pgsql /usr/local/pgsql.old

After you have installed PostgreSQL 7.3, create a new database directory and
start the new server. Remember that you must execute these commands while
logged in to the special database user account (which you already have if you
are upgrading).

  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

Finally, restore your data with

  /usr/local/pgsql/bin/psql -d template1 -f outputfile

using the *new* psql.
These topics are discussed at length in the Administrator's Guide, which you
are encouraged to read in any case.

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

                            Installation Procedure

   1. Configuration
      The first step of the installation procedure is to configure the source
      tree for your system and choose the options you would like. This is done
      by running the "configure" script. For a default installation simply
      enter

        ./configure

      This script will run a number of tests to guess values for various system
      dependent variables and detect some quirks of your operating system, and
      finally will create several files in the build tree to record what it
      found. (You can also run "configure" in a directory outside the source
      tree if you want to keep the build directory separate.)
      The default configuration will build the server and utilities, as well as
      all client applications and interfaces that require only a C compiler.
      All files will be installed under "/usr/local/pgsql" by default.
      You can customize the build and installation process by supplying one or
      more of the following command line options to "configure":

d237 8
a244 8

            Install all files under the directory "PREFIX" instead of "/usr/
            local/pgsql". The actual files will be installed into various
            subdirectories; no files will ever be installed directly into the
            "PREFIX" directory.
            If you have special needs, you can also customize the individual
            subdirectories with the following options.

d246 9
a254 8

            You can install architecture-dependent files under a different
            prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
            useful to share architecture-independent files between hosts. If
            you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
            architecture-dependent and independent files will be installed
            under the same tree, which is probably what you want.

d256 4
a259 4

            Specifies the directory for executable programs. The default is
            "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

d261 5
a265 5

            Sets the directory for read-only data files used by the installed
            programs. The default is "PREFIX/share". Note that this has nothing
            to do with where your database files will be placed.

d267 3
a269 4

            The directory for various configuration files, "PREFIX/etc" by
            default.

d271 3
a273 4

            The location to install libraries and dynamically loadable modules.
            The default is "EXEC-PREFIX/lib".

d275 3
a277 4

            The directory for installing C and C++ header files. The default is
            "PREFIX/include".

d279 4
a282 4

            Documentation files, except "man" pages, will be installed into
            this directory. The default is "PREFIX/doc".

d284 21
a304 22

            The man pages that come with PostgreSQL will be installed under
            this directory, in their respective "manx" subdirectories. The
            default is "PREFIX/man".
           Note: Care has been taken to make it possible to install
           PostgreSQL into shared installation locations (such as "/usr/
           local/include") without interfering with the namespace of the
           rest of the system. First, the string "/postgresql" is
           automatically appended to datadir, sysconfdir, and docdir,
           unless the fully expanded directory name already contains the
           string "postgres" or "pgsql". For example, if you choose "/usr/
           local" as prefix, the documentation will be installed in "/usr/
           local/doc/postgresql", but if the prefix is "/opt/postgres",
           then it will be in "/opt/postgres/doc". The public C header
           files of the client interfaces are installed into includedir
           and are namespace-clean. The internal header files and the
           server header files are installed into private directories
           under includedir. See the Programmer's Guide for information
           about how to get at the header files for each interface.
           Finally, a private subdirectory will also be created, if
           appropriate, under libdir for dynamically loadable modules.

d306 10
a315 8

            "DIRECTORIES" is a colon-separated list of directories that will be
            added to the list the compiler searches for header files. If you
            have optional packages (such as GNU Readline) installed in a non-
            standard location, you have to use this option and probably also
            the corresponding "--with-libraries" option.
            Example: --with-includes=/opt/gnu/include:/usr/sup/include.

d317 7
a323 7

            "DIRECTORIES" is a colon-separated list of directories to search
            for libraries. You will probably have to use this option (and the
            corresponding "--with-includes" option) if you have packages
            installed in non-standard locations.
            Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

d325 12
a336 11

            Enables Native Language Support (NLS), that is, the ability to
            display a program's messages in a language other than English.
            "LANGUAGES" is a space separated list of codes of the languages
            that you want supported, for example --enable-nls='de fr'. (The
            intersection between your list and the set of actually provided
            translations will be computed automatically.) If you do not specify
            a list, then all available translations are installed.
            To use this option, you will need an implementation of the gettext
            API; see above.

d338 8
a345 8

            Set "NUMBER" as the default port number for server and clients. The
            default is 5432. The port can always be changed later on, but if
            you specify it here then both server and clients will have the same
            default compiled in, which can be very convenient. Usually the only
            good reason to select a non-default value is if you intend to run
            multiple PostgreSQL servers on the same machine.

d347 2
a348 3

            Build the PL/Perl server-side language.

d350 2
a351 5

            Build the Python interface module and the PL/Python server-side
            language. You need to have root access to be able to install the
            Python module at its default place ("/usr/lib/pythonx.y").

d353 4
a356 4

            Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
            pgtksh, and PL/Tcl. But see below about "--without-tk".

d358 3
a360 4

            If you specify "--with-tcl" and this option, then the program that
            requires Tk (pgtksh) will be excluded.

d362 8
a369 8

            Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
            contain configuration information needed to build modules
            interfacing to Tcl or Tk. These files are normally found
            automatically at their well-known locations, but if you want to use
            a different version of Tcl or Tk you can specify the directory in
            which to find them.

d371 2
a372 3

            Build the JDBC driver and associated Java packages.

d374 16
a389 14

            Build with support for Kerberos authentication. You can use either
            Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
            specifies the root directory of the Kerberos installation; "/usr/
            athena" is assumed as default. If the relevant header files and
            libraries are not under a common parent directory, then you must
            use the "--with-includes" and "--with-libraries" options in
            addition to this option. If, on the other hand, the required files
            are in a location that is searched by default (e.g., "/usr/lib"),
            then you can leave off the argument.
            "configure" will check for the required header files and libraries
            to make sure that your Kerberos installation is sufficient before
            proceeding.

d391 3
a393 4

            The name of the Kerberos service principal. postgres is the
            default. There's probably no reason to change this.

d395 9
a403 9

            Build with support for SSL (encrypted) connections. This requires
            the OpenSSL package to be installed. The "DIRECTORY" argument
            specifies the root directory of the OpenSSL installation; the
            default is "/usr/local/ssl".
            "configure" will check for the required header files and libraries
            to make sure that your OpenSSL installation is sufficient before
            proceeding.

d405 3
a407 3

             Build with PAM (Pluggable Authentication Modules) support.

d409 17
a425 4

            Prevents the use of the Readline library. This disables command-
            line editing and history in psql, so it is not recommended.

d427 5
a431 5

            Prevents the use of the Zlib library. This disables compression
            support in pg_dump. This option is only intended for those rare
            systems where this library is not available.

d433 12
a444 12

            Compiles all programs and libraries with debugging symbols. This
            means that you can run the programs through a debugger to analyze
            problems. This enlarges the size of the installed executables
            considerably, and on non-GCC compilers it usually also disables
            compiler optimization, causing slowdowns. However, having the
            symbols available is extremely helpful for dealing with any
            problems that may arise. Currently, this option is recommended for
            production installations only if you use GCC. But you should always
            have it on if you are doing development work or running a beta
            version.

d446 12
a457 11

             Enables assertion checks in the server, which test for many "can't
            happen" conditions. This is invaluable for code development
            purposes, but the tests slow things down a little. Also, having the
            tests turned on won't necessarily enhance the stability of your
            server! The assertion checks are not categorized for severity, and
            so what might be a relatively harmless bug will still lead to
            server restarts if it triggers an assertion failure. Currently,
            this option is not recommended for production use, but you should
            have it on for development work or when running a beta version.

d459 355
a813 410

             Enables automatic dependency tracking. With this option, the
            makefiles are set up so that all affected object files will be
            rebuilt when any header file is changed. This is useful if you are
            doing development work, but is just wasted overhead if you intend
            only to compile once and install. At present, this option will work
            only if you use GCC.

      If you prefer a C compiler different from the one "configure" picks then
      you can set the environment variable CC to the program of your choice. By
      default, "configure" will pick "gcc" unless this is inappropriate for the
      platform. Similarly, you can override the default compiler flags with the
      CFLAGS variable.

      You can specify environment variables on the "configure" command line,
      for example:

        ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'

   2. Build
      To start the build, type

        gmake

      (Remember to use GNU make.) The build may take anywhere from 5 minutes to
      half an hour depending on your hardware. The last line displayed should
      be

        All of PostgreSQL is successfully made. Ready to install.

   3. Regression Tests
      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. Type

        gmake check

      (This won't work as root; do it as an unprivileged user.) It is possible
      that some tests fail, due to differences in error message wording or
      floating point results. The file "src/test/regress/README" and the
      Administrator's Guide contain detailed information about interpreting the
      test results. You can repeat this test at any later time by issuing the
      same command.

   4. Installing The Files
           Note: If you are upgrading an existing system and are going to
           install the new files over the old ones, then you should have
           backed up your data and shut down the old server by now, as
           explained in the Section called If You Are Upgrading above.
      To install PostgreSQL enter

        gmake install

      This will install files into the directories that were specified in step
      1. Make sure that you have appropriate permissions to write into that
      area. Normally you need to do this step as root. Alternatively, you could
      create the target directories in advance and arrange for appropriate
      permissions to be granted.
      You can use gmake install-strip instead of gmake install to strip the
      executable files and libraries as they are installed. This will save some
      space. If you built with debugging support, stripping will effectively
      remove the debugging support, so it should only be done if debugging is
      no longer needed. install-strip tries to do a reasonable job saving
      space, but it does not have perfect knowledge of how to strip every
      unneeded byte from an executable file, so if you want to save all the
      disk space you possibly can, you will have to do manual work.
      If you built the Python interfaces and you were not the root user when
      you executed the above command then that part of the installation
      probably failed. In that case you should become the root user and then do

        gmake -C src/interfaces/python install

      If you do not have superuser access you are on your own: you can still
      take the required files and place them in other directories where Python
      can find them, but how to do that is left as an exercise.
      The standard installation provides only the header files needed for
      client application development. If you plan to do any server-side program
      development (such as custom functions or data types written in C), then
      you may want to install the entire PostgreSQL include tree into your
      target include directory. To do that, enter

        gmake install-all-headers

      This adds a megabyte or two to the installation footprint, and is only
      useful if you don't plan to keep the whole source tree around for
      reference. (If you do, you can just use the source's include directory
      when building server-side software.)
      Client-only installation: If you want to install only the client
      applications and interface libraries, then you can use these commands:

        gmake -C src/bin install
        gmake -C src/include install
        gmake -C src/interfaces install
        gmake -C doc install

Uninstallation: To undo the installation use the command "gmake uninstall".
However, this will not remove any created directories.
Cleaning: After the installation you can make room by removing the built files
from the source tree with the command "gmake clean". This will preserve the
files made by the configure program, so that you can rebuild everything with
"gmake" later on. To reset the source tree to the state in which it was
distributed, use "gmake distclean". If you are going to build for several
platforms from the same source tree you must do this and re-configure for each
build.
If you perform a build and then discover that your configure options were
wrong, or if you change anything that configure investigates (for example,
software upgrades), then it's a good idea to do "gmake distclean" before
reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.

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

                            Post-Installation Setup

Shared Libraries

On some systems that have shared libraries (which most systems do) you need to
tell your system how to find the newly installed shared libraries. The systems
on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
The method to set the shared library search path varies between platforms, but
the most widely usable method is to set the environment variable
LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh")

  LD_LIBRARY_PATH=/usr/local/pgsql/lib
  export LD_LIBRARY_PATH

or in "csh" or "tcsh"

  setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
should put these commands into a shell start-up file such as "/etc/profile" or
"~/.bash_profile". Some good information about the caveats associated with this
method can be found at http://www.visi.com/~barr/ldpath.html.
On some systems it might be preferable to set the environment variable
LD_RUN_PATH *before* building.
On Cygwin, put the library directory in the PATH or move the ".dll" files into
the "bin/" directory.
If in doubt, refer to the manual pages of your system (perhaps "ld.so" or
"rld"). 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 this step was necessary. Simply take care of it then.
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run

  /sbin/ldconfig /usr/local/pgsql/lib

(or equivalent directory) after installation to enable the run-time linker to
find the shared libraries faster. Refer to the manual page of "ldconfig" for
more information. On FreeBSD, NetBSD, and OpenBSD the command is

  /sbin/ldconfig -m /usr/local/pgsql/lib

instead. Other systems are not known to have an equivalent command.

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

Environment Variables

If you installed into "/usr/local/pgsql" or some other location that is not
searched for programs by default, you should add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as
"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):

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

If you are using "csh" or "tcsh", then use this command:

  set path = ( /usr/local/pgsql/bin $path )

To enable your system to find the man documentation, you need to add a line
like the following to a shell start-up file unless you installed into a
location that is searched by default.

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

The environment variables PGHOST and PGPORT specify to client applications the
host and port of the database server, overriding the compiled-in defaults. If
you are going to run client applications remotely then it is convenient if
every user that plans to use the database sets PGHOST. This is not required,
however: the settings can be communicated via command line options to most
client programs.

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

                                Getting Started

The following is a quick summary of how to get PostgreSQL up and running once
installed. The Administrator's Guide contains more information.

   1. Create a user account for the PostgreSQL server. 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,
      but running the server as root is a security risk and will not work.

        adduser postgres

   2. Create a database installation with the "initdb" command. To run "initdb"
      you must be logged in to your PostgreSQL server account. It will not work
      as root.

        root# mkdir /usr/local/pgsql/data
        root# chown postgres /usr/local/pgsql/data
        root# su - postgres
        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 server account can write to the
      directory (or create it, if it doesn't already exist) before starting
      "initdb", as illustrated here.

   3. 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 put the server in the
      background use something like

        nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
            </dev/null >>server.log 2>&1 </dev/null &

      To stop a server running in the background you can type

        kill `cat /usr/local/pgsql/data/postmaster.pid`

      In order to allow TCP/IP connections (rather than only Unix domain socket
      ones) you need to pass the "-i" option to "postmaster".

   4. Create a database:

        createdb testdb

      Then enter

        psql testdb

      to connect to that database. At the prompt you can enter SQL commands and
      start experimenting.

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

                                   What Now?

    * The PostgreSQL distribution contains a comprehensive documentation set,
      which you should read sometime. After installation, the documentation can
      be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
      index.html", unless you changed the installation directories.
      The Tutorial should be your first reading if you are completely new to
      SQL databases. If you are familiar with database concepts then you want
      to proceed with the Administrator's Guide, which contains information
      about how to set up the database server, database users, and
      authentication.

    * Usually, you will want to modify your computer so that it will
      automatically start the database server whenever it boots. Some
      suggestions for this are in the Administrator's Guide.

    * 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. This is also explained in the
      Administrator's Guide.

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

                              Supported Platforms

PostgreSQL has been verified by the developer community to work on the
platforms listed below. A supported platform generally means that PostgreSQL
builds and installs according to these instructions and that the regression
tests pass.
     Note: If you are having problems with the installation on a supported
     platform, please write to <pgsql-bugs@@postgresql.org> or <pgsql-
     ports@@postgresql.org>, not to the people listed here.
 ________________________________________________________________________________
|OS______|Processor__|Version|Reported_________________________|Remarks__________|
|AIX     |RS6000     |7.3    |2002-11-12, Andreas Zeugswetter  |see also doc/    |
|________|___________|_______|(<ZeugswetterA@@spardat.at>)______|FAQ_AIX__________|
|BSD/OS  |x86        |7.3    |2002-10-25, Bruce Momjian        |4.2              |
|________|___________|_______|(<pgman@@candle.pha.pa.us>)_______|_________________|
|FreeBSD |Alpha      |7.3    |2002-11-13, Chris Kings-Lynne    |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|FreeBSD |x86        |7.3    |2002-10-29, 3.3, Nigel J. Andrews|                 |
|        |           |       |(<nandrews@@investsystems.co.uk>),|                 |
|        |           |       |4.7, Larry Rosenman              |                 |
|        |           |       |(<ler@@lerctr.org>), 5.0, Sean    |                 |
|        |           |       |Chittenden                       |                 |
|________|___________|_______|(<sean@@chittenden.org>)__________|_________________|
|HP-UX   |PA-RISC    |7.3    |2002-10-28, 10.20 Tom Lane       |gcc and cc; see  |
|        |           |       |(<tgl@@sss.pgh.pa.us>), 11.00,    |also doc/FAQ_HPUX|
|        |           |       |11.11, 32 & 64 bit, Giles Lean   |                 |
|________|___________|_______|(<giles@@nemeton.com.au>)_________|_________________|
|IRIX    |MIPS       |7.3    |2002-10-27, Ian Barwick          |Irix64 Komma 6.5 |
|________|___________|_______|(<barwick@@gmx.net>)______________|_________________|
|Linux   |Alpha      |7.3    |2002-10-28, Magnus Naeslund      |2.4.19-pre6      |
|________|___________|_______|(<mag@@fbab.net>)_________________|_________________|
|Linux   |armv4l     |7.2    |2001-12-10, Mark Knox            |2.2.x            |
|________|___________|_______|(<segfault@@hardline.org>)________|_________________|
|Linux   |MIPS       |7.2    |2001-11-15, Hisao Shibuya        |2.0.x; Cobalt    |
|________|___________|_______|(<shibuya@@alpha.or.jp>)__________|Qube2____________|
|Linux   |PlayStation|7.2    |2001-12-12, Permaine Cheung      |#undef           |
|        |2          |       |<pcheung@@redhat.com>)            |HAS_TEST_AND_SET,|
|________|___________|_______|_________________________________|slock_t__________|
|Linux   |PPC74xx    |7.3    |2002-10-26, Tom Lane             |bye 2.2.18; Apple|
|________|___________|_______|(<tgl@@sss.pgh.pa.us>)____________|G3_______________|
|Linux   |S/390      |7.2    |2001-12-12, Permaine Cheung      |                 |
|________|___________|_______|<pcheung@@redhat.com>)____________|_________________|
|Linux   |Sparc      |7.3    |2002-10-26, Doug McNaught        |3.0              |
|________|___________|_______|(<doug@@mcnaught.org>)____________|_________________|
|Linux   |x86        |7.3    |2002-10-26, Alvaro Herrera       |2.4              |
|________|___________|_______|(<alvherre@@dcc.uchile.cl>)_______|_________________|
|MacOS X |PPC        |7.3    |2002-10-28, 10.1, Tom Lane       |                 |
|        |           |       |(<tgl@@sss.pgh.pa.us>), 10.2.1,   |                 |
|        |           |       |Adam Witney                      |                 |
|________|___________|_______|(<awitney@@sghms.ac.uk>)__________|_________________|
|NetBSD  |Alpha      |7.2    |2001-11-20, Thomas Thai          |1.5W             |
|________|___________|_______|(<tom@@minnesota.com>)____________|_________________|
|NetBSD  |arm32      |7.3    |2002-11-19, Patrick Welche       |1.6              |
|________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|NetBSD  |m68k       |7.0    |2000-04-10, Henry B. Hotz        |Mac 8xx          |
|________|___________|_______|(<hotz@@jpl.nasa.gov>)____________|_________________|
|NetBSD  |MIPS       |7.2.1  |2002-06-13, Warwick Hunter       |1.5.3            |
|________|___________|_______|(<whunter@@agile.tv>)_____________|_________________|
|NetBSD  |PPC        |7.2    |2001-11-28, Bill Studenmund      |1.5              |
|________|___________|_______|(<wrstuden@@netbsd.org>)__________|_________________|
|NetBSD  |Sparc      |7.2    |2001-12-03, Matthew Green        |32- and 64-bit   |
|________|___________|_______|(<mrg@@eterna.com.au>)____________|builds___________|
|NetBSD  |VAX        |7.1    |2001-03-30, Tom I. Helbekkmo     |1.5              |
|________|___________|_______|(<tih@@kpnQwest.no>)______________|_________________|
|NetBSD  |x86        |7.3    |2002-11-14, Patrick Welche       |1.6              |
|________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|OpenBSD |Sparc      |7.3    |2002-11-17, Christopher Kings-   |3.2              |
|        |           |       |Lynne                            |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|OpenBSD |x86        |7.3    |2002-11-14, 3.1 Magnus Naeslund  |                 |
|        |           |       |(<mag@@fbab.net>), 3.2 Christopher|                 |
|        |           |       |Kings-Lynne                      |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|Solaris |Sparc      |7.3    |2002-10-28, Andrew Sullivan      |Solaris 7 & 8;   |
|        |           |       |(<andrew@@libertyrms.info>)       |see also doc/    |
|________|___________|_______|_________________________________|FAQ_Solaris______|
|Solaris |x86        |7.2    |2001-11-28, Martin Renters       |2.8; see also    |
|________|___________|_______|(<martin@@datafax.com>)___________|doc/FAQ_Solaris__|
|SunOS 4 |Sparc      |7.2    |2001-12-04, Tatsuo Ishii (<t-    |                 |
|________|___________|_______|ishii@@sra.co.jp>)________________|_________________|
|Tru64   |Alpha      |7.3    |2002-11-05, Alessio Bragadini    |                 |
|UNIX____|___________|_______|(<alessio@@albourne.com>)_________|_________________|
|UnixWare|x86        |7.3    |2002-11-01, 7.1.3 Larry Rosenman |see also doc/    |
|        |           |       |(<ler@@lerctr.org>), 7.1.1 and    |FAQ_SCO          |
|        |           |       |7.1.2(8.0.0) Olivier Prenant     |                 |
|________|___________|_______|(<ohp@@pyrenet.fr>)_______________|_________________|
|Windows |x86        |7.3    |2002-10-29, Dave Page            |with Cygwin; see |
|        |           |       |(<dpage@@vale-housing.co.uk>),    |doc/FAQ_MSWIN    |
|        |           |       |Jason Tishler                    |                 |
|________|___________|_______|(<jason@@tishler.net>)____________|_________________|
|Windows |x86        |7.3    |2002-11-05, Dave Page            |native is client-|
|        |           |       |(<dpage@@vale-housing.co.uk>)     |side only; see   |
|        |           |       |                                 |Administrator's  |
|________|___________|_______|_________________________________|Guide____________|

Unsupported Platforms: The following platforms are either known not to work, or
they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.3 at the time this list was
compiled. We include these here to let you know that these platforms *could* be
supported if given some attention.
 _____________________________________________________________________________
|OS__________|Processor|Version|Reported_______________________|Remarks_______|
|BeOS        |x86      |7.2    |2001-11-29, Cyril Velter       |needs updates |
|            |         |       |(<cyril.velter@@libertysurf.fr>)|to semaphore  |
|____________|_________|_______|_______________________________|code__________|
|DG/UX       |m88k     |6.3    |1998-03-01, Brian E Gallew     |no recent     |
|5.4R4.11____|_________|_______|(<geek+@@cmu.edu>)______________|reports_______|
|MkLinux DR1 |PPC750   |7.0    |2001-04-03, Tatsuo Ishii (<t-  |7.1 needs OS  |
|____________|_________|_______|ishii@@sra.co.jp>)______________|update?_______|
|NeXTSTEP    |x86      |6.x    |1998-03-01, David Wetzel       |bit rot       |
|____________|_________|_______|(<dave@@turbocat.de>)___________|suspected_____|
|QNX 4 RTOS  |x86      |7.2    |2001-12-10, Bernd Tegge        |needs updates |
|            |         |       |(<tegge@@repas-aeg.de>)         |to semaphore  |
|            |         |       |                               |code; see also|
|____________|_________|_______|_______________________________|doc/FAQ_QNX4__|
|QNX RTOS v6 |x86      |7.2    |2001-11-20, Igor Kovalenko     |patches       |
|            |         |       |(<Igor.Kovalenko@@motorola.com>)|available in  |
|            |         |       |                               |archives, but |
|            |         |       |                               |too late for  |
|____________|_________|_______|_______________________________|7.2___________|
|SCO         |x86      |6.5    |1999-05-25, Andrew Merrill     |7.2 should    |
|OpenServer 5|         |       |(<andrew@@compclass.com>)       |work, but no  |
|            |         |       |                               |reports; see  |
|            |         |       |                               |also doc/     |
|____________|_________|_______|_______________________________|FAQ_SCO_______|
|System V R4 |m88k     |6.2.1  |1998-03-01, Doug Winterburn    |needs new TAS |
|____________|_________|_______|(<dlw@@seavme.xroads.com>)______|spinlock_code_|
|System V R4 |MIPS     |6.4    |1998-10-28, Frank Ridderbusch  |no recent     |
|____________|_________|_______|(<ridderbusch.pad@@sni.de>)_____|reports_______|
|Ultrix      |MIPS     |7.1    |2001-03-26                     |TAS spinlock  |
|            |         |       |                               |code not      |
|____________|_________|_______|_______________________________|detected______|
|Ultrix______|VAX______|6.x____|1998-03-01_____________________|______________|

@


1.89
log
@Regenerate
@
text
@a344 7
        --enable-recode

            Enables single-byte character set recode support. See the
            Administrator's Guide about this feature. Note that a more general
            form of character set conversion is supported in the default
            configuration; this feature is obsolete.

@


1.88
log
@Specify that we need bison >= 1.50.
@
text
@a0 1
                    PostgreSQL Installation Instructions
d2 1
a2 1
  ------------------------------------------------------------------------
d4 2
a5 1
Short Version
d7 16
a22 12
./configure
gmake
su
gmake install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
d26 1
a26 1
  ------------------------------------------------------------------------
d28 1
a28 1
Requirements
d30 127
a156 53
In general, a modern Unix-compatible platform should be able to run
PostgreSQL. The platforms that had received specific testing at the time of
release are listed in the Section called Supported Platforms below. In the
"doc" subdirectory of the distribution there are several platform-specific
FAQ documents you might wish to consult if you are having trouble.

The following prerequisites exist for building PostgreSQL:

   * GNU make is required; other make programs will *not* work. GNU make is
     often installed under the name "gmake"; this document will always refer
     to it by that name. (On some systems GNU make is the default tool with
     the name "make".) To test for GNU make enter

     gmake --version

     It is recommended to use version 3.76.1 or later.

   * You need an ISO/ANSI C compiler. Recent versions of GCC are
     recommendable, but PostgreSQL is known to build with a wide variety of
     compilers from different vendors.

   * gzip is needed to unpack the distribution in the first place. If you
     are reading this, you probably already got past that hurdle.

   * The GNU Readline library (for comfortable line editing and command
     history retrieval) will automatically be used if found. You might wish
     to install it before proceeding, but it is not essential. (On NetBSD,
     the "libedit" library is readline-compatible and is used if
     "libreadline" is not found.)

   * GNU Flex and Bison are needed to build from scratch, but they are *not*
     required when building from a released source package because
     pre-generated output files are included in released packages. You will
     need these programs only when building from a CVS tree or if you
     changed the actual scanner and parser definition files. If you need
     them, be sure to get Flex 2.5.4 or later and Bison 1.50 or later. Other
     yacc programs can sometimes be used, but doing so requires extra effort
     and is not recommended. Other lex programs will definitely not work.

   * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
     packages. See the file "doc/FAQ_MSWIN" for details.

If you need to get a GNU package, you can find it at your local GNU mirror
site (see http://www.gnu.org/order/ftp.html for a list) or at
ftp://ftp.gnu.org/gnu/.

Also check that you have sufficient disk space. You will need about 30 MB
for the source tree during compilation and about 10 MB for the installation
directory. An empty database cluster takes about 20 MB, databases take about
five times the amount of space that a flat text file with the same data
would take. If you are going to run the regression tests you will
temporarily need an extra 20 MB. Use the "df" command to check for disk
space.
d158 1
a158 1
  ------------------------------------------------------------------------
d160 1
a160 1
If You Are Upgrading
d163 51
a213 25
Therefore, if you are upgrading an existing installation that does not have
a version number "7.2.x", you must back up and restore your data as shown
here. These instructions assume that your existing installation is under the
"/usr/local/pgsql" directory, and that the data area is in
"/usr/local/pgsql/data". Substitute your paths appropriately.

  1. Make sure that your database is not updated during or after the backup.
     This does not affect the integrity of the backup, but the changed data
     would of course not be included. If necessary, edit the permissions in
     the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to
     disallow access from everyone except you.

  2. To dump your database installation, type:

     pg_dumpall > outputfile

     If you need to preserve OIDs (such as when using them as foreign keys),
     then use the "-o" option when running "pg_dumpall".

     "pg_dumpall" does not save large objects. Check the Administrator's
     Guide if you need to do this.

     Make sure that you use the "pg_dumpall" command from the version you
     are currently running. 7.2's "pg_dumpall" should not be used on older
     databases.
d215 1
a215 3
  3. If you are installing the new version at the same location as the old
     one then shut down the old server, at the latest before you install the
     new files:
d217 1
a217 22
     kill -INT `cat /usr/local/pgsql/data/postmaster.pid`

     Versions prior to 7.0 do not have this "postmaster.pid" file. If you
     are using such a version you must find out the process id of the server
     yourself, for example by typing "ps ax | grep postmaster", and supply
     it to the "kill" command.

     On systems that have PostgreSQL started at boot time, there is probably
     a start-up file that will accomplish the same thing. For example, on a
     Red Hat Linux system one might find that

     /etc/rc.d/init.d/postgresql stop

     works. Another possibility is "pg_ctl stop".

  4. If you are installing in the same place as the old version then it is
     also a good idea to move the old installation out of the way, in case
     you have trouble and need to revert to it. Use a command like this:

     mv /usr/local/pgsql /usr/local/pgsql.old

After you have installed PostgreSQL 7.2, create a new database directory and
d219 2
a220 2
logged in to the special database user account (which you already have if
you are upgrading).
d222 2
a223 2
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d227 1
a227 1
/usr/local/pgsql/bin/psql -d template1 -f outputfile
d230 2
d233 1
a233 173
You can also install the new version in parallel with the old one to
decrease the downtime. These topics are discussed at length in the
Administrator's Guide, which you are encouraged to read in any case.

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

Installation Procedure

  1. Configuration

     The first step of the installation procedure is to configure the source
     tree for your system and choose the options you would like. This is
     done by running the "configure" script. For a default installation
     simply enter

     ./configure

     This script will run a number of tests to guess values for various
     system dependent variables and detect some quirks of your operating
     system, and finally will create several files in the build tree to
     record what it found.

     The default configuration will build the server and utilities, as well
     as all client applications and interfaces that require only a C
     compiler. All files will be installed under "/usr/local/pgsql" by
     default.

     You can customize the build and installation process by supplying one
     or more of the following command line options to "configure":

     --prefix=PREFIX

          Install all files under the directory "PREFIX" instead of
          "/usr/local/pgsql". The actual files will be installed into
          various subdirectories; no files will ever be installed directly
          into the "PREFIX" directory.

          If you have special needs, you can also customize the individual
          subdirectories with the following options.

     --exec-prefix=EXEC-PREFIX

          You can install architecture-dependent files under a different
          prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
          useful to share architecture-independent files between hosts. If
          you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and
          both architecture-dependent and independent files will be
          installed under the same tree, which is probably what you want.

     --bindir=DIRECTORY

          Specifies the directory for executable programs. The default is
          "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

     --datadir=DIRECTORY

          Sets the directory for read-only data files used by the installed
          programs. The default is "PREFIX/share". Note that this has
          nothing to do with where your database files will be placed.

     --sysconfdir=DIRECTORY

          The directory for various configuration files, "PREFIX/etc" by
          default.

     --libdir=DIRECTORY

          The location to install libraries and dynamically loadable
          modules. The default is "EXEC-PREFIX/lib".

     --includedir=DIRECTORY

          The directory for installing C and C++ header files. The default
          is "PREFIX/include".

     --docdir=DIRECTORY

          Documentation files, except "man" pages, will be installed into
          this directory. The default is "PREFIX/doc".

     --mandir=DIRECTORY

          The man pages that come with PostgreSQL will be installed under
          this directory, in their respective "manx" subdirectories. The
          default is "PREFIX/man".

          Note: Care has been taken to make it possible to install
          PostgreSQL into shared installation locations (such as
          "/usr/local/include") without interfering with the namespace
          of the rest of the system. First, the string "/postgresql" is
          automatically appended to datadir, sysconfdir, and docdir,
          unless the fully expanded directory name already contains the
          string "postgres" or "pgsql". For example, if you choose
          "/usr/local" as prefix, the documentation will be installed
          in "/usr/local/doc/postgresql", but if the prefix is
          "/opt/postgres", then it will be in "/opt/postgres/doc".
          Second, the installation layout of the C and C++ header files
          has been reorganized in the 7.2 release. The public header
          files of the client interfaces are installed into includedir
          and are namespace-clean. The internal header files and the
          server header files are installed into private directories
          under includedir. See the Programmer's Guide for information
          about how to get at the header files for each interface.
          Finally, a private subdirectory will also be created, if
          appropriate, under libdir for dynamically loadable modules.

     --with-includes=DIRECTORIES

          "DIRECTORIES" is a colon-separated list of directories that will
          be added to the list the compiler searches for header files. If
          you have optional packages (such as GNU Readline) installed in a
          non-standard location, you have to use this option and probably
          also the corresponding "--with-libraries" option.

          Example: --with-includes=/opt/gnu/include:/usr/sup/include.

     --with-libraries=DIRECTORIES

          "DIRECTORIES" is a colon-separated list of directories to search
          for libraries. You will probably have to use this option (and the
          corresponding "--with-includes" option) if you have packages
          installed in non-standard locations.

          Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

     --enable-locale

          Enables locale support. There is a performance penalty associated
          with locale support, but if you are not in an English-speaking
          environment you will most likely need this.

     --enable-recode

          Enables single-byte character set recode support. See the
          Administrator's Guide about this feature.

     --enable-multibyte

          Allows the use of multibyte character encodings (including
          Unicode) and character set encoding conversion. Read the
          Administrator's Guide for details.

          Note that some interfaces (such as Tcl or Java) expect all
          character strings to be in Unicode, so this option will be
          required to correctly support these interfaces.

     --enable-nls[=LANGUAGES]

          Enables Native Language Support (NLS), that is, the ability to
          display a program's messages in a language other than English.
          "LANGUAGES" is a space separated list of codes of the languages
          that you want supported, for example --enable-nls='de fr'. (The
          intersection between your list and the set of actually provided
          translations will be computed automatically.) If you do not
          specify a list, then all available translations are installed.

          To use this option, you will need an implementation of the gettext
          API. Some operating systems have this built-in (e.g., Linux,
          NetBSD, Solaris), for other systems you can download an add-on
          package from here: http://www.postgresql.org/~petere/gettext.html.
          If you are using the gettext implementation in the GNU C library
          then you will additionally need the GNU gettext package for some
          utility programs. For any of the other implementations you will
          not need it.

     --with-pgport=NUMBER

          Set "NUMBER" as the default port number for server and clients.
          The default is 5432. The port can always be changed later on, but
          if you specify it here then both server and clients will have the
          same default compiled in, which can be very convenient. Usually
          the only good reason to select a non-default value is if you
          intend to run multiple PostgreSQL servers on the same machine.
d235 1
a235 1
     --with-perl
d237 341
a577 213
          Build the Perl interface module. The Perl interface will be
          installed at the usual place for Perl modules (typically under
          "/usr/lib/perl"), so you must have root access to perform the
          installation step (see step 4). You need to have Perl 5 installed
          to use this option.

     --with-python

          Build the Python interface module. You need to have root access to
          be able to install the Python module at its default place
          ("/usr/lib/pythonx.y"). To be able to use this option, you must
          have Python installed and your system needs to support shared
          libraries. If you instead want to build a new complete interpreter
          binary, you will have to do it manually.

     --with-tcl

          Builds components that require Tcl/Tk, which are libpgtcl,
          pgtclsh, pgtksh, PgAccess, and PL/Tcl. But see below about
          "--without-tk".

     --without-tk

          If you specify "--with-tcl" and this option, then programs that
          require Tk (pgtksh and PgAccess) will be excluded.

     --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY

          Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
          contain configuration information needed to build modules
          interfacing to Tcl or Tk. These files are normally found
          automatically at their well-known locations, but if you want to
          use a different version of Tcl or Tk you can specify the directory
          in which to find them.

     --with-java

          Build the JDBC driver and associated Java packages. This option
          requires Ant to be installed (as well as a JDK, of course). Refer
          to the JDBC driver documentation in the Programmer's Guide for
          more information.

     --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY]

          Build with support for Kerberos authentication. You can use either
          Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
          specifies the root directory of the Kerberos installation;
          "/usr/athena" is assumed as default. If the relevant header files
          and libraries are not under a common parent directory, then you
          must use the "--with-includes" and "--with-libraries" options in
          addition to this option. If, on the other hand, the required files
          are in a location that is searched by default (e.g., "/usr/lib"),
          then you can leave off the argument.

          "configure" will check for the required header files and libraries
          to make sure that your Kerberos installation is sufficient before
          proceeding.

     --with-krb-srvnam=NAME

          The name of the Kerberos service principal. postgres is the
          default. There's probably no reason to change this.

     --with-openssl[=DIRECTORY]

          Build with support for SSL (encrypted) connections. This requires
          the OpenSSL package to be installed. The "DIRECTORY" argument
          specifies the root directory of the OpenSSL installation; the
          default is "/usr/local/ssl".

          "configure" will check for the required header files and libraries
          to make sure that your OpenSSL installation is sufficient before
          proceeding.

     --with-pam

          Build with PAM (Pluggable Authentication Modules) support.

     --enable-syslog

          Enables the PostgreSQL server to use the syslog logging facility.
          (Using this option does not mean that you must log with syslog or
          even that it will be done by default, it simply makes it possible
          to turn that option on at run time.)

     --enable-debug

          Compiles all programs and libraries with debugging symbols. This
          means that you can run the programs through a debugger to analyze
          problems. This enlarges the size of the installed executables
          considerably, and on non-GCC compilers it usually also disables
          compiler optimization, causing slowdowns. However, having the
          symbols available is extremely helpful for dealing with any
          problems that may arise. Currently, this option is recommended for
          production installations only if you use GCC. But you should
          always have it on if you are doing development work or running a
          beta version.

     --enable-cassert

          Enables assertion checks in the server, which test for many "can't
          happen" conditions. This is invaluable for code development
          purposes, but the tests slow things down a little. Also, having
          the tests turned on won't necessarily enhance the stability of
          your server! The assertion checks are not categorized for
          severity, and so what might be a relatively harmless bug will
          still lead to server restarts if it triggers an assertion failure.
          Currently, this option is not recommended for production use, but
          you should have it on for development work or when running a beta
          version.

     --enable-depend

          Enables automatic dependency tracking. With this option, the
          makefiles are set up so that all affected object files will be
          rebuilt when any header file is changed. This is useful if you are
          doing development work, but is just wasted overhead if you intend
          only to compile once and install. At present, this option will
          work only if you use GCC.

     If you prefer a C or C++ compiler different from the one "configure"
     picks then you can set the environment variables CC or CXX,
     respectively, to the program of your choice. Similarly, you can
     override the default compiler flags with the CFLAGS and CXXFLAGS
     variables. For example:

     env CC=/opt/bin/gcc CFLAGS='-O2 -pipe' ./configure

  2. Build

     To start the build, type

     gmake

     (Remember to use GNU make.) The build may take anywhere from 5 minutes
     to half an hour depending on your hardware. The last line displayed
     should be

     All of PostgreSQL is successfully made. Ready to install.

  3. Regression Tests

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

     gmake check

     (This won't work as root; do it as an unprivileged user.) It is
     possible that some tests fail, due to differences in error message
     wording or floating point results. The file "src/test/regress/README"
     and the Administrator's Guide contain detailed information about
     interpreting the test results. You can repeat this test at any later
     time by issuing the same command.

  4. Installing The Files

          Note: If you are upgrading an existing system and are going
          to install the new files over the old ones, then you should
          have backed up your data and shut down the old server by now,
          as explained in the Section called If You Are Upgrading
          above.

     To install PostgreSQL enter

     gmake install

     This will install files into the directories that were specified in
     step 1. Make sure that you have appropriate permissions to write into
     that area. Normally you need to do this step as root. Alternatively,
     you could create the target directories in advance and arrange for
     appropriate permissions to be granted.

     If you built the Perl or Python interfaces and you were not the root
     user when you executed the above command then that part of the
     installation probably failed. In that case you should become the root
     user and then do

     gmake -C src/interfaces/perl5 install
     gmake -C src/interfaces/python install

     If you do not have superuser access you are on your own: you can still
     take the required files and place them in other directories where Perl
     or Python can find them, but how to do that is left as an exercise.

     The standard installation provides only the header files needed for
     client application development. If you plan to do any server-side
     program development (such as custom functions or data types written in
     C), then you may want to install the entire PostgreSQL include tree
     into your target include directory. To do that, enter

     gmake install-all-headers

     This adds a megabyte or two to the installation footprint, and is only
     useful if you don't plan to keep the whole source tree around for
     reference. (If you do, you can just use the source's include directory
     when building server-side software.)

     Client-only installation: If you want to install only the client
     applications and interface libraries, then you can use these commands:

     gmake -C src/bin install
     gmake -C src/include install
     gmake -C src/interfaces install
     gmake -C doc install

     To undo the installation use the command "gmake uninstall". However,
     this will not remove any created directories.

After the installation you can make room by removing the built files from
the source tree with the "gmake clean" command. This will preserve the files
made by the configure program, so that you can rebuild everything with
d580 2
a581 3
platforms from the same source tree you must do this and re-configure for
each build.

d584 3
a586 3
you install GNU Readline), then it's a good idea to do "gmake distclean"
before reconfiguring and rebuilding. Without this, your changes in
configuration choices may not propagate everywhere they need to.
d588 1
a588 1
  ------------------------------------------------------------------------
d590 1
a590 1
Post-Installation Setup
d594 6
a599 8
On some systems that have shared libraries (which most systems do) you need
to tell your system how to find the newly installed shared libraries. The
systems on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX,
IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and
Solaris.

The method to set the shared library search path varies between platforms,
but the most widely usable method is to set the environment variable
d602 2
a603 2
LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH
d607 1
a607 7
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1.
You should put these commands into a shell start-up file such as
"/etc/profile" or "~/.bash_profile". Some good information about the caveats
associated with this method can be found at
http://www.visi.com/~barr/ldpath.html.
d609 4
d615 2
a616 1

d620 2
a621 2
psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
a623 1

d626 1
a626 1
/sbin/ldconfig /usr/local/pgsql/lib
d628 3
a630 3
(or equivalent directory) after installation to enable the run-time linker
to find the shared libraries faster. Refer to the manual page of "ldconfig"
for more information. On FreeBSD, NetBSD, and OpenBSD the command is
d632 1
a632 1
/sbin/ldconfig -m /usr/local/pgsql/lib
d636 1
a636 1
  ------------------------------------------------------------------------
d641 6
a646 4
searched for programs by default, you need to add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. To do this, add
the following to your shell start-up file, such as "~/.bash_profile" (or
"/etc/profile", if you want it to affect every user):
d648 2
a649 1
PATH=/usr/local/pgsql/bin:$PATH
d653 1
a653 1
set path = ( /usr/local/pgsql/bin $path )
d656 2
a657 3
like the following to a shell start-up file:

MANPATH=/usr/local/pgsql/man:$MANPATH
d659 2
a660 6
The environment variables PGHOST and PGPORT specify to client applications
the host and port of the database server, overriding the compiled-in
defaults. If you are going to run client applications remotely then it is
convenient if every user that plans to use the database sets PGHOST. This is
not required, however: the settings can be communicated via command line
options to most client programs.
d662 6
a667 1
  ------------------------------------------------------------------------
d669 1
a669 1
Getting Started
d671 1
a671 2
The following is a quick summary of how to get PostgreSQL up and running
once installed. The Administrator's Guide contains more information.
d673 2
a674 6
  1. Create a user account for the PostgreSQL server. 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, but running the server as root is a security risk and will not
     work.
d676 5
a680 1
     adduser postgres
d682 1
a682 3
  2. Create a database installation with the "initdb" command. To run
     "initdb" you must be logged in to your PostgreSQL server account. It
     will not work as root.
d684 3
a686 4
     root# mkdir /usr/local/pgsql/data
     root# chown postgres /usr/local/pgsql/data
     root# su - postgres
     postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
d688 4
a691 5
     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 server account can
     write to the directory (or create it, if it doesn't already exist)
     before starting "initdb", as illustrated here.
d693 5
a697 2
  3. The previous step should have told you how to start up the database
     server. Do so now. The command should look something like
d699 2
a700 1
     /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d702 1
a702 2
     This will start the server in the foreground. To put the server in the
     background use something like
d704 2
a705 2
     nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
         </dev/null >>server.log 2>&1 </dev/null &
d707 2
a708 1
     To stop a server running in the background you can type
d710 1
a710 1
     kill `cat /usr/local/pgsql/data/postmaster.pid`
d712 1
a712 2
     In order to allow TCP/IP connections (rather than only Unix domain
     socket ones) you need to pass the "-i" option to "postmaster".
d714 2
a715 1
  4. Create a database:
d717 1
a717 1
     createdb testdb
d719 1
a719 1
     Then enter
d721 1
a721 1
     psql testdb
d723 1
a723 2
     to connect to that database. At the prompt you can enter SQL commands
     and start experimenting.
d725 2
a726 1
  ------------------------------------------------------------------------
d728 1
a728 1
What Now?
d730 1
a730 5
   * The PostgreSQL distribution contains a comprehensive documentation set,
     which you should read sometime. After installation, the documentation
     can be accessed by pointing your browser to
     "/usr/local/pgsql/doc/html/index.html", unless you changed the
     installation directories.
d732 9
a740 5
     The Tutorial should be your first reading if you are completely new to
     SQL databases. If you are familiar with database concepts then you want
     to proceed with the Administrator's Guide, which contains information
     about how to set up the database server, database users, and
     authentication.
d742 3
a744 3
   * Usually, you will want to modify your computer so that it will
     automatically start the database server whenever it boots. Some
     suggestions for this are in the Administrator's Guide.
d746 4
a749 4
   * 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. This is also explained
     in the Administrator's Guide.
d751 1
a751 1
  ------------------------------------------------------------------------
d753 1
a753 1
Supported Platforms
d759 127
a886 115
     Note: If you are having problems with the installation on a
     supported platform, please write to <pgsql-bugs@@postgresql.org> or
     <pgsql-ports@@postgresql.org>, not to the people listed here.

 OS     Processor   Version Reported                         Remarks
 AIX    RS6000      7.2     2001-12-19, Andreas Zeugswetter  see also
                            (<ZeugswetterA@@spardat.at>),     doc/FAQ_AIX
                            Tatsuo Ishii
                            (<t-ishii@@sra.co.jp>)
 BeOS   x86         7.2     2001-11-29, Cyril Velter         5.0.4
                            (<cyril.velter@@libertysurf.fr>)
 BSD/OS x86         7.2     2001-11-27, Bruce Momjian        4.2
                            (<pgman@@candle.pha.pa.us>)
 FreeBSDAlpha       7.2     2001-12-18, Chris Kings-Lynne
                            (<chriskl@@familyhealth.com.au>)
 FreeBSDx86         7.2     2001-11-14, Chris Kings-Lynne
                            (<chriskl@@familyhealth.com.au>)
 HP-UX  PA-RISC     7.2     2001-11-29, Joseph Conway        11.00 and 10.20;
                            (<Joseph.Conway@@home.com>), Tom  see also
                            Lane (<tgl@@sss.pgh.pa.us>)       doc/FAQ_HPUX
 IRIX   MIPS        7.2     2001-11-28, Luis Amigo           6.5.13, MIPSPro
                            (<lamigo@@atc.unican.es>)         7.30
 Linux  Alpha       7.2     2001-11-16, Tom Lane             2.2.18; tested at
                            (<tgl@@sss.pgh.pa.us>)            SourceForge
 Linux  armv4l      7.2     2001-12-10, Mark Knox            2.2.x
                            (<segfault@@hardline.org>)
 Linux  MIPS        7.2     2001-11-15, Hisao Shibuya        2.0.x; Cobalt
                            (<shibuya@@alpha.or.jp>)          Qube2
 Linux  PlayStation 7.2     2001-12-12, Permaine Cheung      #undef
        2                   <pcheung@@redhat.com>)            HAS_TEST_AND_SET,
                                                             slock_t
 Linux  PPC74xx     7.2     2001-11-16, Tom Lane             2.2.18; Apple G3
                            (<tgl@@sss.pgh.pa.us>)
 Linux  S/390       7.2     2001-12-12, Permaine Cheung
                            <pcheung@@redhat.com>)
 Linux  Sparc       7.2     2001-11-28, Doug McNaught        2.2.19
                            (<doug@@wireboard.com>)
 Linux  x86         7.2     2001-11-15, Thomas Lockhart      2.0.x, 2.2.x,
                            (<lockhart@@fourpalms.org>)       2.4.x
 MacOS XPPC         7.2     2001-11-28, Gavin Sherry         10.1.x
                            (<swm@@linuxworld.com.au>)
 NetBSD Alpha       7.2     2001-11-20, Thomas Thai          1.5W
                            (<tom@@minnesota.com>)
 NetBSD arm32       7.1     2001-03-21, Patrick Welche       1.5E
                            (<prlw1@@cam.ac.uk>)
 NetBSD m68k        7.0     2000-04-10, Henry B. Hotz        Mac 8xx
                            (<hotz@@jpl.nasa.gov>)
 NetBSD PPC         7.2     2001-11-28, Bill Studenmund      1.5
                            (<wrstuden@@netbsd.org>)
 NetBSD Sparc       7.2     2001-12-03, Matthew Green        32- and 64-bit
                            (<mrg@@eterna.com.au>)            builds
 NetBSD VAX         7.1     2001-03-30, Tom I. Helbekkmo     1.5
                            (<tih@@kpnQwest.no>)
 NetBSD x86         7.2     2001-11-28, Bill Studenmund      1.5
                            (<wrstuden@@netbsd.org>)
 OpenBSDSparc       7.2     2001-11-27, Brandon Palmer       3.0
                            (<bpalmer@@crimelabs.net>)
 OpenBSDx86         7.2     2001-11-26, Brandon Palmer       3.0
                            (<bpalmer@@crimelabs.net>)
 Open   x86         7.2     2001-11-28, OU-8 Larry Rosenman  see also
 UNIX                       (<ler@@lerctr.org>), UW-7 Olivier doc/FAQ_SCO
                            Prenant (<ohp@@pyrenet.fr>)
 QNX 4  x86         7.2     2001-12-10, Bernd Tegge          4.25; see also
 RTOS                       (<tegge@@repas-aeg.de>)           doc/FAQ_QNX4
 SolarisSparc       7.2     2001-11-12, Andrew Sullivan      2.6-8; see also
                            (<andrew@@libertyrms.com>)        doc/FAQ_Solaris
 Solarisx86         7.2     2001-11-28, Martin Renters       2.8; see also
                            (<martin@@datafax.com>)           doc/FAQ_Solaris
 SunOS 4Sparc       7.2     2001-12-04, Tatsuo Ishii
                            (<t-ishii@@sra.co.jp>)
 Tru64  Alpha       7.2     2001-11-26, Alessio Bragadini    5.0; 4.0g with cc
 UNIX                       (<alessio@@albourne.com>), Bernd  and gcc
                            Tegge (<tegge@@repas-aeg.de>)
 Windowsx86         7.2     2001-12-13, Dave Page            with Cygwin; see
                            (<dpage@@vale-housing.co.uk>),    doc/FAQ_MSWIN
                            Jason Tishler
                            (<jason@@tishler.net>)
 Windowsx86         7.2     2001-12-10, Dave Page            native is
                            (<dpage@@vale-housing.co.uk>)     client-side only;
                                                             see
                                                             Administrator's
                                                             Guide

Unsupported Platforms: The following platforms are either known not to work,
or they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.2 at the time this list was
compiled. We include these here to let you know that these platforms *could*
be supported if given some attention.

 OS         Processor Version Reported                         Remarks
 DG/UX      m88k      6.3     1998-03-01, Brian E Gallew       no recent
 5.4R4.11                     (<geek+@@cmu.edu>)                reports
 MkLinux DR1PPC750    7.0     2001-04-03, Tatsuo Ishii         7.1 needs OS
                              (<t-ishii@@sra.co.jp>)            update?
 NeXTSTEP   x86       6.x     1998-03-01, David Wetzel         bit rot
                              (<dave@@turbocat.de>)             suspected
 QNX RTOS v6x86       7.2     2001-11-20, Igor Kovalenko       patches
                              (<Igor.Kovalenko@@motorola.com>)  available in
                                                               archives,
                                                               but too late
                                                               for 7.2
 SCO        x86       6.5     1999-05-25, Andrew Merrill       7.2 should
 OpenServer                   (<andrew@@compclass.com>)         work, but no
 5                                                             reports; see
                                                               also
                                                               doc/FAQ_SCO
 System V R4m88k      6.2.1   1998-03-01, Doug Winterburn      needs new
                              (<dlw@@seavme.xroads.com>)        TAS spinlock
                                                               code
 System V R4MIPS      6.4     1998-10-28, Frank Ridderbusch    no recent
                              (<ridderbusch.pad@@sni.de>)       reports
 Ultrix     MIPS      7.1     2001-03-26                       TAS spinlock
                                                               code not
                                                               detected
 Ultrix     VAX       6.x     1998-03-01
@


1.88.2.1
log
@Regenerate
@
text
@d1 1
d3 1
a3 1
                     PostgreSQL Installation Instructions
d5 1
a5 2
This document describes the installation of PostgreSQL from the source code
distribution.
d7 12
a18 1
-------------------------------------------------------------------------------
d20 70
a89 1
                                 Short Version
d91 5
a95 12
  ./configure
  gmake
  su
  gmake install
  adduser postgres
  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data
  su - postgres
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
  /usr/local/pgsql/bin/createdb test
  /usr/local/pgsql/bin/psql test
d97 17
a113 1
The long version is the rest of this document.
d115 1
a115 1
-------------------------------------------------------------------------------
d117 4
a120 1
                                 Requirements
d122 3
a124 127
In general, a modern Unix-compatible platform should be able to run PostgreSQL.
The platforms that had received specific testing at the time of release are
listed in the Section called Supported Platforms below. In the "doc"
subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble.
The following software packages are required for building PostgreSQL:

    * GNU make is required; other make programs will *not* work. GNU make is
      often installed under the name "gmake"; this document will always refer
      to it by that name. (On some systems GNU make is the default tool with
      the name "make".) To test for GNU make enter

        gmake --version

      It is recommended to use version 3.76.1 or later.

    * You need an ISO/ANSI C compiler. Recent versions of GCC are
      recommendable, but PostgreSQL is known to build with a wide variety of
      compilers from different vendors.

    * gzip is needed to unpack the distribution in the first place. If you are
      reading this, you probably already got past that hurdle.

    * The GNU Readline library (for comfortable line editing and command
      history retrieval) will be used by default. If you don't want to use it
      then you must specify the "--without-readline" option for "configure".
      (On NetBSD, the "libedit" library is readline-compatible and is used if
      "libreadline" is not found.)

    * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
      packages. See the file "doc/FAQ_MSWIN" for details.

The following packages are optional. They are not required in the default
configuration, but they are needed when certain build options are enabled, as
explained below.

    * To build the server programming language PL/Perl you need a full Perl
      installation, including the "libperl" library and the header files. Since
      PL/Perl will be a shared library, the "libperl" library must be a shared
      library also on most platforms. This appears to be the default in recent
      Perl versions, but it was not in earlier versions, and in general it is
      the choice of whomever installed Perl at your site.
      If you don't have the shared library but you need one, a message like
      this will appear during the build to point out this fact:

        *** Cannot build PL/Perl because libperl is not a shared library.
        *** You might have to rebuild your Perl installation.  Refer to
        *** the documentation for details.

      (If you don't follow the on-screen output you will merely notice that the
      PL/Perl library object, "plperl.so" or similar, will not be installed.)
      If you see this, you will have to rebuild and install Perl manually to be
      able to build PL/Perl. During the configuration process for Perl, request
      a shared library.

    * To build the Python interface module or the PL/Python server programming
      language, you need a Python installation, including the header files.
      Since PL/Python will be a shared library, the "libpython" library must be
      a shared library also on most platforms. This is not the case in a
      default Python installation.
      If after building and installing you have a file called "plpython.so"
      (possibly a different extension), then everything went well. Otherwise
      you should have seen a notice like this flying by:

        *** Cannot build PL/Python because libpython is not a shared library.
        *** You might have to rebuild your Python installation.  Refer to
        *** the documentation for details.

      That means you have to rebuild (part of) your Python installation to
      supply this shared library.
      The catch is that the Python distribution or the Python maintainers do
      not provide any direct way to do this. The closest thing we can offer you
      is the information in Python FAQ 3.30. On some operating systems you
      don't really have to build a shared library, but then you will have to
      convince the PostgreSQL build system of this. Consult the "Makefile" in
      the "src/pl/plpython" directory for details.

    * If you want to build Tcl or Tk components (clients and the PL/Tcl
      language) you of course need a Tcl installation.

    * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
      special tool for building Java-based packages. It can be downloaded from
      the Ant web site.
      If you have several Java compilers installed, it depends on the Ant
      configuration which one gets used. Precompiled Ant distributions are
      typically set up to read a file ".antrc" in the current user's home
      directory for configuration. For example, to use a different JDK than the
      default, this may work:

        JAVA_HOME=/usr/local/sun-jdk1.3
        JAVACMD=$JAVA_HOME/bin/java

           Note: Do not try to build the driver by calling "ant" or even
           "javac" directly. This will not work. Run "gmake" normally as
           described below.

    * To enable Native Language Support (NLS), that is, the ability to display
      a program's messages in a language other than English, you need an
      implementation of the Gettext API. Some operating systems have this
      built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
      download an add-on package from here: http://www.postgresql.org/~petere/
      gettext.html. If you are using the gettext implementation in the GNU C
      library then you will additionally need the GNU Gettext package for some
      utility programs. For any of the other implementations you will not need
      it.

    * Kerberos, OpenSSL, or PAM, if you want to support authentication using
      these services.

If you are build from a CVS tree instead of using a released source package, or
if you want to do development, you also need the following packages:

    * Flex and Bison are needed to build a CVS checkout or if you changed the
      actual scanner and parser definition files. If you need them, be sure to
      get Flex 2.5.4 or later and Bison 1.50 or later. Other yacc programs can
      sometimes be used, but doing so requires extra effort and is not
      recommended. Other lex programs will definitely not work.

If you need to get a GNU package, you can find it at your local GNU mirror site
(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for
the source tree during compilation and about 15 MB for the installation
directory. An empty database cluster takes about 25 MB, databases take about
five times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need up
to an extra 90 MB. Use the "df" command to check for disk space.
d126 1
a126 1
-------------------------------------------------------------------------------
d128 1
a128 1
                             If You Are Upgrading
d130 3
a132 52
The internal data storage format changes with new releases of PostgreSQL.
Therefore, if you are upgrading an existing installation that does not have a
version number "7.3.x", you must back up and restore your data as shown here.
These instructions assume that your existing installation is under the "/usr/
local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
Substitute your paths appropriately.

   1. Make sure that your database is not updated during or after the backup.
      This does not affect the integrity of the backup, but the changed data
      would of course not be included. If necessary, edit the permissions in
      the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
      access from everyone except you.

   2. To back up your database installation, type:

        pg_dumpall > outputfile

      If you need to preserve OIDs (such as when using them as foreign keys),
      then use the "-o" option when running "pg_dumpall".
      "pg_dumpall" does not save large objects. Check the Administrator's Guide
      if you need to do this.
      To make the backup, you can use the "pg_dumpall" command from the version
      you are currently running. For best results, however, try to use the
      "pg_dumpall" command from PostgreSQL 7.3, since this version contains
      bug fixes and improvements over older versions. While this advice might
      seem idiosyncratic since you haven't installed the new version yet, it is
      advisable to follow it if you plan to install the new version in parallel
      with the old version. In that case you can complete the installation
      normally and transfer the data later. This will also decrease the
      downtime.

   3. If you are installing the new version at the same location as the old one
      then shut down the old server, at the latest before you install the new
      files:

        kill -INT `cat /usr/local/pgsql/data/postmaster.pid`

      Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
      using such a version you must find out the process id of the server
      yourself, for example by typing "ps ax | grep postmaster", and supply it
      to the "kill" command.
      On systems that have PostgreSQL started at boot time, there is probably a
      start-up file that will accomplish the same thing. For example, on a Red
      Hat Linux system one might find that

        /etc/rc.d/init.d/postgresql stop

      works. Another possibility is "pg_ctl stop".

   4. If you are installing in the same place as the old version then it is
      also a good idea to move the old installation out of the way, in case you
      have trouble and need to revert to it. Use a command like this:
d134 1
a134 1
        mv /usr/local/pgsql /usr/local/pgsql.old
d136 1
a136 1
After you have installed PostgreSQL 7.3, create a new database directory and
d138 2
a139 2
logged in to the special database user account (which you already have if you
are upgrading).
d141 2
a142 2
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d146 1
a146 1
  /usr/local/pgsql/bin/psql -d template1 -f outputfile
a148 2
These topics are discussed at length in the Administrator's Guide, which you
are encouraged to read in any case.
d150 173
a322 1
-------------------------------------------------------------------------------
d324 1
a324 1
                            Installation Procedure
d326 213
a538 341
   1. Configuration
      The first step of the installation procedure is to configure the source
      tree for your system and choose the options you would like. This is done
      by running the "configure" script. For a default installation simply
      enter

        ./configure

      This script will run a number of tests to guess values for various system
      dependent variables and detect some quirks of your operating system, and
      finally will create several files in the build tree to record what it
      found. (You can also run "configure" in a directory outside the source
      tree if you want to keep the build directory separate.)
      The default configuration will build the server and utilities, as well as
      all client applications and interfaces that require only a C compiler.
      All files will be installed under "/usr/local/pgsql" by default.
      You can customize the build and installation process by supplying one or
      more of the following command line options to "configure":

        --prefix=PREFIX

            Install all files under the directory "PREFIX" instead of "/usr/
            local/pgsql". The actual files will be installed into various
            subdirectories; no files will ever be installed directly into the
            "PREFIX" directory.
            If you have special needs, you can also customize the individual
            subdirectories with the following options.

        --exec-prefix=EXEC-PREFIX

            You can install architecture-dependent files under a different
            prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
            useful to share architecture-independent files between hosts. If
            you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
            architecture-dependent and independent files will be installed
            under the same tree, which is probably what you want.

        --bindir=DIRECTORY

            Specifies the directory for executable programs. The default is
            "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

        --datadir=DIRECTORY

            Sets the directory for read-only data files used by the installed
            programs. The default is "PREFIX/share". Note that this has nothing
            to do with where your database files will be placed.

        --sysconfdir=DIRECTORY

            The directory for various configuration files, "PREFIX/etc" by
            default.

        --libdir=DIRECTORY

            The location to install libraries and dynamically loadable modules.
            The default is "EXEC-PREFIX/lib".

        --includedir=DIRECTORY

            The directory for installing C and C++ header files. The default is
            "PREFIX/include".

        --docdir=DIRECTORY

            Documentation files, except "man" pages, will be installed into
            this directory. The default is "PREFIX/doc".

        --mandir=DIRECTORY

            The man pages that come with PostgreSQL will be installed under
            this directory, in their respective "manx" subdirectories. The
            default is "PREFIX/man".
           Note: Care has been taken to make it possible to install
           PostgreSQL into shared installation locations (such as "/usr/
           local/include") without interfering with the namespace of the
           rest of the system. First, the string "/postgresql" is
           automatically appended to datadir, sysconfdir, and docdir,
           unless the fully expanded directory name already contains the
           string "postgres" or "pgsql". For example, if you choose "/usr/
           local" as prefix, the documentation will be installed in "/usr/
           local/doc/postgresql", but if the prefix is "/opt/postgres",
           then it will be in "/opt/postgres/doc". The public C header
           files of the client interfaces are installed into includedir
           and are namespace-clean. The internal header files and the
           server header files are installed into private directories
           under includedir. See the Programmer's Guide for information
           about how to get at the header files for each interface.
           Finally, a private subdirectory will also be created, if
           appropriate, under libdir for dynamically loadable modules.

        --with-includes=DIRECTORIES

            "DIRECTORIES" is a colon-separated list of directories that will be
            added to the list the compiler searches for header files. If you
            have optional packages (such as GNU Readline) installed in a non-
            standard location, you have to use this option and probably also
            the corresponding "--with-libraries" option.
            Example: --with-includes=/opt/gnu/include:/usr/sup/include.

        --with-libraries=DIRECTORIES

            "DIRECTORIES" is a colon-separated list of directories to search
            for libraries. You will probably have to use this option (and the
            corresponding "--with-includes" option) if you have packages
            installed in non-standard locations.
            Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

        --enable-recode

            Enables single-byte character set recode support. See the
            Administrator's Guide about this feature. Note that a more general
            form of character set conversion is supported in the default
            configuration; this feature is obsolete.

        --enable-nls[=LANGUAGES]

            Enables Native Language Support (NLS), that is, the ability to
            display a program's messages in a language other than English.
            "LANGUAGES" is a space separated list of codes of the languages
            that you want supported, for example --enable-nls='de fr'. (The
            intersection between your list and the set of actually provided
            translations will be computed automatically.) If you do not specify
            a list, then all available translations are installed.
            To use this option, you will need an implementation of the gettext
            API; see above.

        --with-pgport=NUMBER

            Set "NUMBER" as the default port number for server and clients. The
            default is 5432. The port can always be changed later on, but if
            you specify it here then both server and clients will have the same
            default compiled in, which can be very convenient. Usually the only
            good reason to select a non-default value is if you intend to run
            multiple PostgreSQL servers on the same machine.

        --with-perl

            Build the PL/Perl server-side language.

        --with-python

            Build the Python interface module and the PL/Python server-side
            language. You need to have root access to be able to install the
            Python module at its default place ("/usr/lib/pythonx.y").

        --with-tcl

            Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
            pgtksh, and PL/Tcl. But see below about "--without-tk".

        --without-tk

            If you specify "--with-tcl" and this option, then the program that
            requires Tk (pgtksh) will be excluded.

        --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY

            Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
            contain configuration information needed to build modules
            interfacing to Tcl or Tk. These files are normally found
            automatically at their well-known locations, but if you want to use
            a different version of Tcl or Tk you can specify the directory in
            which to find them.

        --with-java

            Build the JDBC driver and associated Java packages.

        --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY]

            Build with support for Kerberos authentication. You can use either
            Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
            specifies the root directory of the Kerberos installation; "/usr/
            athena" is assumed as default. If the relevant header files and
            libraries are not under a common parent directory, then you must
            use the "--with-includes" and "--with-libraries" options in
            addition to this option. If, on the other hand, the required files
            are in a location that is searched by default (e.g., "/usr/lib"),
            then you can leave off the argument.
            "configure" will check for the required header files and libraries
            to make sure that your Kerberos installation is sufficient before
            proceeding.

        --with-krb-srvnam=NAME

            The name of the Kerberos service principal. postgres is the
            default. There's probably no reason to change this.

        --with-openssl[=DIRECTORY]

            Build with support for SSL (encrypted) connections. This requires
            the OpenSSL package to be installed. The "DIRECTORY" argument
            specifies the root directory of the OpenSSL installation; the
            default is "/usr/local/ssl".
            "configure" will check for the required header files and libraries
            to make sure that your OpenSSL installation is sufficient before
            proceeding.

        --with-pam

             Build with PAM (Pluggable Authentication Modules) support.

        --without-readline

            Prevents the use of the Readline library. This disables command-
            line editing and history in psql, so it is not recommended.

        --without-zlib

            Prevents the use of the Zlib library. This disables compression
            support in pg_dump. This option is only intended for those rare
            systems where this library is not available.

        --enable-debug

            Compiles all programs and libraries with debugging symbols. This
            means that you can run the programs through a debugger to analyze
            problems. This enlarges the size of the installed executables
            considerably, and on non-GCC compilers it usually also disables
            compiler optimization, causing slowdowns. However, having the
            symbols available is extremely helpful for dealing with any
            problems that may arise. Currently, this option is recommended for
            production installations only if you use GCC. But you should always
            have it on if you are doing development work or running a beta
            version.

        --enable-cassert

             Enables assertion checks in the server, which test for many "can't
            happen" conditions. This is invaluable for code development
            purposes, but the tests slow things down a little. Also, having the
            tests turned on won't necessarily enhance the stability of your
            server! The assertion checks are not categorized for severity, and
            so what might be a relatively harmless bug will still lead to
            server restarts if it triggers an assertion failure. Currently,
            this option is not recommended for production use, but you should
            have it on for development work or when running a beta version.

        --enable-depend

             Enables automatic dependency tracking. With this option, the
            makefiles are set up so that all affected object files will be
            rebuilt when any header file is changed. This is useful if you are
            doing development work, but is just wasted overhead if you intend
            only to compile once and install. At present, this option will work
            only if you use GCC.

      If you prefer a C compiler different from the one "configure" picks then
      you can set the environment variable CC to the program of your choice. By
      default, "configure" will pick "gcc" unless this is inappropriate for the
      platform. Similarly, you can override the default compiler flags with the
      CFLAGS variable.

      You can specify environment variables on the "configure" command line,
      for example:

        ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'

   2. Build
      To start the build, type

        gmake

      (Remember to use GNU make.) The build may take anywhere from 5 minutes to
      half an hour depending on your hardware. The last line displayed should
      be

        All of PostgreSQL is successfully made. Ready to install.

   3. Regression Tests
      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. Type

        gmake check

      (This won't work as root; do it as an unprivileged user.) It is possible
      that some tests fail, due to differences in error message wording or
      floating point results. The file "src/test/regress/README" and the
      Administrator's Guide contain detailed information about interpreting the
      test results. You can repeat this test at any later time by issuing the
      same command.

   4. Installing The Files
           Note: If you are upgrading an existing system and are going to
           install the new files over the old ones, then you should have
           backed up your data and shut down the old server by now, as
           explained in the Section called If You Are Upgrading above.
      To install PostgreSQL enter

        gmake install

      This will install files into the directories that were specified in step
      1. Make sure that you have appropriate permissions to write into that
      area. Normally you need to do this step as root. Alternatively, you could
      create the target directories in advance and arrange for appropriate
      permissions to be granted.
      You can use gmake install-strip instead of gmake install to strip the
      executable files and libraries as they are installed. This will save some
      space. If you built with debugging support, stripping will effectively
      remove the debugging support, so it should only be done if debugging is
      no longer needed. install-strip tries to do a reasonable job saving
      space, but it does not have perfect knowledge of how to strip every
      unneeded byte from an executable file, so if you want to save all the
      disk space you possibly can, you will have to do manual work.
      If you built the Python interfaces and you were not the root user when
      you executed the above command then that part of the installation
      probably failed. In that case you should become the root user and then do

        gmake -C src/interfaces/python install

      If you do not have superuser access you are on your own: you can still
      take the required files and place them in other directories where Python
      can find them, but how to do that is left as an exercise.
      The standard installation provides only the header files needed for
      client application development. If you plan to do any server-side program
      development (such as custom functions or data types written in C), then
      you may want to install the entire PostgreSQL include tree into your
      target include directory. To do that, enter

        gmake install-all-headers

      This adds a megabyte or two to the installation footprint, and is only
      useful if you don't plan to keep the whole source tree around for
      reference. (If you do, you can just use the source's include directory
      when building server-side software.)
      Client-only installation: If you want to install only the client
      applications and interface libraries, then you can use these commands:

        gmake -C src/bin install
        gmake -C src/include install
        gmake -C src/interfaces install
        gmake -C doc install

Uninstallation: To undo the installation use the command "gmake uninstall".
However, this will not remove any created directories.
Cleaning: After the installation you can make room by removing the built files
from the source tree with the command "gmake clean". This will preserve the
files made by the configure program, so that you can rebuild everything with
d541 3
a543 2
platforms from the same source tree you must do this and re-configure for each
build.
d546 3
a548 3
software upgrades), then it's a good idea to do "gmake distclean" before
reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.
d550 1
a550 1
-------------------------------------------------------------------------------
d552 1
a552 1
                            Post-Installation Setup
d556 8
a563 6
On some systems that have shared libraries (which most systems do) you need to
tell your system how to find the newly installed shared libraries. The systems
on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
The method to set the shared library search path varies between platforms, but
the most widely usable method is to set the environment variable
d566 2
a567 2
  LD_LIBRARY_PATH=/usr/local/pgsql/lib
  export LD_LIBRARY_PATH
d571 7
a577 1
  setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
a578 4
Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
should put these commands into a shell start-up file such as "/etc/profile" or
"~/.bash_profile". Some good information about the caveats associated with this
method can be found at http://www.visi.com/~barr/ldpath.html.
d581 1
a581 2
On Cygwin, put the library directory in the PATH or move the ".dll" files into
the "bin/" directory.
d585 2
a586 2
  psql: error in loading shared libraries
  libpq.so.2.1: cannot open shared object file: No such file or directory
d589 1
d592 1
a592 1
  /sbin/ldconfig /usr/local/pgsql/lib
d594 3
a596 3
(or equivalent directory) after installation to enable the run-time linker to
find the shared libraries faster. Refer to the manual page of "ldconfig" for
more information. On FreeBSD, NetBSD, and OpenBSD the command is
d598 1
a598 1
  /sbin/ldconfig -m /usr/local/pgsql/lib
d602 1
a602 1
-------------------------------------------------------------------------------
d607 4
a610 6
searched for programs by default, you should add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as
"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):
d612 1
a612 2
  PATH=/usr/local/pgsql/bin:$PATH
  export PATH
d616 1
a616 1
  set path = ( /usr/local/pgsql/bin $path )
d619 3
a621 2
like the following to a shell start-up file unless you installed into a
location that is searched by default.
d623 6
a628 2
  MANPATH=/usr/local/pgsql/man:$MANPATH
  export MANPATH
d630 1
a630 6
The environment variables PGHOST and PGPORT specify to client applications the
host and port of the database server, overriding the compiled-in defaults. If
you are going to run client applications remotely then it is convenient if
every user that plans to use the database sets PGHOST. This is not required,
however: the settings can be communicated via command line options to most
client programs.
d632 1
a632 1
-------------------------------------------------------------------------------
d634 2
a635 1
                                Getting Started
d637 6
a642 2
The following is a quick summary of how to get PostgreSQL up and running once
installed. The Administrator's Guide contains more information.
d644 1
a644 5
   1. Create a user account for the PostgreSQL server. 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,
      but running the server as root is a security risk and will not work.
d646 3
a648 1
        adduser postgres
d650 4
a653 3
   2. Create a database installation with the "initdb" command. To run "initdb"
      you must be logged in to your PostgreSQL server account. It will not work
      as root.
d655 5
a659 4
        root# mkdir /usr/local/pgsql/data
        root# chown postgres /usr/local/pgsql/data
        root# su - postgres
        postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
d661 2
a662 5
      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 server account can write to the
      directory (or create it, if it doesn't already exist) before starting
      "initdb", as illustrated here.
d664 1
a664 2
   3. The previous step should have told you how to start up the database
      server. Do so now. The command should look something like
d666 2
a667 1
        /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d669 2
a670 2
      This will start the server in the foreground. To put the server in the
      background use something like
d672 1
a672 2
        nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
            </dev/null >>server.log 2>&1 </dev/null &
d674 1
a674 1
      To stop a server running in the background you can type
d676 2
a677 1
        kill `cat /usr/local/pgsql/data/postmaster.pid`
d679 1
a679 2
      In order to allow TCP/IP connections (rather than only Unix domain socket
      ones) you need to pass the "-i" option to "postmaster".
d681 1
a681 1
   4. Create a database:
d683 1
a683 1
        createdb testdb
d685 1
a685 1
      Then enter
d687 2
a688 1
        psql testdb
d690 1
a690 2
      to connect to that database. At the prompt you can enter SQL commands and
      start experimenting.
d692 1
a692 1
-------------------------------------------------------------------------------
d694 5
a698 1
                                   What Now?
d700 5
a704 9
    * The PostgreSQL distribution contains a comprehensive documentation set,
      which you should read sometime. After installation, the documentation can
      be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
      index.html", unless you changed the installation directories.
      The Tutorial should be your first reading if you are completely new to
      SQL databases. If you are familiar with database concepts then you want
      to proceed with the Administrator's Guide, which contains information
      about how to set up the database server, database users, and
      authentication.
d706 3
a708 3
    * Usually, you will want to modify your computer so that it will
      automatically start the database server whenever it boots. Some
      suggestions for this are in the Administrator's Guide.
d710 4
a713 4
    * 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. This is also explained in the
      Administrator's Guide.
d715 1
a715 1
-------------------------------------------------------------------------------
d717 1
a717 1
                              Supported Platforms
a722 127
     Note: If you are having problems with the installation on a supported
     platform, please write to <pgsql-bugs@@postgresql.org> or <pgsql-
     ports@@postgresql.org>, not to the people listed here.
 ________________________________________________________________________________
|OS______|Processor__|Version|Reported_________________________|Remarks__________|
|AIX     |RS6000     |7.3    |2002-11-12, Andreas Zeugswetter  |see also doc/    |
|________|___________|_______|(<ZeugswetterA@@spardat.at>)______|FAQ_AIX__________|
|BSD/OS  |x86        |7.3    |2002-10-25, Bruce Momjian        |4.2              |
|________|___________|_______|(<pgman@@candle.pha.pa.us>)_______|_________________|
|FreeBSD |Alpha      |7.3    |2002-11-13, Chris Kings-Lynne    |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|FreeBSD |x86        |7.3    |2002-10-29, 3.3, Nigel J. Andrews|                 |
|        |           |       |(<nandrews@@investsystems.co.uk>),|                 |
|        |           |       |4.7, Larry Rosenman              |                 |
|        |           |       |(<ler@@lerctr.org>), 5.0, Sean    |                 |
|        |           |       |Chittenden                       |                 |
|________|___________|_______|(<sean@@chittenden.org>)__________|_________________|
|HP-UX   |PA-RISC    |7.3    |2002-10-28, 10.20 Tom Lane       |gcc and cc; see  |
|        |           |       |(<tgl@@sss.pgh.pa.us>), 11.00,    |also doc/FAQ_HPUX|
|        |           |       |11.11, 32 & 64 bit, Giles Lean   |                 |
|________|___________|_______|(<giles@@nemeton.com.au>)_________|_________________|
|IRIX    |MIPS       |7.3    |2002-10-27, Ian Barwick          |Irix64 Komma 6.5 |
|________|___________|_______|(<barwick@@gmx.net>)______________|_________________|
|Linux   |Alpha      |7.3    |2002-10-28, Magnus Naeslund      |2.4.19-pre6      |
|________|___________|_______|(<mag@@fbab.net>)_________________|_________________|
|Linux   |armv4l     |7.2    |2001-12-10, Mark Knox            |2.2.x            |
|________|___________|_______|(<segfault@@hardline.org>)________|_________________|
|Linux   |MIPS       |7.2    |2001-11-15, Hisao Shibuya        |2.0.x; Cobalt    |
|________|___________|_______|(<shibuya@@alpha.or.jp>)__________|Qube2____________|
|Linux   |PlayStation|7.2    |2001-12-12, Permaine Cheung      |#undef           |
|        |2          |       |<pcheung@@redhat.com>)            |HAS_TEST_AND_SET,|
|________|___________|_______|_________________________________|slock_t__________|
|Linux   |PPC74xx    |7.3    |2002-10-26, Tom Lane             |bye 2.2.18; Apple|
|________|___________|_______|(<tgl@@sss.pgh.pa.us>)____________|G3_______________|
|Linux   |S/390      |7.2    |2001-12-12, Permaine Cheung      |                 |
|________|___________|_______|<pcheung@@redhat.com>)____________|_________________|
|Linux   |Sparc      |7.3    |2002-10-26, Doug McNaught        |3.0              |
|________|___________|_______|(<doug@@mcnaught.org>)____________|_________________|
|Linux   |x86        |7.3    |2002-10-26, Alvaro Herrera       |2.4              |
|________|___________|_______|(<alvherre@@dcc.uchile.cl>)_______|_________________|
|MacOS X |PPC        |7.3    |2002-10-28, 10.1, Tom Lane       |                 |
|        |           |       |(<tgl@@sss.pgh.pa.us>), 10.2.1,   |                 |
|        |           |       |Adam Witney                      |                 |
|________|___________|_______|(<awitney@@sghms.ac.uk>)__________|_________________|
|NetBSD  |Alpha      |7.2    |2001-11-20, Thomas Thai          |1.5W             |
|________|___________|_______|(<tom@@minnesota.com>)____________|_________________|
|NetBSD  |arm32      |7.3    |2002-11-19, Patrick Welche       |1.6              |
|________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|NetBSD  |m68k       |7.0    |2000-04-10, Henry B. Hotz        |Mac 8xx          |
|________|___________|_______|(<hotz@@jpl.nasa.gov>)____________|_________________|
|NetBSD  |MIPS       |7.2.1  |2002-06-13, Warwick Hunter       |1.5.3            |
|________|___________|_______|(<whunter@@agile.tv>)_____________|_________________|
|NetBSD  |PPC        |7.2    |2001-11-28, Bill Studenmund      |1.5              |
|________|___________|_______|(<wrstuden@@netbsd.org>)__________|_________________|
|NetBSD  |Sparc      |7.2    |2001-12-03, Matthew Green        |32- and 64-bit   |
|________|___________|_______|(<mrg@@eterna.com.au>)____________|builds___________|
|NetBSD  |VAX        |7.1    |2001-03-30, Tom I. Helbekkmo     |1.5              |
|________|___________|_______|(<tih@@kpnQwest.no>)______________|_________________|
|NetBSD  |x86        |7.3    |2002-11-14, Patrick Welche       |1.6              |
|________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|OpenBSD |Sparc      |7.3    |2002-11-17, Christopher Kings-   |3.2              |
|        |           |       |Lynne                            |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|OpenBSD |x86        |7.3    |2002-11-14, 3.1 Magnus Naeslund  |                 |
|        |           |       |(<mag@@fbab.net>), 3.2 Christopher|                 |
|        |           |       |Kings-Lynne                      |                 |
|________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|Solaris |Sparc      |7.3    |2002-10-28, Andrew Sullivan      |Solaris 7 & 8;   |
|        |           |       |(<andrew@@libertyrms.info>)       |see also doc/    |
|________|___________|_______|_________________________________|FAQ_Solaris______|
|Solaris |x86        |7.2    |2001-11-28, Martin Renters       |2.8; see also    |
|________|___________|_______|(<martin@@datafax.com>)___________|doc/FAQ_Solaris__|
|SunOS 4 |Sparc      |7.2    |2001-12-04, Tatsuo Ishii (<t-    |                 |
|________|___________|_______|ishii@@sra.co.jp>)________________|_________________|
|Tru64   |Alpha      |7.3    |2002-11-05, Alessio Bragadini    |                 |
|UNIX____|___________|_______|(<alessio@@albourne.com>)_________|_________________|
|UnixWare|x86        |7.3    |2002-11-01, 7.1.3 Larry Rosenman |see also doc/    |
|        |           |       |(<ler@@lerctr.org>), 7.1.1 and    |FAQ_SCO          |
|        |           |       |7.1.2(8.0.0) Olivier Prenant     |                 |
|________|___________|_______|(<ohp@@pyrenet.fr>)_______________|_________________|
|Windows |x86        |7.3    |2002-10-29, Dave Page            |with Cygwin; see |
|        |           |       |(<dpage@@vale-housing.co.uk>),    |doc/FAQ_MSWIN    |
|        |           |       |Jason Tishler                    |                 |
|________|___________|_______|(<jason@@tishler.net>)____________|_________________|
|Windows |x86        |7.3    |2002-11-05, Dave Page            |native is client-|
|        |           |       |(<dpage@@vale-housing.co.uk>)     |side only; see   |
|        |           |       |                                 |Administrator's  |
|________|___________|_______|_________________________________|Guide____________|

Unsupported Platforms: The following platforms are either known not to work, or
they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.3 at the time this list was
compiled. We include these here to let you know that these platforms *could* be
supported if given some attention.
 _____________________________________________________________________________
|OS__________|Processor|Version|Reported_______________________|Remarks_______|
|BeOS        |x86      |7.2    |2001-11-29, Cyril Velter       |needs updates |
|            |         |       |(<cyril.velter@@libertysurf.fr>)|to semaphore  |
|____________|_________|_______|_______________________________|code__________|
|DG/UX       |m88k     |6.3    |1998-03-01, Brian E Gallew     |no recent     |
|5.4R4.11____|_________|_______|(<geek+@@cmu.edu>)______________|reports_______|
|MkLinux DR1 |PPC750   |7.0    |2001-04-03, Tatsuo Ishii (<t-  |7.1 needs OS  |
|____________|_________|_______|ishii@@sra.co.jp>)______________|update?_______|
|NeXTSTEP    |x86      |6.x    |1998-03-01, David Wetzel       |bit rot       |
|____________|_________|_______|(<dave@@turbocat.de>)___________|suspected_____|
|QNX 4 RTOS  |x86      |7.2    |2001-12-10, Bernd Tegge        |needs updates |
|            |         |       |(<tegge@@repas-aeg.de>)         |to semaphore  |
|            |         |       |                               |code; see also|
|____________|_________|_______|_______________________________|doc/FAQ_QNX4__|
|QNX RTOS v6 |x86      |7.2    |2001-11-20, Igor Kovalenko     |patches       |
|            |         |       |(<Igor.Kovalenko@@motorola.com>)|available in  |
|            |         |       |                               |archives, but |
|            |         |       |                               |too late for  |
|____________|_________|_______|_______________________________|7.2___________|
|SCO         |x86      |6.5    |1999-05-25, Andrew Merrill     |7.2 should    |
|OpenServer 5|         |       |(<andrew@@compclass.com>)       |work, but no  |
|            |         |       |                               |reports; see  |
|            |         |       |                               |also doc/     |
|____________|_________|_______|_______________________________|FAQ_SCO_______|
|System V R4 |m88k     |6.2.1  |1998-03-01, Doug Winterburn    |needs new TAS |
|____________|_________|_______|(<dlw@@seavme.xroads.com>)______|spinlock_code_|
|System V R4 |MIPS     |6.4    |1998-10-28, Frank Ridderbusch  |no recent     |
|____________|_________|_______|(<ridderbusch.pad@@sni.de>)_____|reports_______|
|Ultrix      |MIPS     |7.1    |2001-03-26                     |TAS spinlock  |
|            |         |       |                               |code not      |
|____________|_________|_______|_______________________________|detected______|
|Ultrix______|VAX______|6.x____|1998-03-01_____________________|______________|
d724 115
@


1.88.2.2
log
@Update INSTALL file for 7.3.1.
@
text
@d2 254
a255 234
                    PostgreSQL Installation Instructions
                                      
   This document describes the installation of PostgreSQL from the source
   code distribution.
     _________________________________________________________________
   
                               Short Version
                                      
./configure
gmake
su
gmake install
adduser postgres
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test

   The long version is the rest of this document.
     _________________________________________________________________
   
                                Requirements
                                      
   In general, a modern Unix-compatible platform should be able to run
   PostgreSQL. The platforms that had received specific testing at the
   time of release are listed in the section called Supported Platforms
   below. In the "doc" subdirectory of the distribution there are several
   platform-specific FAQ documents you might wish to consult if you are
   having trouble.
   
   The following software packages are required for building PostgreSQL:
   
     * GNU make is required; other make programs will *not* work. GNU
       make is often installed under the name "gmake"; this document will
       always refer to it by that name. (On some systems GNU make is the
       default tool with the name "make".) To test for GNU make enter
gmake --version
       It is recommended to use version 3.76.1 or later.
     * You need an ISO/ANSI C compiler. Recent versions of GCC are
       recommendable, but PostgreSQL is known to build with a wide
       variety of compilers from different vendors.
     * gzip is needed to unpack the distribution in the first place. If
       you are reading this, you probably already got past that hurdle.
     * The GNU Readline library (for comfortable line editing and command
       history retrieval) will be used by default. If you don't want to
       use it then you must specify the "--without-readline" option for
       "configure". (On NetBSD, the "libedit" library is
       readline-compatible and is used if "libreadline" is not found.)
     * To build on Windows NT or Windows 2000 you need the Cygwin and
       cygipc packages. See the file "doc/FAQ_MSWIN" for details.
       
   The following packages are optional. They are not required in the
   default configuration, but they are needed when certain build options
   are enabled, as explained below.
   
     * To build the server programming language PL/Perl you need a full
       Perl installation, including the "libperl" library and the header
       files. Since PL/Perl will be a shared library, the "libperl"
       library must be a shared library also on most platforms. This
       appears to be the default in recent Perl versions, but it was not
       in earlier versions, and in general it is the choice of whomever
       installed Perl at your site.
       If you don't have the shared library but you need one, a message
       like this will appear during the build to point out this fact:
*** Cannot build PL/Perl because libperl is not a shared library.
*** You might have to rebuild your Perl installation.  Refer to
*** the documentation for details.
       (If you don't follow the on-screen output you will merely notice
       that the PL/Perl library object, "plperl.so" or similar, will not
       be installed.) If you see this, you will have to rebuild and
       install Perl manually to be able to build PL/Perl. During the
       configuration process for Perl, request a shared library.
     * To build the Python interface module or the PL/Python server
       programming language, you need a Python installation, including
       the header files. Since PL/Python will be a shared library, the
       "libpython" library must be a shared library also on most
       platforms. This is not the case in a default Python installation.
       If after building and installing you have a file called
       "plpython.so" (possibly a different extension), then everything
       went well. Otherwise you should have seen a notice like this
       flying by:
*** Cannot build PL/Python because libpython is not a shared library.
*** You might have to rebuild your Python installation.  Refer to
*** the documentation for details.
       That means you have to rebuild (part of) your Python installation
       to supply this shared library.
       The catch is that the Python distribution or the Python
       maintainers do not provide any direct way to do this. The closest
       thing we can offer you is the information in Python FAQ 3.30. On
       some operating systems you don't really have to build a shared
       library, but then you will have to convince the PostgreSQL build
       system of this. Consult the "Makefile" in the "src/pl/plpython"
       directory for details.
     * If you want to build Tcl or Tk components (clients and the PL/Tcl
       language) you of course need a Tcl installation.
     * To build the JDBC driver, you need Ant 1.5 or higher and a JDK.
       Ant is a special tool for building Java-based packages. It can be
       downloaded from the Ant web site.
       If you have several Java compilers installed, it depends on the
       Ant configuration which one gets used. Precompiled Ant
       distributions are typically set up to read a file ".antrc" in the
       current user's home directory for configuration. For example, to
       use a different JDK than the default, this may work:
JAVA_HOME=/usr/local/sun-jdk1.3
JAVACMD=$JAVA_HOME/bin/java
       
     Note: Do not try to build the driver by calling "ant" or even
     "javac" directly. This will not work. Run "gmake" normally as
     described below.
     * To enable Native Language Support (NLS), that is, the ability to
       display a program's messages in a language other than English, you
       need an implementation of the Gettext API. Some operating systems
       have this built-in (e.g., Linux, NetBSD, Solaris), for other
       systems you can download an add-on package from here:
       http://www.postgresql.org/~petere/gettext.html. If you are using
       the gettext implementation in the GNU C library then you will
       additionally need the GNU Gettext package for some utility
       programs. For any of the other implementations you will not need
       it.
     * Kerberos, OpenSSL, or PAM, if you want to support authentication
       using these services.
       
   If you are build from a CVS tree instead of using a released source
   package, or if you want to do development, you also need the following
   packages:
   
     * Flex and Bison are needed to build a CVS checkout or if you
       changed the actual scanner and parser definition files. If you
       need them, be sure to get Flex 2.5.4 or later and Bison 1.50 or
       later. Other yacc programs can sometimes be used, but doing so
       requires extra effort and is not recommended. Other lex programs
       will definitely not work.
       
   If you need to get a GNU package, you can find it at your local GNU
   mirror site (see http://www.gnu.org/order/ftp.html for a list) or at
   ftp://ftp.gnu.org/gnu/.
   
   Also check that you have sufficient disk space. You will need about 65
   MB for the source tree during compilation and about 15 MB for the
   installation directory. An empty database cluster takes about 25 MB,
   databases take about five times the amount of space that a flat text
   file with the same data would take. If you are going to run the
   regression tests you will temporarily need up to an extra 90 MB. Use
   the "df" command to check for disk space.
     _________________________________________________________________
   
                            If You Are Upgrading
                                      
   The internal data storage format changes with new releases of
   PostgreSQL. Therefore, if you are upgrading an existing installation
   that does not have a version number "7.3.x", you must back up and
   restore your data as shown here. These instructions assume that your
   existing installation is under the "/usr/local/pgsql" directory, and
   that the data area is in "/usr/local/pgsql/data". Substitute your
   paths appropriately.
    1. Make sure that your database is not updated during or after the
       backup. This does not affect the integrity of the backup, but the
       changed data would of course not be included. If necessary, edit
       the permissions in the file "/usr/local/pgsql/data/pg_hba.conf"
       (or equivalent) to disallow access from everyone except you.
    2. To back up your database installation, type:
pg_dumpall > outputfile
       If you need to preserve OIDs (such as when using them as foreign
       keys), then use the "-o" option when running "pg_dumpall".
       "pg_dumpall" does not save large objects. Check the
       Administrator's Guide if you need to do this.
       To make the backup, you can use the "pg_dumpall" command from the
       version you are currently running. For best results, however, try
       to use the "pg_dumpall" command from PostgreSQL 7.3.1, since this
       version contains bug fixes and improvements over older versions.
       While this advice might seem idiosyncratic since you haven't
       installed the new version yet, it is advisable to follow it if you
       plan to install the new version in parallel with the old version.
       In that case you can complete the installation normally and
       transfer the data later. This will also decrease the downtime.
    3. If you are installing the new version at the same location as the
       old one then shut down the old server, at the latest before you
       install the new files:
kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
       Versions prior to 7.0 do not have this "postmaster.pid" file. If
       you are using such a version you must find out the process id of
       the server yourself, for example by typing "ps ax | grep
       postmaster", and supply it to the "kill" command.
       On systems that have PostgreSQL started at boot time, there is
       probably a start-up file that will accomplish the same thing. For
       example, on a Red Hat Linux system one might find that
/etc/rc.d/init.d/postgresql stop
       works. Another possibility is "pg_ctl stop".
    4. If you are installing in the same place as the old version then it
       is also a good idea to move the old installation out of the way,
       in case you have trouble and need to revert to it. Use a command
       like this:
mv /usr/local/pgsql /usr/local/pgsql.old
       
   After you have installed PostgreSQL 7.3.1, create a new database
   directory and start the new server. Remember that you must execute
   these commands while logged in to the special database user account
   (which you already have if you are upgrading).
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

   Finally, restore your data with
/usr/local/pgsql/bin/psql -d template1 -f outputfile

   using the *new* psql.
   
   These topics are discussed at length in the Administrator's Guide,
   which you are encouraged to read in any case.
     _________________________________________________________________
   
                           Installation Procedure
                                      
    1. Configuration
       The first step of the installation procedure is to configure the
       source tree for your system and choose the options you would like.
       This is done by running the "configure" script. For a default
       installation simply enter
./configure
       This script will run a number of tests to guess values for various
       system dependent variables and detect some quirks of your
       operating system, and finally will create several files in the
       build tree to record what it found. (You can also run "configure"
       in a directory outside the source tree if you want to keep the
       build directory separate.)
       The default configuration will build the server and utilities, as
       well as all client applications and interfaces that require only a
       C compiler. All files will be installed under "/usr/local/pgsql"
       by default.
       You can customize the build and installation process by supplying
       one or more of the following command line options to "configure":
       
d257 8
a264 8
                Install all files under the directory "PREFIX" instead of
                "/usr/local/pgsql". The actual files will be installed
                into various subdirectories; no files will ever be
                installed directly into the "PREFIX" directory.
                
                If you have special needs, you can also customize the
                individual subdirectories with the following options.
                
d266 8
a273 9
                You can install architecture-dependent files under a
                different prefix, "EXEC-PREFIX", than what "PREFIX" was
                set to. This can be useful to share
                architecture-independent files between hosts. If you omit
                this, then "EXEC-PREFIX" is set equal to "PREFIX" and
                both architecture-dependent and independent files will be
                installed under the same tree, which is probably what you
                want.
                
d275 4
a278 4
                Specifies the directory for executable programs. The
                default is "EXEC-PREFIX/bin", which normally means
                "/usr/local/pgsql/bin".
                
d280 5
a284 5
                Sets the directory for read-only data files used by the
                installed programs. The default is "PREFIX/share". Note
                that this has nothing to do with where your database
                files will be placed.
                
d286 4
a289 3
                The directory for various configuration files,
                "PREFIX/etc" by default.
                
d291 4
a294 3
                The location to install libraries and dynamically
                loadable modules. The default is "EXEC-PREFIX/lib".
                
d296 4
a299 3
                The directory for installing C and C++ header files. The
                default is "PREFIX/include".
                
d301 4
a304 4
                Documentation files, except "man" pages, will be
                installed into this directory. The default is
                "PREFIX/doc".
                
d306 22
a327 21
                The man pages that come with PostgreSQL will be installed
                under this directory, in their respective "manx"
                subdirectories. The default is "PREFIX/man".
                
     Note: Care has been taken to make it possible to install PostgreSQL
     into shared installation locations (such as "/usr/local/include")
     without interfering with the namespace of the rest of the system.
     First, the string "/postgresql" is automatically appended to
     datadir, sysconfdir, and docdir, unless the fully expanded
     directory name already contains the string "postgres" or "pgsql".
     For example, if you choose "/usr/local" as prefix, the
     documentation will be installed in "/usr/local/doc/postgresql", but
     if the prefix is "/opt/postgres", then it will be in
     "/opt/postgres/doc". The public C header files of the client
     interfaces are installed into includedir and are namespace-clean.
     The internal header files and the server header files are installed
     into private directories under includedir. See the Programmer's
     Guide for information about how to get at the header files for each
     interface. Finally, a private subdirectory will also be created, if
     appropriate, under libdir for dynamically loadable modules.
       
d329 8
a336 10
                "DIRECTORIES" is a colon-separated list of directories
                that will be added to the list the compiler searches for
                header files. If you have optional packages (such as GNU
                Readline) installed in a non-standard location, you have
                to use this option and probably also the corresponding
                "--with-libraries" option.
                
                Example:
                --with-includes=/opt/gnu/include:/usr/sup/include.
                
d338 7
a344 7
                "DIRECTORIES" is a colon-separated list of directories to
                search for libraries. You will probably have to use this
                option (and the corresponding "--with-includes" option)
                if you have packages installed in non-standard locations.
                
                Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
                
d346 6
a351 6
                Enables single-byte character set recode support. See the
                Administrator's Guide about this feature. Note that a
                more general form of character set conversion is
                supported in the default configuration; this feature is
                obsolete.
                
d353 11
a363 12
                Enables Native Language Support (NLS), that is, the
                ability to display a program's messages in a language
                other than English. "LANGUAGES" is a space separated list
                of codes of the languages that you want supported, for
                example --enable-nls='de fr'. (The intersection between
                your list and the set of actually provided translations
                will be computed automatically.) If you do not specify a
                list, then all available translations are installed.
                
                To use this option, you will need an implementation of
                the gettext API; see above.
                
d365 8
a372 8
                Set "NUMBER" as the default port number for server and
                clients. The default is 5432. The port can always be
                changed later on, but if you specify it here then both
                server and clients will have the same default compiled
                in, which can be very convenient. Usually the only good
                reason to select a non-default value is if you intend to
                run multiple PostgreSQL servers on the same machine.
                
d374 3
a376 2
                Build the PL/Perl server-side language.
                
d378 5
a382 5
                Build the Python interface module and the PL/Python
                server-side language. You need to have root access to be
                able to install the Python module at its default place
                ("/usr/lib/pythonx.y").
                
d384 4
a387 4
                Build components that require Tcl/Tk, which are libpgtcl,
                pgtclsh, pgtksh, and PL/Tcl. But see below about
                "--without-tk".
                
d389 4
a392 3
                If you specify "--with-tcl" and this option, then the
                program that requires Tk (pgtksh) will be excluded.
                
d394 8
a401 8
                Tcl/Tk installs the files "tclConfig.sh" and
                "tkConfig.sh", which contain configuration information
                needed to build modules interfacing to Tcl or Tk. These
                files are normally found automatically at their
                well-known locations, but if you want to use a different
                version of Tcl or Tk you can specify the directory in
                which to find them.
                
d403 3
a405 2
                Build the JDBC driver and associated Java packages.
                
d407 14
a420 16
                Build with support for Kerberos authentication. You can
                use either Kerberos version 4 or 5, but not both. The
                "DIRECTORY" argument specifies the root directory of the
                Kerberos installation; "/usr/athena" is assumed as
                default. If the relevant header files and libraries are
                not under a common parent directory, then you must use
                the "--with-includes" and "--with-libraries" options in
                addition to this option. If, on the other hand, the
                required files are in a location that is searched by
                default (e.g., "/usr/lib"), then you can leave off the
                argument.
                
                "configure" will check for the required header files and
                libraries to make sure that your Kerberos installation is
                sufficient before proceeding.
                
d422 4
a425 3
                The name of the Kerberos service principal. postgres is
                the default. There's probably no reason to change this.
                
d427 9
a435 9
                Build with support for SSL (encrypted) connections. This
                requires the OpenSSL package to be installed. The
                "DIRECTORY" argument specifies the root directory of the
                OpenSSL installation; the default is "/usr/local/ssl".
                
                "configure" will check for the required header files and
                libraries to make sure that your OpenSSL installation is
                sufficient before proceeding.
                
d437 3
a439 3
                Build with PAM (Pluggable Authentication Modules)
                support.
                
d441 4
a444 4
                Prevents the use of the Readline library. This disables
                command-line editing and history in psql, so it is not
                recommended.
                
d446 5
a450 5
                Prevents the use of the Zlib library. This disables
                compression support in pg_dump. This option is only
                intended for those rare systems where this library is not
                available.
                
d452 12
a463 12
                Compiles all programs and libraries with debugging
                symbols. This means that you can run the programs through
                a debugger to analyze problems. This enlarges the size of
                the installed executables considerably, and on non-GCC
                compilers it usually also disables compiler optimization,
                causing slowdowns. However, having the symbols available
                is extremely helpful for dealing with any problems that
                may arise. Currently, this option is recommended for
                production installations only if you use GCC. But you
                should always have it on if you are doing development
                work or running a beta version.
                
d465 11
a475 12
                Enables assertion checks in the server, which test for
                many "can't happen" conditions. This is invaluable for
                code development purposes, but the tests slow things down
                a little. Also, having the tests turned on won't
                necessarily enhance the stability of your server! The
                assertion checks are not categorized for severity, and so
                what might be a relatively harmless bug will still lead
                to server restarts if it triggers an assertion failure.
                Currently, this option is not recommended for production
                use, but you should have it on for development work or
                when running a beta version.
                
d477 410
a886 352
                Enables automatic dependency tracking. With this option,
                the makefiles are set up so that all affected object
                files will be rebuilt when any header file is changed.
                This is useful if you are doing development work, but is
                just wasted overhead if you intend only to compile once
                and install. At present, this option will work only if
                you use GCC.
                
       If you prefer a C compiler different from the one "configure"
       picks then you can set the environment variable CC to the program
       of your choice. By default, "configure" will pick "gcc" unless
       this is inappropriate for the platform. Similarly, you can
       override the default compiler flags with the CFLAGS variable.
       You can specify environment variables on the "configure" command
       line, for example:
./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'
    2. Build
       To start the build, type
gmake
       (Remember to use GNU make.) The build may take anywhere from 5
       minutes to half an hour depending on your hardware. The last line
       displayed should be
All of PostgreSQL is successfully made. Ready to install.
    3. Regression Tests
       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. Type
gmake check
       (This won't work as root; do it as an unprivileged user.) It is
       possible that some tests fail, due to differences in error message
       wording or floating point results. The file
       "src/test/regress/README" and the Administrator's Guide contain
       detailed information about interpreting the test results. You can
       repeat this test at any later time by issuing the same command.
    4. Installing The Files
       
     Note: If you are upgrading an existing system and are going to
     install the new files over the old ones, then you should have
     backed up your data and shut down the old server by now, as
     explained in the section called If You Are Upgrading above.
       To install PostgreSQL enter
gmake install
       This will install files into the directories that were specified
       in step 1. Make sure that you have appropriate permissions to
       write into that area. Normally you need to do this step as root.
       Alternatively, you could create the target directories in advance
       and arrange for appropriate permissions to be granted.
       You can use gmake install-strip instead of gmake install to strip
       the executable files and libraries as they are installed. This
       will save some space. If you built with debugging support,
       stripping will effectively remove the debugging support, so it
       should only be done if debugging is no longer needed.
       install-strip tries to do a reasonable job saving space, but it
       does not have perfect knowledge of how to strip every unneeded
       byte from an executable file, so if you want to save all the disk
       space you possibly can, you will have to do manual work.
       If you built the Python interfaces and you were not the root user
       when you executed the above command then that part of the
       installation probably failed. In that case you should become the
       root user and then do
gmake -C src/interfaces/python install
       If you do not have superuser access you are on your own: you can
       still take the required files and place them in other directories
       where Python can find them, but how to do that is left as an
       exercise.
       The standard installation provides only the header files needed
       for client application development. If you plan to do any
       server-side program development (such as custom functions or data
       types written in C), then you may want to install the entire
       PostgreSQL include tree into your target include directory. To do
       that, enter
gmake install-all-headers
       This adds a megabyte or two to the installation footprint, and is
       only useful if you don't plan to keep the whole source tree around
       for reference. (If you do, you can just use the source's include
       directory when building server-side software.)
       Client-only installation: If you want to install only the client
       applications and interface libraries, then you can use these
       commands:
gmake -C src/bin install
gmake -C src/include install
gmake -C src/interfaces install
gmake -C doc install
       
   Uninstallation: To undo the installation use the command "gmake
   uninstall". However, this will not remove any created directories.
   
   Cleaning: After the installation you can make room by removing the
   built files from the source tree with the command "gmake clean". This
   will preserve the files made by the configure program, so that you can
   rebuild everything with "gmake" later on. To reset the source tree to
   the state in which it was distributed, use "gmake distclean". If you
   are going to build for several platforms from the same source tree you
   must do this and re-configure for each build.
   
   If you perform a build and then discover that your configure options
   were wrong, or if you change anything that configure investigates (for
   example, software upgrades), then it's a good idea to do "gmake
   distclean" before reconfiguring and rebuilding. Without this, your
   changes in configuration choices may not propagate everywhere they
   need to.
     _________________________________________________________________
   
                          Post-Installation Setup
                                      
                              Shared Libraries
                                      
   On some systems that have shared libraries (which most systems do) you
   need to tell your system how to find the newly installed shared
   libraries. The systems on which this is *not* necessary include
   BSD/OS, FreeBSD, HP-UX, IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX
   (formerly Digital UNIX), and Solaris.
   
   The method to set the shared library search path varies between
   platforms, but the most widely usable method is to set the environment
   variable LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh",
   "bash", "zsh")
LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH

   or in "csh" or "tcsh"
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

   Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in
   step 1. You should put these commands into a shell start-up file such
   as "/etc/profile" or "~/.bash_profile". Some good information about
   the caveats associated with this method can be found at
   http://www.visi.com/~barr/ldpath.html.
   
   On some systems it might be preferable to set the environment variable
   LD_RUN_PATH *before* building.
   
   On Cygwin, put the library directory in the PATH or move the ".dll"
   files into the "bin/" directory.
   
   If in doubt, refer to the manual pages of your system (perhaps "ld.so"
   or "rld"). 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 this step was necessary. Simply take care of it then.
   
   If you are on BSD/OS, Linux, or SunOS 4 and you have root access you
   can run
/sbin/ldconfig /usr/local/pgsql/lib

   (or equivalent directory) after installation to enable the run-time
   linker to find the shared libraries faster. Refer to the manual page
   of "ldconfig" for more information. On FreeBSD, NetBSD, and OpenBSD
   the command is
/sbin/ldconfig -m /usr/local/pgsql/lib

   instead. Other systems are not known to have an equivalent command.
     _________________________________________________________________
   
                           Environment Variables
                                      
   If you installed into "/usr/local/pgsql" or some other location that
   is not searched for programs by default, you should add
   "/usr/local/pgsql/bin" (or whatever you set "--bindir" to in step 1)
   into your PATH. Strictly speaking, this is not necessary, but it will
   make the use of PostgreSQL much more convenient.
   
   To do this, add the following to your shell start-up file, such as
   "~/.bash_profile" (or "/etc/profile", if you want it to affect every
   user):
PATH=/usr/local/pgsql/bin:$PATH
export PATH

   If you are using "csh" or "tcsh", then use this command:
set path = ( /usr/local/pgsql/bin $path )

   To enable your system to find the man documentation, you need to add a
   line like the following to a shell start-up file unless you installed
   into a location that is searched by default.
MANPATH=/usr/local/pgsql/man:$MANPATH
export MANPATH

   The environment variables PGHOST and PGPORT specify to client
   applications the host and port of the database server, overriding the
   compiled-in defaults. If you are going to run client applications
   remotely then it is convenient if every user that plans to use the
   database sets PGHOST. This is not required, however: the settings can
   be communicated via command line options to most client programs.
     _________________________________________________________________
   
                              Getting Started
                                      
   The following is a quick summary of how to get PostgreSQL up and
   running once installed. The Administrator's Guide contains more
   information.
    1. Create a user account for the PostgreSQL server. 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, but running the server as root is a
       security risk and will not work.
adduser postgres
    2. Create a database installation with the "initdb" command. To run
       "initdb" you must be logged in to your PostgreSQL server account.
       It will not work as root.
root# mkdir /usr/local/pgsql/data
root# chown postgres /usr/local/pgsql/data
root# su - postgres
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 server
       account can write to the directory (or create it, if it doesn't
       already exist) before starting "initdb", as illustrated here.
    3. 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 put the server in
       the background use something like
nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
    </dev/null >>server.log 2>&1 </dev/null &
       To stop a server running in the background you can type
kill `cat /usr/local/pgsql/data/postmaster.pid`
       In order to allow TCP/IP connections (rather than only Unix domain
       socket ones) you need to pass the "-i" option to "postmaster".
    4. Create a database:
createdb testdb
       Then enter
psql testdb
       to connect to that database. At the prompt you can enter SQL
       commands and start experimenting.
     _________________________________________________________________
   
                                 What Now?
                                      
     * The PostgreSQL distribution contains a comprehensive documentation
       set, which you should read sometime. After installation, the
       documentation can be accessed by pointing your browser to
       "/usr/local/pgsql/doc/html/index.html", unless you changed the
       installation directories.
       The Tutorial should be your first reading if you are completely
       new to SQL databases. If you are familiar with database concepts
       then you want to proceed with the Administrator's Guide, which
       contains information about how to set up the database server,
       database users, and authentication.
     * Usually, you will want to modify your computer so that it will
       automatically start the database server whenever it boots. Some
       suggestions for this are in the Administrator's Guide.
     * 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. This is also
       explained in the Administrator's Guide.
     _________________________________________________________________
   
                            Supported Platforms
                                      
   PostgreSQL has been verified by the developer community to work on the
   platforms listed below. A supported platform generally means that
   PostgreSQL builds and installs according to these instructions and
   that the regression tests pass.
   
     Note: If you are having problems with the installation on a
     supported platform, please write to <pgsql-bugs@@postgresql.org> or
     <pgsql-ports@@postgresql.org>, not to the people listed here.
     
   OS Processor Version Reported Remarks
   AIX RS6000 7.3 2002-11-12, Andreas Zeugswetter
   (<ZeugswetterA@@spardat.at>) see also doc/FAQ_AIX
   BSD/OS x86 7.3 2002-10-25, Bruce Momjian (<pgman@@candle.pha.pa.us>)
   4.2
   FreeBSD Alpha 7.3 2002-11-13, Chris Kings-Lynne
   (<chriskl@@familyhealth.com.au>)
   FreeBSD x86 7.3 2002-10-29, 3.3, Nigel J. Andrews
   (<nandrews@@investsystems.co.uk>), 4.7, Larry Rosenman
   (<ler@@lerctr.org>), 5.0, Sean Chittenden (<sean@@chittenden.org>)
   HP-UX PA-RISC 7.3 2002-10-28, 10.20 Tom Lane (<tgl@@sss.pgh.pa.us>),
   11.00, 11.11, 32 & 64 bit, Giles Lean (<giles@@nemeton.com.au>) gcc and
   cc; see also doc/FAQ_HPUX
   IRIX MIPS 7.3 2002-10-27, Ian Barwick (<barwick@@gmx.net>) Irix64 Komma
   6.5
   Linux Alpha 7.3 2002-10-28, Magnus Naeslund (<mag@@fbab.net>)
   2.4.19-pre6
   Linux armv4l 7.2 2001-12-10, Mark Knox (<segfault@@hardline.org>) 2.2.x
   Linux MIPS 7.2 2001-11-15, Hisao Shibuya (<shibuya@@alpha.or.jp>)
   2.0.x; Cobalt Qube2
   Linux PlayStation 2 7.3 2002-11-19, Permaine Cheung
   <pcheung@@redhat.com>) #undef HAS_TEST_AND_SET, remove slock_t typedef
   Linux PPC74xx 7.3 2002-10-26, Tom Lane (<tgl@@sss.pgh.pa.us>) bye
   2.2.18; Apple G3
   Linux S/390 7.3 2002-11-22, Permaine Cheung <pcheung@@redhat.com>) both
   s390 and s390x (32 and 64 bit)
   Linux Sparc 7.3 2002-10-26, Doug McNaught (<doug@@mcnaught.org>) 3.0
   Linux x86 7.3 2002-10-26, Alvaro Herrera (<alvherre@@dcc.uchile.cl>)
   2.4
   MacOS X PPC 7.3 2002-10-28, 10.1, Tom Lane (<tgl@@sss.pgh.pa.us>),
   10.2.1, Adam Witney (<awitney@@sghms.ac.uk>)
   NetBSD Alpha 7.2 2001-11-20, Thomas Thai (<tom@@minnesota.com>) 1.5W
   NetBSD arm32 7.3 2002-11-19, Patrick Welche (<prlw1@@newn.cam.ac.uk>)
   1.6
   NetBSD m68k 7.0 2000-04-10, Henry B. Hotz (<hotz@@jpl.nasa.gov>) Mac
   8xx
   NetBSD MIPS 7.2.1 2002-06-13, Warwick Hunter (<whunter@@agile.tv>)
   1.5.3
   NetBSD PPC 7.2 2001-11-28, Bill Studenmund (<wrstuden@@netbsd.org>) 1.5
   NetBSD Sparc 7.2 2001-12-03, Matthew Green (<mrg@@eterna.com.au>) 32-
   and 64-bit builds
   NetBSD VAX 7.1 2001-03-30, Tom I. Helbekkmo (<tih@@kpnQwest.no>) 1.5
   NetBSD x86 7.3 2002-11-14, Patrick Welche (<prlw1@@newn.cam.ac.uk>) 1.6
   OpenBSD Sparc 7.3 2002-11-17, Christopher Kings-Lynne
   (<chriskl@@familyhealth.com.au>) 3.2
   OpenBSD x86 7.3 2002-11-14, 3.1 Magnus Naeslund (<mag@@fbab.net>), 3.2
   Christopher Kings-Lynne (<chriskl@@familyhealth.com.au>)
   SCO OpenServer 5 x86 7.3.1 2002-12-11, Shibashish Satpathy
   (<shib@@postmark.net>) 5.0.4, gcc; see also doc/FAQ_SCO
   Solaris Sparc 7.3 2002-10-28, Andrew Sullivan
   (<andrew@@libertyrms.info>) Solaris 7 & 8; see also doc/FAQ_Solaris
   Solaris x86 7.3 2002-11-20, Martin Renters (<martin@@datafax.com>) 5.8;
   see also doc/FAQ_Solaris
   SunOS 4 Sparc 7.2 2001-12-04, Tatsuo Ishii (<t-ishii@@sra.co.jp>)
   Tru64 UNIX Alpha 7.3 2002-11-05, Alessio Bragadini
   (<alessio@@albourne.com>)
   UnixWare x86 7.3 2002-11-01, 7.1.3 Larry Rosenman (<ler@@lerctr.org>),
   7.1.1 and 7.1.2(8.0.0) Olivier Prenant (<ohp@@pyrenet.fr>) see also
   doc/FAQ_SCO
   Windows x86 7.3 2002-10-29, Dave Page (<dpage@@vale-housing.co.uk>),
   Jason Tishler (<jason@@tishler.net>) with Cygwin; see doc/FAQ_MSWIN
   Windows x86 7.3 2002-11-05, Dave Page (<dpage@@vale-housing.co.uk>)
   native is client-side only; see Administrator's Guide
   
   Unsupported Platforms: The following platforms are either known not to
   work, or they used to work in a previous release and we did not
   receive explicit confirmation of a successful test with version 7.3 at
   the time this list was compiled. We include these here to let you know
   that these platforms *could* be supported if given some attention.
   
   OS Processor Version Reported Remarks
   BeOS x86 7.2 2001-11-29, Cyril Velter (<cyril.velter@@libertysurf.fr>)
   needs updates to semaphore code
   DG/UX 5.4R4.11 m88k 6.3 1998-03-01, Brian E Gallew (<geek+@@cmu.edu>)
   no recent reports
   MkLinux DR1 PPC750 7.0 2001-04-03, Tatsuo Ishii (<t-ishii@@sra.co.jp>)
   7.1 needs OS update?
   NeXTSTEP x86 6.x 1998-03-01, David Wetzel (<dave@@turbocat.de>) bit rot
   suspected
   QNX 4 RTOS x86 7.2 2001-12-10, Bernd Tegge (<tegge@@repas-aeg.de>)
   needs updates to semaphore code; see also doc/FAQ_QNX4
   QNX RTOS v6 x86 7.2 2001-11-20, Igor Kovalenko
   (<Igor.Kovalenko@@motorola.com>) patches available in archives, but too
   late for 7.2
   System V R4 m88k 6.2.1 1998-03-01, Doug Winterburn
   (<dlw@@seavme.xroads.com>) needs new TAS spinlock code
   System V R4 MIPS 6.4 1998-10-28, Frank Ridderbusch
   (<ridderbusch.pad@@sni.de>) no recent reports
   Ultrix MIPS 7.1 2001-03-26 TAS spinlock code not detected
   Ultrix VAX 6.x 1998-03-01
@


1.88.2.3
log
@Fix release notes and installation instructions for 7.3.1 release.
@
text
@d2 234
a235 254
                     PostgreSQL Installation Instructions

This document describes the installation of PostgreSQL from the source code
distribution.

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

                                 Short Version

  ./configure
  gmake
  su
  gmake install
  adduser postgres
  mkdir /usr/local/pgsql/data
  chown postgres /usr/local/pgsql/data
  su - postgres
  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
  /usr/local/pgsql/bin/createdb test
  /usr/local/pgsql/bin/psql test

The long version is the rest of this document.

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

                                 Requirements

In general, a modern Unix-compatible platform should be able to run PostgreSQL.
The platforms that had received specific testing at the time of release are
listed in the Section called Supported Platforms below. In the "doc"
subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble.
The following software packages are required for building PostgreSQL:

    * GNU make is required; other make programs will *not* work. GNU make is
      often installed under the name "gmake"; this document will always refer
      to it by that name. (On some systems GNU make is the default tool with
      the name "make".) To test for GNU make enter

        gmake --version

      It is recommended to use version 3.76.1 or later.

    * You need an ISO/ANSI C compiler. Recent versions of GCC are
      recommendable, but PostgreSQL is known to build with a wide variety of
      compilers from different vendors.

    * gzip is needed to unpack the distribution in the first place. If you are
      reading this, you probably already got past that hurdle.

    * The GNU Readline library (for comfortable line editing and command
      history retrieval) will be used by default. If you don't want to use it
      then you must specify the "--without-readline" option for "configure".
      (On NetBSD, the "libedit" library is readline-compatible and is used if
      "libreadline" is not found.)

    * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
      packages. See the file "doc/FAQ_MSWIN" for details.

The following packages are optional. They are not required in the default
configuration, but they are needed when certain build options are enabled, as
explained below.

    * To build the server programming language PL/Perl you need a full Perl
      installation, including the "libperl" library and the header files. Since
      PL/Perl will be a shared library, the "libperl" library must be a shared
      library also on most platforms. This appears to be the default in recent
      Perl versions, but it was not in earlier versions, and in general it is
      the choice of whomever installed Perl at your site.
      If you don't have the shared library but you need one, a message like
      this will appear during the build to point out this fact:

        *** Cannot build PL/Perl because libperl is not a shared library.
        *** You might have to rebuild your Perl installation.  Refer to
        *** the documentation for details.

      (If you don't follow the on-screen output you will merely notice that the
      PL/Perl library object, "plperl.so" or similar, will not be installed.)
      If you see this, you will have to rebuild and install Perl manually to be
      able to build PL/Perl. During the configuration process for Perl, request
      a shared library.

    * To build the Python interface module or the PL/Python server programming
      language, you need a Python installation, including the header files.
      Since PL/Python will be a shared library, the "libpython" library must be
      a shared library also on most platforms. This is not the case in a
      default Python installation.
      If after building and installing you have a file called "plpython.so"
      (possibly a different extension), then everything went well. Otherwise
      you should have seen a notice like this flying by:

        *** Cannot build PL/Python because libpython is not a shared library.
        *** You might have to rebuild your Python installation.  Refer to
        *** the documentation for details.

      That means you have to rebuild (part of) your Python installation to
      supply this shared library.
      The catch is that the Python distribution or the Python maintainers do
      not provide any direct way to do this. The closest thing we can offer you
      is the information in Python FAQ 3.30. On some operating systems you
      don't really have to build a shared library, but then you will have to
      convince the PostgreSQL build system of this. Consult the "Makefile" in
      the "src/pl/plpython" directory for details.

    * If you want to build Tcl or Tk components (clients and the PL/Tcl
      language) you of course need a Tcl installation.

    * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
      special tool for building Java-based packages. It can be downloaded from
      the Ant web site.
      If you have several Java compilers installed, it depends on the Ant
      configuration which one gets used. Precompiled Ant distributions are
      typically set up to read a file ".antrc" in the current user's home
      directory for configuration. For example, to use a different JDK than the
      default, this may work:

        JAVA_HOME=/usr/local/sun-jdk1.3
        JAVACMD=$JAVA_HOME/bin/java

           Note: Do not try to build the driver by calling "ant" or even
           "javac" directly. This will not work. Run "gmake" normally as
           described below.

    * To enable Native Language Support (NLS), that is, the ability to display
      a program's messages in a language other than English, you need an
      implementation of the Gettext API. Some operating systems have this
      built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
      download an add-on package from here: http://www.postgresql.org/~petere/
      gettext.html. If you are using the gettext implementation in the GNU C
      library then you will additionally need the GNU Gettext package for some
      utility programs. For any of the other implementations you will not need
      it.

    * Kerberos, OpenSSL, or PAM, if you want to support authentication using
      these services.

If you are build from a CVS tree instead of using a released source package, or
if you want to do development, you also need the following packages:

    * Flex and Bison are needed to build a CVS checkout or if you changed the
      actual scanner and parser definition files. If you need them, be sure to
      get Flex 2.5.4 or later and Bison 1.50 or later. Other yacc programs can
      sometimes be used, but doing so requires extra effort and is not
      recommended. Other lex programs will definitely not work.

If you need to get a GNU package, you can find it at your local GNU mirror site
(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
gnu/.
Also check that you have sufficient disk space. You will need about 65 MB for
the source tree during compilation and about 15 MB for the installation
directory. An empty database cluster takes about 25 MB, databases take about
five times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need up
to an extra 90 MB. Use the "df" command to check for disk space.

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

                             If You Are Upgrading

The internal data storage format changes with new releases of PostgreSQL.
Therefore, if you are upgrading an existing installation that does not have a
version number "7.3.x", you must back up and restore your data as shown here.
These instructions assume that your existing installation is under the "/usr/
local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
Substitute your paths appropriately.

   1. Make sure that your database is not updated during or after the backup.
      This does not affect the integrity of the backup, but the changed data
      would of course not be included. If necessary, edit the permissions in
      the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
      access from everyone except you.

   2. To back up your database installation, type:

        pg_dumpall > outputfile

      If you need to preserve OIDs (such as when using them as foreign keys),
      then use the "-o" option when running "pg_dumpall".
      "pg_dumpall" does not save large objects. Check the Administrator's Guide
      if you need to do this.
      To make the backup, you can use the "pg_dumpall" command from the version
      you are currently running. For best results, however, try to use the
      "pg_dumpall" command from PostgreSQL 7.3.1, since this version contains
      bug fixes and improvements over older versions. While this advice might
      seem idiosyncratic since you haven't installed the new version yet, it is
      advisable to follow it if you plan to install the new version in parallel
      with the old version. In that case you can complete the installation
      normally and transfer the data later. This will also decrease the
      downtime.

   3. If you are installing the new version at the same location as the old one
      then shut down the old server, at the latest before you install the new
      files:

        kill -INT `cat /usr/local/pgsql/data/postmaster.pid`

      Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
      using such a version you must find out the process id of the server
      yourself, for example by typing "ps ax | grep postmaster", and supply it
      to the "kill" command.
      On systems that have PostgreSQL started at boot time, there is probably a
      start-up file that will accomplish the same thing. For example, on a Red
      Hat Linux system one might find that

        /etc/rc.d/init.d/postgresql stop

      works. Another possibility is "pg_ctl stop".

   4. If you are installing in the same place as the old version then it is
      also a good idea to move the old installation out of the way, in case you
      have trouble and need to revert to it. Use a command like this:

        mv /usr/local/pgsql /usr/local/pgsql.old

After you have installed PostgreSQL 7.3.1, create a new database directory and
start the new server. Remember that you must execute these commands while
logged in to the special database user account (which you already have if you
are upgrading).

  /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
  /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data

Finally, restore your data with

  /usr/local/pgsql/bin/psql -d template1 -f outputfile

using the *new* psql.
These topics are discussed at length in the Administrator's Guide, which you
are encouraged to read in any case.

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

                            Installation Procedure

   1. Configuration
      The first step of the installation procedure is to configure the source
      tree for your system and choose the options you would like. This is done
      by running the "configure" script. For a default installation simply
      enter

        ./configure

      This script will run a number of tests to guess values for various system
      dependent variables and detect some quirks of your operating system, and
      finally will create several files in the build tree to record what it
      found. (You can also run "configure" in a directory outside the source
      tree if you want to keep the build directory separate.)
      The default configuration will build the server and utilities, as well as
      all client applications and interfaces that require only a C compiler.
      All files will be installed under "/usr/local/pgsql" by default.
      You can customize the build and installation process by supplying one or
      more of the following command line options to "configure":

d237 8
a244 8

            Install all files under the directory "PREFIX" instead of "/usr/
            local/pgsql". The actual files will be installed into various
            subdirectories; no files will ever be installed directly into the
            "PREFIX" directory.
            If you have special needs, you can also customize the individual
            subdirectories with the following options.

d246 9
a254 8

            You can install architecture-dependent files under a different
            prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
            useful to share architecture-independent files between hosts. If
            you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
            architecture-dependent and independent files will be installed
            under the same tree, which is probably what you want.

d256 4
a259 4

            Specifies the directory for executable programs. The default is
            "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".

d261 5
a265 5

            Sets the directory for read-only data files used by the installed
            programs. The default is "PREFIX/share". Note that this has nothing
            to do with where your database files will be placed.

d267 3
a269 4

            The directory for various configuration files, "PREFIX/etc" by
            default.

d271 3
a273 4

            The location to install libraries and dynamically loadable modules.
            The default is "EXEC-PREFIX/lib".

d275 3
a277 4

            The directory for installing C and C++ header files. The default is
            "PREFIX/include".

d279 4
a282 4

            Documentation files, except "man" pages, will be installed into
            this directory. The default is "PREFIX/doc".

d284 21
a304 22

            The man pages that come with PostgreSQL will be installed under
            this directory, in their respective "manx" subdirectories. The
            default is "PREFIX/man".
           Note: Care has been taken to make it possible to install
           PostgreSQL into shared installation locations (such as "/usr/
           local/include") without interfering with the namespace of the
           rest of the system. First, the string "/postgresql" is
           automatically appended to datadir, sysconfdir, and docdir,
           unless the fully expanded directory name already contains the
           string "postgres" or "pgsql". For example, if you choose "/usr/
           local" as prefix, the documentation will be installed in "/usr/
           local/doc/postgresql", but if the prefix is "/opt/postgres",
           then it will be in "/opt/postgres/doc". The public C header
           files of the client interfaces are installed into includedir
           and are namespace-clean. The internal header files and the
           server header files are installed into private directories
           under includedir. See the Programmer's Guide for information
           about how to get at the header files for each interface.
           Finally, a private subdirectory will also be created, if
           appropriate, under libdir for dynamically loadable modules.

d306 10
a315 8

            "DIRECTORIES" is a colon-separated list of directories that will be
            added to the list the compiler searches for header files. If you
            have optional packages (such as GNU Readline) installed in a non-
            standard location, you have to use this option and probably also
            the corresponding "--with-libraries" option.
            Example: --with-includes=/opt/gnu/include:/usr/sup/include.

d317 7
a323 7

            "DIRECTORIES" is a colon-separated list of directories to search
            for libraries. You will probably have to use this option (and the
            corresponding "--with-includes" option) if you have packages
            installed in non-standard locations.
            Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.

d325 6
a330 6

            Enables single-byte character set recode support. See the
            Administrator's Guide about this feature. Note that a more general
            form of character set conversion is supported in the default
            configuration; this feature is obsolete.

d332 12
a343 11

            Enables Native Language Support (NLS), that is, the ability to
            display a program's messages in a language other than English.
            "LANGUAGES" is a space separated list of codes of the languages
            that you want supported, for example --enable-nls='de fr'. (The
            intersection between your list and the set of actually provided
            translations will be computed automatically.) If you do not specify
            a list, then all available translations are installed.
            To use this option, you will need an implementation of the gettext
            API; see above.

d345 8
a352 8

            Set "NUMBER" as the default port number for server and clients. The
            default is 5432. The port can always be changed later on, but if
            you specify it here then both server and clients will have the same
            default compiled in, which can be very convenient. Usually the only
            good reason to select a non-default value is if you intend to run
            multiple PostgreSQL servers on the same machine.

d354 2
a355 3

            Build the PL/Perl server-side language.

d357 5
a361 5

            Build the Python interface module and the PL/Python server-side
            language. You need to have root access to be able to install the
            Python module at its default place ("/usr/lib/pythonx.y").

d363 4
a366 4

            Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
            pgtksh, and PL/Tcl. But see below about "--without-tk".

d368 3
a370 4

            If you specify "--with-tcl" and this option, then the program that
            requires Tk (pgtksh) will be excluded.

d372 8
a379 8

            Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
            contain configuration information needed to build modules
            interfacing to Tcl or Tk. These files are normally found
            automatically at their well-known locations, but if you want to use
            a different version of Tcl or Tk you can specify the directory in
            which to find them.

d381 2
a382 3

            Build the JDBC driver and associated Java packages.

d384 16
a399 14

            Build with support for Kerberos authentication. You can use either
            Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
            specifies the root directory of the Kerberos installation; "/usr/
            athena" is assumed as default. If the relevant header files and
            libraries are not under a common parent directory, then you must
            use the "--with-includes" and "--with-libraries" options in
            addition to this option. If, on the other hand, the required files
            are in a location that is searched by default (e.g., "/usr/lib"),
            then you can leave off the argument.
            "configure" will check for the required header files and libraries
            to make sure that your Kerberos installation is sufficient before
            proceeding.

d401 3
a403 4

            The name of the Kerberos service principal. postgres is the
            default. There's probably no reason to change this.

d405 9
a413 9

            Build with support for SSL (encrypted) connections. This requires
            the OpenSSL package to be installed. The "DIRECTORY" argument
            specifies the root directory of the OpenSSL installation; the
            default is "/usr/local/ssl".
            "configure" will check for the required header files and libraries
            to make sure that your OpenSSL installation is sufficient before
            proceeding.

d415 3
a417 3

             Build with PAM (Pluggable Authentication Modules) support.

d419 4
a422 4

            Prevents the use of the Readline library. This disables command-
            line editing and history in psql, so it is not recommended.

d424 5
a428 5

            Prevents the use of the Zlib library. This disables compression
            support in pg_dump. This option is only intended for those rare
            systems where this library is not available.

d430 12
a441 12

            Compiles all programs and libraries with debugging symbols. This
            means that you can run the programs through a debugger to analyze
            problems. This enlarges the size of the installed executables
            considerably, and on non-GCC compilers it usually also disables
            compiler optimization, causing slowdowns. However, having the
            symbols available is extremely helpful for dealing with any
            problems that may arise. Currently, this option is recommended for
            production installations only if you use GCC. But you should always
            have it on if you are doing development work or running a beta
            version.

d443 12
a454 11

             Enables assertion checks in the server, which test for many "can't
            happen" conditions. This is invaluable for code development
            purposes, but the tests slow things down a little. Also, having the
            tests turned on won't necessarily enhance the stability of your
            server! The assertion checks are not categorized for severity, and
            so what might be a relatively harmless bug will still lead to
            server restarts if it triggers an assertion failure. Currently,
            this option is not recommended for production use, but you should
            have it on for development work or when running a beta version.

d456 352
a807 410

             Enables automatic dependency tracking. With this option, the
            makefiles are set up so that all affected object files will be
            rebuilt when any header file is changed. This is useful if you are
            doing development work, but is just wasted overhead if you intend
            only to compile once and install. At present, this option will work
            only if you use GCC.

      If you prefer a C compiler different from the one "configure" picks then
      you can set the environment variable CC to the program of your choice. By
      default, "configure" will pick "gcc" unless this is inappropriate for the
      platform. Similarly, you can override the default compiler flags with the
      CFLAGS variable.

      You can specify environment variables on the "configure" command line,
      for example:

        ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'

   2. Build
      To start the build, type

        gmake

      (Remember to use GNU make.) The build may take anywhere from 5 minutes to
      half an hour depending on your hardware. The last line displayed should
      be

        All of PostgreSQL is successfully made. Ready to install.

   3. Regression Tests
      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. Type

        gmake check

      (This won't work as root; do it as an unprivileged user.) It is possible
      that some tests fail, due to differences in error message wording or
      floating point results. The file "src/test/regress/README" and the
      Administrator's Guide contain detailed information about interpreting the
      test results. You can repeat this test at any later time by issuing the
      same command.

   4. Installing The Files
           Note: If you are upgrading an existing system and are going to
           install the new files over the old ones, then you should have
           backed up your data and shut down the old server by now, as
           explained in the Section called If You Are Upgrading above.
      To install PostgreSQL enter

        gmake install

      This will install files into the directories that were specified in step
      1. Make sure that you have appropriate permissions to write into that
      area. Normally you need to do this step as root. Alternatively, you could
      create the target directories in advance and arrange for appropriate
      permissions to be granted.
      You can use gmake install-strip instead of gmake install to strip the
      executable files and libraries as they are installed. This will save some
      space. If you built with debugging support, stripping will effectively
      remove the debugging support, so it should only be done if debugging is
      no longer needed. install-strip tries to do a reasonable job saving
      space, but it does not have perfect knowledge of how to strip every
      unneeded byte from an executable file, so if you want to save all the
      disk space you possibly can, you will have to do manual work.
      If you built the Python interfaces and you were not the root user when
      you executed the above command then that part of the installation
      probably failed. In that case you should become the root user and then do

        gmake -C src/interfaces/python install

      If you do not have superuser access you are on your own: you can still
      take the required files and place them in other directories where Python
      can find them, but how to do that is left as an exercise.
      The standard installation provides only the header files needed for
      client application development. If you plan to do any server-side program
      development (such as custom functions or data types written in C), then
      you may want to install the entire PostgreSQL include tree into your
      target include directory. To do that, enter

        gmake install-all-headers

      This adds a megabyte or two to the installation footprint, and is only
      useful if you don't plan to keep the whole source tree around for
      reference. (If you do, you can just use the source's include directory
      when building server-side software.)
      Client-only installation: If you want to install only the client
      applications and interface libraries, then you can use these commands:

        gmake -C src/bin install
        gmake -C src/include install
        gmake -C src/interfaces install
        gmake -C doc install

Uninstallation: To undo the installation use the command "gmake uninstall".
However, this will not remove any created directories.
Cleaning: After the installation you can make room by removing the built files
from the source tree with the command "gmake clean". This will preserve the
files made by the configure program, so that you can rebuild everything with
"gmake" later on. To reset the source tree to the state in which it was
distributed, use "gmake distclean". If you are going to build for several
platforms from the same source tree you must do this and re-configure for each
build.
If you perform a build and then discover that your configure options were
wrong, or if you change anything that configure investigates (for example,
software upgrades), then it's a good idea to do "gmake distclean" before
reconfiguring and rebuilding. Without this, your changes in configuration
choices may not propagate everywhere they need to.

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

                            Post-Installation Setup

Shared Libraries

On some systems that have shared libraries (which most systems do) you need to
tell your system how to find the newly installed shared libraries. The systems
on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
The method to set the shared library search path varies between platforms, but
the most widely usable method is to set the environment variable
LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh")

  LD_LIBRARY_PATH=/usr/local/pgsql/lib
  export LD_LIBRARY_PATH

or in "csh" or "tcsh"

  setenv LD_LIBRARY_PATH /usr/local/pgsql/lib

Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
should put these commands into a shell start-up file such as "/etc/profile" or
"~/.bash_profile". Some good information about the caveats associated with this
method can be found at http://www.visi.com/~barr/ldpath.html.
On some systems it might be preferable to set the environment variable
LD_RUN_PATH *before* building.
On Cygwin, put the library directory in the PATH or move the ".dll" files into
the "bin/" directory.
If in doubt, refer to the manual pages of your system (perhaps "ld.so" or
"rld"). 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 this step was necessary. Simply take care of it then.
If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run

  /sbin/ldconfig /usr/local/pgsql/lib

(or equivalent directory) after installation to enable the run-time linker to
find the shared libraries faster. Refer to the manual page of "ldconfig" for
more information. On FreeBSD, NetBSD, and OpenBSD the command is

  /sbin/ldconfig -m /usr/local/pgsql/lib

instead. Other systems are not known to have an equivalent command.

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

Environment Variables

If you installed into "/usr/local/pgsql" or some other location that is not
searched for programs by default, you should add "/usr/local/pgsql/bin" (or
whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
this is not necessary, but it will make the use of PostgreSQL much more
convenient.
To do this, add the following to your shell start-up file, such as
"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):

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

If you are using "csh" or "tcsh", then use this command:

  set path = ( /usr/local/pgsql/bin $path )

To enable your system to find the man documentation, you need to add a line
like the following to a shell start-up file unless you installed into a
location that is searched by default.

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

The environment variables PGHOST and PGPORT specify to client applications the
host and port of the database server, overriding the compiled-in defaults. If
you are going to run client applications remotely then it is convenient if
every user that plans to use the database sets PGHOST. This is not required,
however: the settings can be communicated via command line options to most
client programs.

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

                                Getting Started

The following is a quick summary of how to get PostgreSQL up and running once
installed. The Administrator's Guide contains more information.

   1. Create a user account for the PostgreSQL server. 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,
      but running the server as root is a security risk and will not work.

        adduser postgres

   2. Create a database installation with the "initdb" command. To run "initdb"
      you must be logged in to your PostgreSQL server account. It will not work
      as root.

        root# mkdir /usr/local/pgsql/data
        root# chown postgres /usr/local/pgsql/data
        root# su - postgres
        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 server account can write to the
      directory (or create it, if it doesn't already exist) before starting
      "initdb", as illustrated here.

   3. 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 put the server in the
      background use something like

        nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
            </dev/null >>server.log 2>&1 </dev/null &

      To stop a server running in the background you can type

        kill `cat /usr/local/pgsql/data/postmaster.pid`

      In order to allow TCP/IP connections (rather than only Unix domain socket
      ones) you need to pass the "-i" option to "postmaster".

   4. Create a database:

        createdb testdb

      Then enter

        psql testdb

      to connect to that database. At the prompt you can enter SQL commands and
      start experimenting.

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

                                   What Now?

    * The PostgreSQL distribution contains a comprehensive documentation set,
      which you should read sometime. After installation, the documentation can
      be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
      index.html", unless you changed the installation directories.
      The Tutorial should be your first reading if you are completely new to
      SQL databases. If you are familiar with database concepts then you want
      to proceed with the Administrator's Guide, which contains information
      about how to set up the database server, database users, and
      authentication.

    * Usually, you will want to modify your computer so that it will
      automatically start the database server whenever it boots. Some
      suggestions for this are in the Administrator's Guide.

    * 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. This is also explained in the
      Administrator's Guide.

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

                              Supported Platforms

PostgreSQL has been verified by the developer community to work on the
platforms listed below. A supported platform generally means that PostgreSQL
builds and installs according to these instructions and that the regression
tests pass.
     Note: If you are having problems with the installation on a supported
     platform, please write to <pgsql-bugs@@postgresql.org> or <pgsql-
     ports@@postgresql.org>, not to the people listed here.
 __________________________________________________________________________________
|OS________|Processor__|Version|Reported_________________________|Remarks__________|
|AIX       |RS6000     |7.3    |2002-11-12, Andreas Zeugswetter  |see also doc/    |
|__________|___________|_______|(<ZeugswetterA@@spardat.at>)______|FAQ_AIX__________|
|BSD/OS    |x86        |7.3    |2002-10-25, Bruce Momjian        |4.2              |
|__________|___________|_______|(<pgman@@candle.pha.pa.us>)_______|_________________|
|FreeBSD   |Alpha      |7.3    |2002-11-13, Chris Kings-Lynne    |                 |
|__________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|FreeBSD   |x86        |7.3    |2002-10-29, 3.3, Nigel J. Andrews|                 |
|          |           |       |(<nandrews@@investsystems.co.uk>),|                 |
|          |           |       |4.7, Larry Rosenman              |                 |
|          |           |       |(<ler@@lerctr.org>), 5.0, Sean    |                 |
|          |           |       |Chittenden                       |                 |
|__________|___________|_______|(<sean@@chittenden.org>)__________|_________________|
|HP-UX     |PA-RISC    |7.3    |2002-10-28, 10.20 Tom Lane       |gcc and cc; see  |
|          |           |       |(<tgl@@sss.pgh.pa.us>), 11.00,    |also doc/FAQ_HPUX|
|          |           |       |11.11, 32 & 64 bit, Giles Lean   |                 |
|__________|___________|_______|(<giles@@nemeton.com.au>)_________|_________________|
|IRIX      |MIPS       |7.3    |2002-10-27, Ian Barwick          |Irix64 Komma 6.5 |
|__________|___________|_______|(<barwick@@gmx.net>)______________|_________________|
|Linux     |Alpha      |7.3    |2002-10-28, Magnus Naeslund      |2.4.19-pre6      |
|__________|___________|_______|(<mag@@fbab.net>)_________________|_________________|
|Linux     |PlayStation|7.3    |2002-11-19, Permaine Cheung      |#undef           |
|          |2          |       |<pcheung@@redhat.com>)            |HAS_TEST_AND_SET,|
|          |           |       |                                 |remove slock_t   |
|__________|___________|_______|_________________________________|typedef__________|
|Linux     |PPC74xx    |7.3    |2002-10-26, Tom Lane             |bye 2.2.18; Apple|
|__________|___________|_______|(<tgl@@sss.pgh.pa.us>)____________|G3_______________|
|Linux     |S/390      |7.3    |2002-11-22, Permaine Cheung      |both s390 and    |
|          |           |       |<pcheung@@redhat.com>)            |s390x (32 and 64 |
|__________|___________|_______|_________________________________|bit)_____________|
|Linux     |Sparc      |7.3    |2002-10-26, Doug McNaught        |3.0              |
|__________|___________|_______|(<doug@@mcnaught.org>)____________|_________________|
|Linux     |x86        |7.3    |2002-10-26, Alvaro Herrera       |2.4              |
|__________|___________|_______|(<alvherre@@dcc.uchile.cl>)_______|_________________|
|MacOS X   |PPC        |7.3    |2002-10-28, 10.1, Tom Lane       |                 |
|          |           |       |(<tgl@@sss.pgh.pa.us>), 10.2.1,   |                 |
|          |           |       |Adam Witney                      |                 |
|__________|___________|_______|(<awitney@@sghms.ac.uk>)__________|_________________|
|NetBSD    |arm32      |7.3    |2002-11-19, Patrick Welche       |1.6              |
|__________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|NetBSD    |x86        |7.3    |2002-11-14, Patrick Welche       |1.6              |
|__________|___________|_______|(<prlw1@@newn.cam.ac.uk>)_________|_________________|
|OpenBSD   |Sparc      |7.3    |2002-11-17, Christopher Kings-   |3.2              |
|          |           |       |Lynne                            |                 |
|__________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|OpenBSD   |x86        |7.3    |2002-11-14, 3.1 Magnus Naeslund  |                 |
|          |           |       |(<mag@@fbab.net>), 3.2 Christopher|                 |
|          |           |       |Kings-Lynne                      |                 |
|__________|___________|_______|(<chriskl@@familyhealth.com.au>)__|_________________|
|SCO       |x86        |7.3.1  |2002-12-11, Shibashish Satpathy  |5.0.4, gcc; see  |
|OpenServer|           |       |(<shib@@postmark.net>)            |also doc/FAQ_SCO |
|5_________|___________|_______|_________________________________|_________________|
|Solaris   |Sparc      |7.3    |2002-10-28, Andrew Sullivan      |Solaris 7 & 8;   |
|          |           |       |(<andrew@@libertyrms.info>)       |see also doc/    |
|__________|___________|_______|_________________________________|FAQ_Solaris______|
|Solaris   |x86        |7.3    |2002-11-20, Martin Renters       |5.8; see also    |
|__________|___________|_______|(<martin@@datafax.com>)___________|doc/FAQ_Solaris__|
|Tru64 UNIX|Alpha      |7.3    |2002-11-05, Alessio Bragadini    |                 |
|__________|___________|_______|(<alessio@@albourne.com>)_________|_________________|
|UnixWare  |x86        |7.3    |2002-11-01, 7.1.3 Larry Rosenman |see also doc/    |
|          |           |       |(<ler@@lerctr.org>), 7.1.1 and    |FAQ_SCO          |
|          |           |       |7.1.2(8.0.0) Olivier Prenant     |                 |
|__________|___________|_______|(<ohp@@pyrenet.fr>)_______________|_________________|
|Windows   |x86        |7.3    |2002-10-29, Dave Page            |with Cygwin; see |
|          |           |       |(<dpage@@vale-housing.co.uk>),    |doc/FAQ_MSWIN    |
|          |           |       |Jason Tishler                    |                 |
|__________|___________|_______|(<jason@@tishler.net>)____________|_________________|
|Windows   |x86        |7.3    |2002-11-05, Dave Page            |native is client-|
|          |           |       |(<dpage@@vale-housing.co.uk>)     |side only; see   |
|          |           |       |                                 |Administrator's  |
|__________|___________|_______|_________________________________|Guide____________|

Unsupported Platforms: The following platforms are either known not to work, or
they used to work in a previous release and we did not receive explicit
confirmation of a successful test with version 7.3 at the time this list was
compiled. We include these here to let you know that these platforms *could* be
supported if given some attention.
 ____________________________________________________________________________
|OS_________|Processor|Version|Reported_______________________|Remarks_______|
|BeOS       |x86      |7.2    |2001-11-29, Cyril Velter       |needs updates |
|           |         |       |(<cyril.velter@@libertysurf.fr>)|to semaphore  |
|___________|_________|_______|_______________________________|code__________|
|DG/UX      |m88k     |6.3    |1998-03-01, Brian E Gallew     |no recent     |
|5.4R4.11___|_________|_______|(<geek+@@cmu.edu>)______________|reports_______|
|Linux      |armv4l   |7.2    |2001-12-10, Mark Knox          |2.2.x         |
|___________|_________|_______|(<segfault@@hardline.org>)______|______________|
|Linux      |MIPS     |7.2    |2001-11-15, Hisao Shibuya      |2.0.x; Cobalt |
|___________|_________|_______|(<shibuya@@alpha.or.jp>)________|Qube2_________|
|MkLinux DR1|PPC750   |7.0    |2001-04-03, Tatsuo Ishii (<t-  |7.1 needs OS  |
|___________|_________|_______|ishii@@sra.co.jp>)______________|update?_______|
|NetBSD     |Alpha    |7.2    |2001-11-20, Thomas Thai        |1.5W          |
|___________|_________|_______|(<tom@@minnesota.com>)__________|______________|
|NetBSD     |m68k     |7.0    |2000-04-10, Henry B. Hotz      |Mac 8xx       |
|___________|_________|_______|(<hotz@@jpl.nasa.gov>)__________|______________|
|NetBSD     |MIPS     |7.2.1  |2002-06-13, Warwick Hunter     |1.5.3         |
|___________|_________|_______|(<whunter@@agile.tv>)___________|______________|
|NetBSD     |PPC      |7.2    |2001-11-28, Bill Studenmund    |1.5           |
|___________|_________|_______|(<wrstuden@@netbsd.org>)________|______________|
|NetBSD     |Sparc    |7.2    |2001-12-03, Matthew Green      |32- and 64-bit|
|___________|_________|_______|(<mrg@@eterna.com.au>)__________|builds________|
|NetBSD     |VAX      |7.1    |2001-03-30, Tom I. Helbekkmo   |1.5           |
|___________|_________|_______|(<tih@@kpnQwest.no>)____________|______________|
|NeXTSTEP   |x86      |6.x    |1998-03-01, David Wetzel       |bit rot       |
|___________|_________|_______|(<dave@@turbocat.de>)___________|suspected_____|
|QNX 4 RTOS |x86      |7.2    |2001-12-10, Bernd Tegge        |needs updates |
|           |         |       |(<tegge@@repas-aeg.de>)         |to semaphore  |
|           |         |       |                               |code; see also|
|___________|_________|_______|_______________________________|doc/FAQ_QNX4__|
|QNX RTOS v6|x86      |7.2    |2001-11-20, Igor Kovalenko     |patches       |
|           |         |       |(<Igor.Kovalenko@@motorola.com>)|available in  |
|           |         |       |                               |archives, but |
|           |         |       |                               |too late for  |
|___________|_________|_______|_______________________________|7.2___________|
|SunOS 4    |Sparc    |7.2    |2001-12-04, Tatsuo Ishii (<t-  |              |
|___________|_________|_______|ishii@@sra.co.jp>)______________|______________|
|System V R4|m88k     |6.2.1  |1998-03-01, Doug Winterburn    |needs new TAS |
|___________|_________|_______|(<dlw@@seavme.xroads.com>)______|spinlock_code_|
|System V R4|MIPS     |6.4    |1998-10-28, Frank Ridderbusch  |no recent     |
|___________|_________|_______|(<ridderbusch.pad@@sni.de>)_____|reports_______|
|Ultrix     |MIPS     |7.1    |2001-03-26                     |TAS spinlock  |
|           |         |       |                               |code not      |
|___________|_________|_______|_______________________________|detected______|
|Ultrix_____|VAX______|6.x____|1998-03-01_____________________|______________|

@


1.88.2.4
log
@Stamp 7.3.4 release.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.4, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.4, create a new database directory and
@


1.88.2.5
log
@Brand 7.3.5.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.5, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.5, create a new database directory and
@


1.88.2.6
log
@Brand 7.3.6.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.6, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.6, create a new database directory and
@


1.88.2.7
log
@Stamp 7.3.7.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.7, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.7, create a new database directory and
@


1.88.2.8
log
@Stamp release 7.3.8.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.8, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.8, create a new database directory and
@


1.88.2.9
log
@Stamp release 7.3.9.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.9, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.9, create a new database directory and
@


1.88.2.10
log
@Stamp release 7.3.10.
@
text
@d185 1
a185 1
      "pg_dumpall" command from PostgreSQL 7.3.10, since this version contains
d217 1
a217 1
After you have installed PostgreSQL 7.3.10, create a new database directory and
@


1.88.2.11
log
@The release process is now generating HISTORY/INSTALL on the fly in
the 7.3 branch as well as later branches ... so no need to update
manually.
@
text
@@


1.87
log
@
Remove all traces of the ODBC driver, which is now on GBorg as the psqlodbc
project ...
@
text
@d61 1
a61 1
     them, be sure to get Flex 2.5.4 or later and Bison 1.28 or later. Other
@


1.86
log
@Rebuild from source.
@
text
@a323 4
     --with-CXX

          Build the C++ interface library.

a359 29

     --enable-odbc

          Build the ODBC driver. By default, the driver will be independent
          of a driver manager. To work better with a driver manager already
          installed on your system, use one of the following options in
          addition to this one. More information can be found in the
          Programmer's Guide.

     --with-iodbc

          Build the ODBC driver for use with iODBC.

     --with-unixodbc

          Build the ODBC driver for use with unixODBC.

     --with-odbcinst=DIRECTORY

          Specifies the directory where the ODBC driver will expect its
          "odbcinst.ini" configuration file. The default is
          "/usr/local/pgsql/etc" or whatever you specified as
          "--sysconfdir". It should be arranged that the driver reads the
          same file as the driver manager.

          If either the option "--with-iodbc" or the option
          "--with-unixodbc" is used, this option will be ignored because in
          that case the driver manager handles the location of the
          configuration file.
@


1.85
log
@Update from source
@
text
@d27 1
a27 1
PostgreSQL. The platforms that had received explicit testing at the time of
d41 1
a41 1
     If at all possible you should use version 3.76.1 or later.
d47 2
a48 1
   * gzip
d50 3
a52 3
   * The GNU Readline library for comfortable line editing and command
     history retrieval will automatically be used if found. You might wish
     to install it before proceeding, but it is not required. (On NetBSD,
d56 8
a63 7
   * Flex and Bison are *not* required when building from a released source
     package because the output files are pre-generated. You will need these
     programs only when building from a CVS tree or when the actual scanner
     and parser definition files were changed. If you need them, be sure to
     get Flex 2.5.4 or later and Bison 1.28 or later. Other yacc programs
     can sometimes be used, but doing so requires extra efforts and is not
     recommended. Other lex programs will definitely not work.
d101 5
a105 4
     If you need to preserve the OIDs (such as when using them as foreign
     keys), then use the "-o" option when running "pg_dumpall". "pg_dumpall"
     does not save large objects. Check the Administrator's Guide if you
     need to do this.
d128 1
a128 1
     works.
d132 1
a132 1
     you still need it later on. Use a command like this:
d169 2
a170 2
     system, and finally creates several files in the build tree to record
     what it found.
d173 1
a173 1
     as all client applications and interfaces that only require a C
d252 3
a254 3
          how to get at the header files for each interface. Finally, a
          private subdirectory will also be created, if appropriate,
          under libdir for dynamically loadable modules.
d261 2
a262 2
          non-standard location you have to use this option and probably the
          corresponding "--with-libraries" option.
d299 1
a299 1
          display a program's message in a language other than English.
d301 4
a304 4
          that you want supported. (The intersection between your list and
          the set of actually provided translations will be computed
          automatically.) If you do not specify it, then all available
          translations are installed.
d320 3
a322 1
          same default compiled in, which can be very convenient.
d358 6
a363 6
          Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh" which
          contain certain configuration information that is needed to build
          modules interfacing to Tcl or Tk. These files are normally found
          automatically at their well-known location, but if you want to use
          a different version of Tcl or Tk you can specify the directory
          where to find them.
d369 3
a371 2
          installed on your system, use one of the following options. More
          information can be found in the Programmer's Guide.
d394 8
a401 1
     --with-krb4=DIRECTORY, --with-krb5=DIRECTORY
d406 1
a406 1
          "/usr/athena" is assumed as default. If the relevant headers files
d422 1
a422 1
     --with-openssl=DIRECTORY
d433 1
a433 1
     --with-java
d435 1
a435 4
          Build the JDBC driver and associated Java packages. This option
          requires Ant to be installed (as well as a JDK, of course). Refer
          to the JDBC driver documentation in the Programmer's Guide for
          more information.
d442 1
a442 1
          to turn this option on at run time.)
d452 4
a455 3
          problems that may arise. Currently, this option is considered of
          marginal value for production installations, but you should have
          it on if you are doing development work or running a beta version.
d470 9
d480 1
a480 1
     picks then you can set the environment variables CC and CXX,
d485 1
a485 1
     env CC=/opt/bin/gcc CFLAGS='-02 -pipe' ./configure
d493 3
a495 2
     (Remember to use GNU make.) The build can take anywhere from 5 minutes
     to half an hour. The last line displayed should be
d518 1
a518 1
          to install the new files over the old ones then you should
d545 5
a549 5
     The standard install installs only the header files needed for client
     application development. If you plan to do any server-side program
     development (such as custom functions or data types written in C), then
     you may want to install the entire PostgreSQL include tree into your
     target include directory. To do that, enter
d558 1
a558 1
     Client-only installation. If you want to install only the client
d562 1
d567 1
a567 1
     this will not remove any directories.
d570 3
a572 3
the source tree with the "gmake clean" command. This will preserve the
choices made by the configure program, so that you can rebuild everything
with "gmake" later on. To reset the source tree to the state in which it was
d577 6
d609 1
a609 1
associated with the method can be found at
d641 2
a642 2
what you set "--bindir" to in step 1) into your PATH. To do this, add the
following to your shell start-up file, such as "~/.bash_profile" (or
d659 2
a660 2
convenient if every user that plans to use the database sets PGHOST, but it
is not required and the settings can be communicated via command line
d727 4
a730 3
   * The Tutorial should be your first reading if you are completely new to
     SQL databases. It should have been installed at
     "/usr/local/pgsql/doc/html/tutorial.html" unless you changed the
d733 5
a737 4
   * If you are familiar with database concepts then you want to proceed
     with the Administrator's Guide, which contains information about how to
     set up the database server, database users, and authentication. It can
     be found at "/usr/local/pgsql/doc/html/admin.html".
d761 10
a770 9
 OS       Processor Version Reported                               Remarks
 AIX 4.3.3RS6000    7.1     2001-03-21, Gilles Darold              see also
                            (<gilles@@darold.net>)                  doc/FAQ_AIX
 BeOS     x86       7.1     2001-02-26, Cyril Velter               requires new
 5.0.4                      (<cyril.velter@@libertysurf.fr>)        BONE networking
                                                                   stack
 BSD/OS   x86       7.1     2001-03-20, Bruce Momjian
 4.01                       (<pgman@@candle.pha.pa.us>)
 FreeBSD  x86       7.2     2001-11-14, Chris Kings-Lynne
d772 17
a788 22
 HP-UX    PA-RISC   7.2     2001-11-16, 10.20 Tom Lane             32- and 64-bit
                            (<tgl@@sss.pgh.pa.us>), 2001-03-22,     on 11.00; see
                            11.00, 11i Giles Lean                  also
                            (<giles@@nemeton.com.au>)               doc/FAQ_HPUX
 IRIX     MIPS      7.1     2001-03-22, Robert Bruccoleri          32-bit
 6.5.11                     (<bruc@@acm.org>)                       compilation
                                                                   model
 Linux    Alpha     7.2     2001-11-16, Tom Lane                   Tested at
 2.2.18                     (<tgl@@sss.pgh.pa.us>)                  SourceForge
 Linux    armv4l    7.1     2001-02-22, Mark Knox
 2.2.x                      (<segfault@@hardline.org>)
 Linux    MIPS      7.2     2001-11-15, Hisao Shibuya              Cobalt Qube2
 2.0.x                      (<shibuya@@alpha.or.jp>)
 Linux    PPC74xx   7.2     2001-11-16, Tom Lane                   Apple G3
 2.2.18                     (<tgl@@sss.pgh.pa.us>)
 Linux    S/390     7.1     2000-11-17, Neale Ferguson
                            (<Neale.Ferguson@@softwareAG-usa.com>)
 Linux    Sparc     7.1     2001-01-30, Ryan Kirkpatrick
 2.2.15                     (<pgsql@@rkirkpat.net>)
 Linux    x86       7.2     2001-11-15, Thomas Lockhart            2.0.x, 2.2.x,
                            (<lockhart@@fourpalms.org>)             2.4.x
 MacOS X  PPC       7.2     2001-11-16, Tom Lane                   Darwin 10.1
d790 13
a802 7
 NetBSD   Alpha     7.2     2001-11-20, Thomas Thai
 1.5W                       (<tom@@minnesota.com>)
 NetBSD   arm32     7.1     2001-03-21, Patrick Welche
 1.5E                       (<prlw1@@cam.ac.uk>)
 NetBSD   m68k      7.0     2000-04-10, Henry B. Hotz              Mac 8xx
                            (<hotz@@jpl.nasa.gov>)
 NetBSD   PPC       7.1     2001-04-05, Henry B. Hotz              Mac G4
d804 68
a871 65
 NetBSD   Sparc     7.1     2000-04-05, Matthew Green              32- and 64-bit
                            (<mrg@@eterna.com.au>)                  builds
 NetBSD   VAX       7.1     2001-03-30, Tom I. Helbekkmo
 1.5                        (<tih@@kpnQwest.no>)
 NetBSD   x86       7.1     2001-03-23, Giles Lean
 1.5                        (<giles@@nemeton.com.au>)
 OpenBSD  Sparc     7.1     2001-03-23, Brandon Palmer
 2.8                        (<bpalmer@@crimelabs.net>)
 OpenBSD  x86       7.1     2001-03-21, Brandon Palmer
 2.8                        (<bpalmer@@crimelabs.net>)
 SCO      x86       7.1     2001-03-19, Larry Rosenman             UDK FS compiler;
 UnixWare                   (<ler@@lerctr.org>)                     see also
 7.1.1                                                             doc/FAQ_SCO
 Solaris  Sparc     7.2     2001-11-12, Andrew Sullivan            2.6-8; see also
                            (<andrew@@libertyrms.com>)              doc/FAQ_Solaris
 Solaris  x86       7.1     2001-03-27, Mathijs Brands             see also
 2.8                        (<mathijs@@ilse.nl>)                    doc/FAQ_Solaris
 SunOS    Sparc     7.1     2001-03-23, Tatsuo Ishii
 4.1.4                      (<t-ishii@@sra.co.jp>)
 Tru64    Alpha     7.1     2001-03-26, Adriaan Joubert            4.0-5.0, cc and
 UNIX                       (<a.joubert@@albourne.com>)             gcc
 Windows  x86       7.1     2001-03-16, Jason Tishler              with Cygwin tool
 NT/2000                    (<Jason.Tishler@@dothill.com>)          set, see
 with                                                              doc/FAQ_MSWIN
 Cygwin

Unsupported Platforms. The following platforms have not been verified to
work. Platforms listed for version 6.3.x and later should also work with
7.2, but we did not receive explicit confirmation of such at the time this
list was compiled. We include these here to let you know that these
platforms *could* be supported if given some attention.

 OS          ProcessorVersion Reported                    Remarks
 DGUX        m88k     6.3     1998-03-01, Brian E Gallew  6.4 probably OK
 5.4R4.11                     (<geek+@@cmu.edu>)
 MkLinux DR1 PPC750   7.0     2001-04-03, Tatsuo Ishii    7.1 needs OS
                              (<t-ishii@@sra.co.jp>)       update?
 NextStep    x86      6.x     1998-03-01, David Wetzel    bit rot suspected
                              (<dave@@turbocat.de>)
 QNX 4.25    x86      7.0     2000-04-01, Dr. Andreas     Spinlock code
                              Kardos                      needs work. See
                              (<kardos@@repas-aeg.de>)     also
                                                          doc/FAQ_QNX4.
 SCO         x86      6.5     1999-05-25, Andrew Merrill  7.1 should work,
 OpenServer                   (<andrew@@compclass.com>)    but no reports;
 5                                                        see also
                                                          doc/FAQ_SCO
 System V R4 m88k     6.2.1   1998-03-01, Doug Winterburn needs new TAS
                              (<dlw@@seavme.xroads.com>)   spinlock code
 System V R4 MIPS     6.4     1998-10-28, Frank           no 64-bit integer
                              Ridderbusch
                              (<ridderbusch.pad@@sni.de>)
 Ultrix      MIPS     7.1     2001-03-26                  TAS spinlock code
                                                          not detected
 Ultrix      VAX      6.x     1998-03-01                  No recent
                                                          reports.
                                                          Obsolete?
 Windows 9x, x86      7.1     2001-03-26, Magnus Hagander client-side
 ME, NT,                      (<mha@@sollentuna.net>)      libraries (libpq
 2000                                                     and psql) or ODBC
 (native)                                                 or JDBC, no
                                                          server-side; see
                                                          Administrator's
                                                          Guide for
                                                          instructions
@


1.84
log
@Update docs for 7.2 mention where appropriate.
@
text
@d3 2
d9 1
d12 2
a19 1

d28 3
a30 3
release are listed in the section called Supported Platforms below. In the
doc subdirectory of the distribution there are several platform-specific FAQ
documents you might wish to consult if you are having trouble.
d34 4
a37 4
   * GNU make is required; other make programs will not work. GNU make is
     often installed under the name gmake; this document will always refer
     to it by that name. (On GNU/Linux systems GNU make is the default tool
     with the name make.) To test for GNU make enter
d52 2
a53 2
     the libedit library is readline-compatible and is used if libreadline
     is not found.)
d55 1
a55 1
   * Flex and Bison are not required when building from a released source
d64 1
a64 1
     packages. See the file doc/FAQ_MSWIN for details.
d71 6
a76 5
for the source tree during compilation and about 5 MB for the installation
directory. An empty database takes about 1 MB, later it takes about five
times the amount of space that a flat text file with the same data would
take. If you are going to run the regression tests you will temporarily need
an extra 20 MB. Use the df command to check for disk space.
d86 2
a87 2
/usr/local/pgsql directory, and that the data area is in
/usr/local/pgsql/data. Substitute your paths appropriately.
d92 2
a93 2
     the file /usr/local/pgsql/data/pg_hba.conf (or equivalent) to disallow
     access from everyone except you.
d100 3
a102 3
     keys), then use the -o option when running pg_dumpall. pg_dumpall does
     not save large objects. Check the Administrator's Guide if you need to
     do this.
d104 2
a105 2
     Make sure that you use the pg_dumpall command from the version you are
     currently running. 7.2's pg_dumpall should not be used on older
d114 4
a117 4
     Versions prior to 7.0 do not have this postmaster.pid file. If you are
     using such a version you must find out the process id of the server
     yourself, for example by typing ps ax | grep postmaster, and supply it
     to the kill command.
d145 1
a145 1
using the new psql.
d159 2
a160 2
     done by running the configure script. For a default installation simply
     enter
d171 1
a171 1
     compiler. All files will be installed under /usr/local/pgsql by
d175 1
a175 1
     or more of the following command line options to configure:
d179 4
a182 4
          Install all files under the directory PREFIX instead of
          /usr/local/pgsql. The actual files will be installed into various
          subdirectories; no files will ever be installed directly into the
          PREFIX directory.
d190 1
a190 1
          prefix, EXEC-PREFIX, than what PREFIX was set to. This can be
d192 3
a194 3
          you omit this, then EXEC-PREFIX is set equal to PREFIX and both
          architecture dependent and independent files will be installed
          under the same tree, which is probably what you want.
d199 1
a199 1
          EXEC-PREFIX/bin, which normally means /usr/local/pgsql/bin.
d204 2
a205 2
          programs. The default is PREFIX/share. Note that this has nothing
          to do with where your database files will be placed.
d209 1
a209 1
          The directory for various configuration files, PREFIX/etc by
d215 1
a215 1
          modules. The default is EXEC-PREFIX/lib.
d220 1
a220 1
          is PREFIX/include.
d225 1
a225 1
          this directory. The default is PREFIX/doc.
d230 2
a231 2
          this directory, in their respective manx subdirectories. The
          default is PREFIX/man.
d233 19
a251 9
          Note: To reduce the pollution of shared installation
          locations (such as /usr/local/include), the string
          "/postgresql" is automatically appended to datadir,
          sysconfdir, includedir, and docdir, unless the fully expanded
          directory name already contains the string "postgres" or
          "pgsql". For example, if you choose /usr/local as prefix, the
          C header files will be installed in
          /usr/local/include/postgresql, but if the prefix is
          /opt/postgres, then they will be in /opt/postgres/include.
d255 3
a257 3
          DIRECTORIES is a colon-separated list of directories that will be
          added to the list the compiler searches for header files. If you
          have optional packages (such as GNU Readline) installed in a
d259 1
a259 1
          corresponding --with-libraries option.
d265 3
a267 3
          DIRECTORIES is a colon-separated list of directories to search for
          libraries. You will probably have to use this option (and the
          corresponding --with-includes option) if you have packages
d285 2
a286 2
          Allows the use of multibyte character encodings. This is primarily
          for languages like Japanese, Korean, and Chinese. Read the
d289 23
d314 3
a316 3
          Set NUMBER as the default port number for server and clients. The
          default is 5432. The port can always be changed later on, but if
          you specify it here then both server and clients will have the
d327 1
a327 1
          /usr/lib/perl), so you must have root access to perform the
d335 2
a336 2
          (/usr/lib/pythonx.y). To be able to use this option, you must have
          Python installed and your system needs to support shared
d343 2
a344 2
          pgtclsh, pgtksh, pgaccess, and PL/Tcl. But see below about
          --without-tk.
d348 2
a349 2
          If you specify --with-tcl and this option, then programs that
          require Tk (i.e., pgtksh and pgaccess) will be excluded.
d353 1
a353 1
          Tcl/Tk installs the files tclConfig.sh and tkConfig.sh which
d362 12
a373 1
          Build the ODBC driver package.
d378 9
a386 5
          odbcinst.ini configuration file. The default is
          /usr/local/pgsql/etc or whatever you specified as --sysconfdir. A
          default file will be installed there. If you intend to share the
          odbcinst.ini file between several ODBC drivers then you may want
          to use this option.
d391 1
a391 1
          Kerberos version 4 or 5, but not both. The DIRECTORY argument
d393 1
a393 1
          /usr/athena is assumed as default. If the relevant headers files
d395 1
a395 1
          must use the --with-includes and --with-libraries options in
d397 1
a397 1
          are in a location that is searched by default (e.g., /usr/lib),
d400 1
a400 1
          configure will check for the required header files and libraries
d406 1
a406 1
          The name of the Kerberos service principal. "postgres" is the
d412 1
a412 1
          the OpenSSL package to be installed. The DIRECTORY argument
d414 1
a414 1
          default is /usr/local/ssl.
d416 1
a416 1
          configure will check for the required header files and libraries
d439 1
a439 1
          considerably, and on non-gcc compilers it usually also disables
d454 4
a457 4
          still lead to postmaster restarts if it triggers an assertion
          failure. Currently, this option is not recommended for production
          use, but you should have it on for development work or when
          running a beta version.
d459 1
a459 1
     If you prefer a C or C++ compiler different from the one configure
d487 6
a492 5
     It is possible that some tests fail, due to differences in error
     message wording or floating point results. The file
     src/test/regress/README and the Administrator's Guide contain detailed
     information about interpreting the test results. You can repeat this
     test at any later time by issuing the same command.
d499 1
a499 1
          as explained in the section called If You Are Upgrading
d520 3
a522 6
     Due to a quirk in the Perl build environment the first command will
     actually rebuild the complete interface and then install it. This is
     not harmful, just unusual. If you do not have superuser access you are
     on your own: you can still take the required files and place them in
     other directories where Perl or Python can find them, but how to do
     that is left as an exercise.
d526 1
a526 1
     development (such as custom functions or datatypes written in C), then
d532 1
a532 1
     This adds a megabyte or two to the install footprint, and is only
d544 2
a545 3
     To undo the installation use the command gmake uninstall. However, this
     will not remove the Perl and Python interfaces and it will not remove
     any directories.
d548 6
a553 5
the source tree with the gmake clean command. This will preserve the choices
made by the configure program, so that you can rebuild everything with gmake
later on. To reset the source tree to the state in which it was distributed,
use gmake distclean. If you are going to build for several platforms from
the same source tree you must do this and re-configure for each build.
d563 3
a565 2
systems on which this is not necessary include FreeBSD, HP/UX, Irix, Linux,
NetBSD, OpenBSD, OSF/1 (Digital Unix, Tru64 UNIX), and Solaris.
d569 1
a569 1
LD_LIBRARY_PATH like so: In Bourne shells (sh, ksh, bash, zsh)
d574 1
a574 1
or in csh or tcsh
d578 1
a578 1
Replace /usr/local/pgsql/lib with whatever you set --libdir to in step 1.
d580 1
a580 1
/etc/profile or ~/.bash_profile. Some good information about the caveats
d585 1
a585 1
LD_RUN_PATH before building.
d587 2
a588 2
If in doubt, refer to the manual pages of your system (perhaps ld.so or
rld). If you later on get a message like
d595 12
d611 5
a615 5
If you installed into /usr/local/pgsql or some other location that is not
searched for programs by default, you need to add /usr/local/pgsql/bin (or
what you set --bindir to in step 1) into your PATH. To do this, add the
following to your shell start-up file, such as ~/.bash_profile (or
/etc/profile, if you want it to affect every user):
d617 1
a617 1
PATH=$PATH:/usr/local/pgsql/bin
d619 1
a619 1
If you are using csh or tcsh, then use this command:
d621 1
a621 1
set path = ( /usr/local/pgsql/bin path )
d626 1
a626 1
MANPATH=$MANPATH:/usr/local/pgsql/man
d651 3
a653 3
  2. Create a database installation with the initdb command. To run initdb
     you must be logged in to your PostgreSQL server account. It will not
     work as root.
d660 2
a661 2
     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
d664 1
a664 1
     before starting initdb, as illustrated here.
d682 1
a682 1
     socket ones) you need to pass the -i option to postmaster.
d701 1
a701 1
     /usr/local/pgsql/doc/html/tutorial.html unless you changed the
d707 1
a707 1
     be found at /usr/local/pgsql/doc/html/admin.html.
d739 3
a741 6
 Compaq   Alpha     7.1     2001-03-26, Adriaan Joubert            4.0-5.0, cc and
 Tru64                      (<a.joubert@@albourne.com>)             gcc
 UNIX
 FreeBSD  x86       7.1     2001-03-19, Vince Vielhaber
 4.3                        (<vev@@hub.org>)
 HP/UX    PA-RISC   7.1     2001-03-19, 10.20 Tom Lane             32- and 64-bit
d748 2
a749 2
 Linux    Alpha     7.1     2001-01-23, Ryan Kirkpatrick
 2.2.x                      (<pgsql@@rkirkpat.net>)
d752 3
a754 3
 Linux    MIPS      7.1     2001-03-30, Dominic Eidson             Cobalt Qube
 2.0.x                      (<sauron@@the-infinite.org>)
 Linux    PPC74xx   7.1     2001-03-19, Tom Lane                   Apple G3
d760 6
a765 7
 Linux    x86       7.1     2001-03-19, Thomas Lockhart            2.0.x, 2.2.x,
                            (<thomas@@fourpalms.org>)               2.4.2
 MacOS X  PPC       7.1     2000-12-11, Peter Bierman              Darwin (only)
                            (<bierman@@apple.com>), 2000-12-11,     Beta-2 or higher
                            Daniel Luke (<dluke@@geeklair.net>)
 NetBSD   Alpha     7.1     2001-03-22, Giles Lean
 1.5                        (<giles@@nemeton.com.au>)
d785 2
a786 3
 Solaris  Sparc     7.1     2001-03-22, Marc Fournier              see also
 2.7-8                      (<scrappy@@hub.org>), 2001-03-25,       doc/FAQ_Solaris
                            Justin Clift (<justin@@postgresql.org>)
d791 4
a794 2
 Windows  x86       7.1     2001-03-16, Jason Tishler              with Cygwin
 NT/2000                    (<Jason.Tishler@@dothill.com>)          toolset, see
d802 1
a802 1
platforms could be supported if given some attention.
d804 2
a805 2
 OS          Processor VersionReported                     Remarks
 DGUX        m88k      6.3    1998-03-01, Brian E Gallew   6.4 probably OK
d807 16
a822 16
 MkLinux DR1 PPC750    7.0    2001-04-03, Tatsuo Ishii     7.1 needs OS
                              (<t-ishii@@sra.co.jp>)        update?
 NextStep    x86       6.x    1998-03-01, David Wetzel     bit rot
                              (<dave@@turbocat.de>)         suspected
 QNX 4.25    x86       7.0    2000-04-01, Dr. Andreas      Spinlock code
                              Kardos                       needs work. See
                              (<kardos@@repas-aeg.de>)      also
                                                           doc/FAQ_QNX4.
 SCO         x86       6.5    1999-05-25, Andrew Merrill   7.1 should work,
 OpenServer                   (<andrew@@compclass.com>)     but no reports;
 5                                                         see also
                                                           doc/FAQ_SCO
 System V R4 m88k      6.2.1  1998-03-01, Doug Winterburn  needs new TAS
                              (<dlw@@seavme.xroads.com>)    spinlock code
 System V R4 MIPS      6.4    1998-10-28, Frank            no 64-bit
                              Ridderbusch                  integer
d824 13
a836 14
 Ultrix      MIPS      7.1    2001-03-26                   TAS spinlock
                                                           code not
                                                           detected
 Ultrix      VAX       6.x    1998-03-01                   No recent
                                                           reports.
                                                           Obsolete?
 Windows 9x, x86       7.1    2001-03-26, Magnus Hagander  client-side
 ME, NT,                      (<mha@@sollentuna.net>)       libraries (libpq
 2000                                                      and psql) or
 (native)                                                  ODBC/JDBC, no
                                                           server-side; see
                                                           Administrator's
                                                           Guide for
                                                           instructions
@


1.83
log
@Revert wrong SCO OpenServer report, update comments and improve formatting
a bit.  Regenerate INSTALL.
@
text
@d79 1
a79 1
a version number "7.1.x", you must back up and restore your data as shown
d100 1
a100 1
     currently running. 7.1's pg_dumpall should not be used on older
d128 1
a128 1
After you have installed PostgreSQL 7.1, create a new database directory and
d739 1
a739 1
7.1, but we did not receive explicit confirmation of such at the time this
@


1.82
log
@Adjust file names.
@
text
@d1 1
a1 11
PostgreSQL Installation Instructions

Table of Contents
Short Version
Requirements
If You Are Upgrading
Installation Procedure
Post-Installation Setup
Getting Started
What Now?
Supported Platforms
d15 1
d47 3
a49 1
     to install it before proceeding, but it is not required.
d95 3
a97 1
     keys), then use the -o option when running pg_dumpall.
d100 1
a100 1
     currently running. 7.1devel's pg_dumpall should not be used on older
d114 3
a116 3
     On systems which have PostgreSQL started at boot time, there is
     probably a start-up file that will accomplish the same thing. For
     example, on a Red Hat Linux system one might find that
d128 4
a131 4
After you have installed PostgreSQL 7.1devel, create a new database
directory and start the new server. Remember that you must execute these
commands while logged in to the special database user account (which you
already have if you are upgrading).
d367 7
d385 20
a404 1
          problems. This option is not recommended for production use.
d473 13
d487 1
a487 1
     applications and interfaces, then you can use these commands:
d637 1
a637 1
     /usr/local/pgsql/doc/html/tutorial.htm unless you changed the
d643 1
a643 1
     be found at /usr/local/pgsql/doc/html/admin.htm.
d667 69
a735 57
 OS           Processor Version Reported                            Remarks
 AIX 4.3.2    RS6000    7.0     2000-04-05, Andread Zeugswetter     See also
                                (<Andreas.Zeugswetter@@telecom.at>)  doc/FAQ_AIX
 BSDI 4.01    x86       7.0     2000-04-04, Bruce Momjian
                                (<pgman@@candle.pha.pa.us>)
 Compaq Tru64 Alpha     7.0     2000-04-11, Andrew McMurry
 5.0                            (<andrew.mcmurry@@astro.uio.no>)
 FreeBSD 4.0  x86       7.0     2000-04-04, Marc Fournier
                                (<scrappy@@hub.org>)
 HPUX 9.0x andPA-RISC   7.0     2000-04-12, Tom Lane                See also
 10.20                          (<tgl@@sss.pgh.pa.us>)               doc/FAQ_HPUX
 IRIX 6.5.6f  MIPS      6.5.3   2000-02-18, Kevin Wheatley          MIPSPro
                                (<hxpro@@cinesite.co.uk>)            7.3.1.1m N32
                                                                    build
 Linux 2.0.x  Alpha     7.0     2000-04-05, Ryan Kirkpatrick        with published
                                (<pgsql@@rkirkpat.net>)              patches
 Linux 2.2.x  armv4l    7.0     2000-04-17, Mark Knox               Regression
                                (<segfault@@hardline.org>)           test needs
                                                                    work.
 Linux 2.2.x  x86       7.0     2000-03-26, Lamar Owen
                                (<lamar.owen@@wgcr.org>)
 Linux 2.0.x  MIPS      7.0     2000-04-13, Tatsuo Ishii            Cobalt Qube
                                (<t-ishii@@sra.co.jp>)
 Linux 2.2.5  Sparc     7.0     2000-04-02, Tom Szybist
                                (<szybist@@boxhill.com>)
 LinuxPPC R4  PPC603e   7.0     2000-04-13, Tatsuo Ishii
                                (<t-ishii@@sra.co.jp>)
 mklinux      PPC750    7.0     2000-04-13, Tatsuo Ishii
                                (<t-ishii@@sra.co.jp>)
 NetBSD 1.4   arm32     7.0     2000-04-08, Patrick Welche
                                (<prlw1@@newn.cam.ac.uk>)
 NetBSD 1.4U  x86       7.0     2000-03-26, Patrick Welche
                                (<prlw1@@newn.cam.ac.uk>)
 NetBSD       m68k      7.0     2000-04-10, Henry B. Hotz           Mac 8xx
                                (<hotz@@jpl.nasa.gov>)
 NetBSD       Sparc     7.0     2000-04-13, Tom I. Helbekkmo
                                (<tih@@kpnQwest.no>)
 QNX 4.25     x86       7.0     2000-04-01, Dr. Andreas Kardos      See also
                                (<kardos@@repas-aeg.de>)             doc/FAQ_QNX4
 SCO          x86       6.5     1999-05-25, Andrew Merrill          See also
 OpenServer 5                   (<andrew@@compclass.com>)            doc/FAQ_SCO
 SCO UnixWare x86       7.0     2000-04-18, Billy G. Allie          See also
 7                              (<Bill.Allie@@mug.org>)              doc/FAQ_SCO
 Solaris      x86       7.0     2000-04-12, Marc Fournier
                                (<scrappy@@hub.org>)
 Solaris      Sparc     7.0     2000-04-12, Peter Eisentraut
 2.5.1-2.7                      (<peter_e@@gmx.net>), Marc Fournier
                                (<scrappy@@hub.org>)
 SunOS 4.1.4  Sparc     7.0     2000-04-13, Tatsuo Ishii
                                (<t-ishii@@sra.co.jp>)
 Windows/Win32x86       7.0     2000-04-02, Magnus Hagander         Client-side
                                (<mha@@sollentuna.net>)              libraries or
                                                                    ODBC/JDBC, no
                                                                    server-side
 WinNT/Cygwin x86       7.0     2000-03-30, Daniel Horak            with
                                (<horak@@sit.plzen-city.cz>)         RedHat/Cygnus
                                                                    Cygwin toolset
d739 2
a740 2
7.1devel, but we did not receive explicit confirmation of such at the time
this list was compiled. We include these here to let you know that these
d743 34
a776 20
 OS        Processor Version Reported                        Remarks
 BeOS      x86       7.0     2000-05-01, Adam Haberlach      Client-side
                             (<adam@@newsnipple.com>)         coming soon?
 DGUX      m88k      6.3     1998-03-01, Brian E Gallew      6.4 probably
 5.4R4.11                    (<geek+@@cmu.edu>)               OK. Needs new
                                                             maintainer.
 NetBSD 1.3VAX       6.3     1998-03-01, Tom I Helbekkmo     7.0 should
                             (<tih@@kpnQwest.no>)             work.
 System V  m88k      6.2.1   1998-03-01, Doug Winterburn     Needs new TAS
 R4 4.4                      (<dlw@@seavme.xroads.com>)       spinlock code
 System V  MIPS      6.4     1998-10-28, Frank Ridderbusch   No 64-bit
 R4                          (<ridderbusch.pad@@sni.de>)      integer
 Ultrix    MIPS, VAX 6.x     1998-03-01                      No recent
                                                             reports.
                                                             Obsolete?
 MacOS     all       6.x     1998-03-01                      Not library
                                                             compatible;
                                                             use ODBC/JDBC.
 NextStep  x86       6.x     1998-03-01, David Wetzel        Client-only
                             (<dave@@turbocat.de>)            support
@


1.81
log
@Minor tweaks in installation instructions, regenerate INSTALL file.
@
text
@d603 1
a603 1
     /usr/local/pgsql/doc/tutorial/index.html unless you changed the
d609 1
a609 1
     be found at /usr/local/pgsql/doc/admin/index.html.
@


1.80
log
@Update installation instructions to new realities. Combined into one file.
Improved automation of INSTALL file generation.
@
text
@d37 42
a78 21
Compiler. You need a Standard ("ANSI") C compiler. Recent versions of GCC
are recommendable, but PostgreSQL is known to build with a wide variety of
compilers from different vendors.

Make. Building PostgreSQL requires GNU make; it will not work with other
make programs. GNU make is often installed under the name gmake. This
document will always refer to it by that name. (On GNU/Linux systems GNU
make is the default tool with the name make.) To test for GNU make enter

gmake --version

If at all possible you should try to use version 3.76.1 or later. If you
need to get GNU make, you can find it at your local GNU mirror site (see
http://www.gnu.org/order/ftp.html) or at ftp://ftp.gnu.org/gnu/make.

Resources. Check that you have sufficient disk space. You will need about 30
MB for the source tree during compilation and about 5 MB for the
installation directory. An empty database takes about 1 MB, later it takes
about five times the amount of space that a flat text file with the same
data would take. If you are going to run the regression tests you will
temporarily need an extra 20 MB. Use the df command to check for disk space.
d101 1
a101 1
     If you need to preserve the oids (such as when using them as foreign
d105 1
a105 1
     currently running. 7.1's pg_dumpall should not be used on older
d120 2
a121 2
     probably a startup file that will accomplish the same thing. For
     example, on a Redhat Linux system one might find that
d123 1
a123 1
     /etc/rc.d/init.d/postgres.init stop
d133 4
a136 4
After you have installed PostgreSQL 7.1, create a new database directory and
start the new server. Remember that you must execute these commands while
logged in to the special database user account (which you already have if
you are upgrading).
d138 2
a139 2
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/bin
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/bin
d148 2
a149 3
decrease the downtime. These topic are discussed at length in the
Administrator's Guide, which you are encouraged to read in any case. The
pg_upgrade utility can also often be used.
d157 1
a157 1
     The first step of the installation procedure to configure the source
d159 2
a160 2
     done by running the configure script. For a default installation,
     simply type
d174 2
a175 2
     You can customize the build and installation process by giving one or
     more of the following command line options to configure:
d230 12
a241 2
          this directory, in their respective manx subdirectories.
          PREFIX/man.
d270 2
a271 2
          Enables character set recode support. See doc/README.Charsets for
          details on this feature.
d276 2
a277 2
          for languages like Japanese, Korean, and Chinese. Read
          doc/README.mb for details.
d288 1
a288 4
          Build the C++ interface library. configure will automatically pick
          the C++ compiler that goes with the C compiler you are using. It
          is not recommended or supported to use C and C++ compilers of
          different origin in the same build.
d309 3
a311 2
          Builds components that require Tcl, which are libpgtcl, pgtclsh,
          and PL/Tcl.
d313 1
a313 1
     --with-x
d315 2
a316 3
          Use the X Window System. If you specified --with-tcl then this
          will enable the build of modules requiring Tcl/Tk, that is, pgtksh
          and pgaccess.
d336 3
a338 1
          default file will be installed there.
d342 9
a350 9
          Build with suppport for Kerberos authentication. You can use
          either Kerberos version 4 or 5, but not both. The DIRECTORY
          argument specifies the root directory of the Kerberos
          installation; /usr/athena is assumed as default. If the relevant
          headers files and libraries are not under a common parent
          directory, then you must use the --with-includes and
          --with-libraries options in addition to this option. If, on the
          other hand, the required files are in a location that is searched
          by default (e.g., /usr/lib), then you can leave off the argument.
d361 6
a366 1
     --with-krb-srvtab=FILE
d368 3
a370 5
          Specifies the location of the Kerberos server shared key file
          ("srvtab"). If you are using Kerberos 4, this defaults to
          /etc/srvtab, with Kerberos 5 to
          FILE:/usr/local/pgsql/etc/krb5.keytab, or equivalent, depending on
          what you set --sysconfdir to above.
d375 3
a377 3
          (Using this option does not mean that you have to log with syslog
          or even that it will be done by default, it simply makes it
          possible to turn this option on at run time.)
d385 5
a389 3
     Environment variables. You can set the CC environment variable to
     choose the C compiler to use. If you don't then configure will look for
     one. For example:
d391 1
a391 1
     CC=/opt/bin/gcc ./configure
d411 1
a411 1
     gmake -C src/test/regress all runcheck
d463 6
a468 7
Cleanup. After the installation you can make room by removing the built
files from the source tree with the gmake clean command. This will preserve
the choices made by the configure program, so that you can rebuild
everything with gmake later on. To reset the source tree to the state in
which it was distributed, use gmake distclean. If you are going to build for
several platforms from the same source tree you must do this and
re-configure for each build.
d476 8
a483 5
On most systems that have shared libraries (which most systems do) you need
to tell your system how to find the newly installed shared libraries. How to
do this varies between platforms, but the most widely usable method is to
set the environment variable LD_LIBRARY_PATH like so: In Bourne shells (sh,
ksh, bash, zsh)
d493 4
a496 7
You should put these commands into a shell startup file such as /etc/profile
or ~/.bash_profile.

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

/usr/local/pgsql/lib
d498 2
a499 1
Then run command /sbin/ldconfig.
d501 2
a502 2
If in doubt, refer to the manual pages of your system. If you later on get a
message like
d516 1
a516 1
following to your shell startup file, such as ~/.bash_profile (or
d526 1
a526 1
like the following to a shell startup file:
d544 6
a549 6
  1. Create the PostgreSQL server 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, but
     running the server as root is a security risk and therefore not
     allowed.
d581 1
a581 1
     kill `cat /usr/local/psgql/data/postmaster.pid`
d624 4
a627 4
At the time of release, PostgreSQL 7.1 has been verified by the developer
community to work on the following platforms. A supported platform generally
means that PostgreSQL builds and installs according to these instructions
and that the regression tests pass, except for minor differences.
d642 2
a643 2
 HPUX 9.0x andPA-RISC   7.0     2000-04-12, Tom Lane
 10.20                          (<tgl@@sss.pgh.pa.us>)
d670 4
a673 4
 QNX 4.25     x86       7.0     2000-04-01, Dr. Andreas Kardos
                                (<kardos@@repas-aeg.de>)
 SCO          x86       6.5     1999-05-25, Andrew Merrill
 OpenServer 5                   (<andrew@@compclass.com>)
d693 2
a694 2
7.1, but we did not receive explicit confirmation of such at the time this
list was compiled. We include these here to let you know that these
@


1.79
log
@Update for 7.0.2.
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.2.
d3 87
a89 2
If you haven't gotten the PostgreSQL distribution, get it from
ftp.postgresql.org, then unpack it:
d91 1
a91 3
> gunzip postgresql-7.0.2.tar.gz
> tar -xf postgresql-7.0.2.tar
> mv postgresql-7.0.2 /usr/src
d93 4
d98 3
a100 1
Before you start
d102 1
a102 5
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
d104 1
a104 1
> gmake --version
d106 3
d110 1
a110 1
If you need to get GNU make, you can find it at ftp://ftp.gnu.org.
d112 4
a115 6
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.
d117 2
a118 3
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.
d120 1
a120 6
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.
d122 1
a122 1
To check for disk space, use
d124 1
a124 1
> df -k
d126 4
a129 3
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.
d131 1
d135 1
a135 1
PostgreSQL Installation
d137 11
a147 1
For a fresh install or upgrading from previous releases of PostgreSQL:
d149 4
a152 5
  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.
d154 2
a155 3
     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.
d157 1
a157 3
     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.
d159 4
a162 4
  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:
d164 2
a165 1
     > ./configure
d167 1
d169 6
a174 3
     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:
d176 1
a176 1
     > ./configure --help
d178 2
d181 1
a181 1
     Some of the more commonly used ones are:
d183 3
a185 1
     --prefix=BASEDIR
d187 1
a187 2
          Selects a different base directory for the installation of
          PostgreSQL. The default is /usr/local/pgsql.
d189 4
a192 1
     --enable-locale
d194 2
a195 1
          If you want to use locales.
d197 1
a197 1
     --enable-multibyte
d199 2
a200 2
          Allows the use of multibyte character encodings. This is primarily
          for languages like Japanese, Korean, or Chinese.
d202 1
a202 1
     --with-perl
d204 2
a205 7
          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.)
d207 1
a207 1
     --with-odbc
d209 3
a211 1
          Builds the ODBC driver package.
d213 1
a213 1
     --with-tcl
d215 5
a219 2
          Builds interface libraries and programs requiring Tcl/Tk,
          including libpgtcl, pgtclsh, and pgtksh.
d221 1
a221 1
  3. Compile the program. Type
d223 1
a223 1
     > gmake
d225 4
d230 1
a230 2
     The compilation process can take anywhere from 10 minutes to an hour.
     Your mileage will most certainly vary. Remember to use GNU make.
d232 1
a232 1
     The last line displayed will hopefully be
d234 3
a236 1
     All of PostgreSQL is successfully made. Ready to install.
d238 1
d240 2
a241 6
  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.)
d243 1
a243 2
  5. If you are not upgrading an existing system, skip to step 7.
     If you are running 7.*, skip to step 6.
d245 3
a247 2
     You now need to back up your existing database. To dump your 
     database installation, type:
d249 1
a249 1
     > pg_dumpall > db.out
d251 11
d263 1
a263 3
     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.
d265 14
a278 3
     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.
d280 1
a280 5
                                        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.
d282 2
a283 1
      Rather than using pg_dumpall, pg_upgrade can often be used.
d285 1
a285 2
  6. If you are upgrading an existing system, kill the database server
     now. Type
d287 3
a289 1
     > ps ax | grep postmaster
d291 1
d293 6
a298 1
     or
d300 1
a300 1
     > ps -e | grep postmaster
d302 1
d304 1
a304 3
     (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:
d306 4
a309 2
       263  ?  SW   0:00 (postmaster)
       777  p1 S    0:00 grep postmaster
d311 1
d313 9
a321 3
     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".)
d323 3
a325 1
     > kill pid
d327 1
d329 2
a330 4
          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
d332 1
a332 1
          > /etc/rc.d/init.d/postgres.init stop
d334 5
d340 1
a340 1
          works.
d342 4
a345 2
     If you used pg_dumpall, move the old directory out of the
     way.  Type the following:
d347 1
a347 1
     > mv /usr/local/pgsql /usr/local/pgsql.old
d349 3
d353 3
a355 1
     (substitute your particular paths).
d357 1
a357 1
  7. Install the PostgreSQL executable files and libraries. Type
d359 1
a359 1
     > gmake install
d361 1
d363 1
a363 4
     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.
d365 2
a366 3
  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:
d368 1
a368 2
     > LD_LIBRARY_PATH=/usr/local/pgsql/lib
     > export LD_LIBRARY_PATH
d370 1
d372 4
a375 1
     on sh, ksh, bash, zsh or
d377 1
a377 1
     > setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
d379 5
d385 1
a385 2
     on csh or tcsh. You might want to put this into a shell startup file
     such as /etc/profile.
d387 5
a391 2
     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
d393 1
a393 1
     /usr/local/pgsql/lib
d395 1
d397 5
a401 1
     Then run command /sbin/ldconfig.
d403 4
a406 2
     If in doubt, refer to the manual pages of your system. If you later on
     get a message like
d408 2
a409 2
     psql: error in loading shared libraries
     libpq.so.2.1: cannot open shared object file: No such file or directory
d411 6
d418 2
a419 1
     then the above was necessary. Simply do this step then.
d421 3
a423 4
  9. If you moved the old directory out of the way, 
     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.
d425 3
a427 4
     > mkdir /usr/local/pgsql/data
     > chown postgres /usr/local/pgsql/data
     > su - postgres
     > /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
d429 7
d437 1
a437 8
     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.)
d439 1
a439 2
 10. The previous step should have told you how to start up the database
     server. Do so now. The command should look something like
d441 1
a441 1
     > /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d443 5
d449 2
a450 4
     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
d452 1
a452 2
     > nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
         </dev/null >>server.log 2>>1 &
d454 1
d456 3
a458 1
 11. If you did a pg_dumpall, reload your data back in:
d460 2
a461 1
     > /usr/local/pgsql/bin/psql -d template1 -f db.out
d463 1
d465 1
a465 3
     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.
d467 2
a468 3
This concludes the installation proper. To make your life more productive
and enjoyable you should look at the following optional steps and
suggestions:
d470 2
a471 5
   * 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):
d473 1
a473 1
     > PATH=$PATH:/usr/local/pgsql/bin
d475 1
d477 1
a477 2
     Furthermore, if you set PGDATA in the environment of the PostgreSQL
     superuser, you can omit the -D for postmaster and initdb.
d479 5
a483 1
   * You probably want to install the man and HTML documentation. Type
d485 1
a485 2
     > cd /usr/src/pgsql/postgresql-7.0.2/doc
     > gmake install
d487 1
d489 1
a489 4
     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:
d491 2
a492 1
     > MANPATH=$MANPATH:/usr/local/pgsql/man
d494 1
d496 6
a501 4
     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
d503 1
a503 2
     > cd /usr/local/pgsql/doc
     > gunzip -c user.ps.tz | lpr
d505 1
d507 2
a508 2
     Here is how you might do it if you have Ghostscript on your system and
     are writing to a laserjet printer.
d510 6
a515 3
     > gunzip -c user.ps.gz \
         | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
         | lpr
d517 1
d519 3
a521 2
     Printer setups can vary wildly from system to system. If in doubt,
     consult your manuals or your local expert.
d523 4
a526 3
     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.
d528 5
a532 4
   * 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.
d534 2
a535 7
     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.
d537 1
a537 2
     It might be advisable to keep a log of the server output. To start the
     server that way try:
d539 2
a540 1
     > nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
d542 2
d545 1
a545 1
     Here are a few more operating system specific suggestions.
d547 1
a547 2
        o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
          to contain the following single line:
d549 2
a550 1
          > su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
d552 1
d554 1
a554 3
        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.
d556 1
a556 7
          #!/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'
          }
d558 1
d560 2
a561 4
          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.
d563 1
a563 3
        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.
d565 1
a565 4
   * 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.
d567 4
a570 2
To start experimenting with Postgres, set up the paths as explained above
and start the server. To create a database, type
d572 4
a575 1
> createdb testdb
d577 3
d581 4
a584 1
Then enter
d586 1
a586 1
> psql testdb
d588 1
d590 93
a682 2
to connect to that database. At the prompt you can enter SQL commands and
start experimenting.
@


1.78
log
@Update for 7.0.2.
@
text
@d202 1
a202 1
     If you used pg_dumpall, move the old directories out of the
d253 2
a254 1
  9. Create the database installation (the working data files). To do this
@


1.77
log
@Mention pg_upgrade
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.1.
d6 3
a8 3
> gunzip postgresql-7.0.1.tar.gz
> tar -xf postgresql-7.0.1.tar
> mv postgresql-7.0.1 /usr/src
d141 2
a142 1
  5. If you are not upgrading an existing system then skip to step 7.
d144 2
a145 2
     You now need to back up your existing database. To dump your fairly
     recent post-6.0 database installation, type
d155 2
a156 7
     currently running. 7.0.1's pg_dumpall will not work on pre-7.0 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.
d166 1
a166 1
  6. If you are upgrading an existing system then kill the database server
d298 1
a298 1
suggestions.
d314 1
a314 1
     > cd /usr/src/pgsql/postgresql-7.0.1/doc
@


1.76
log
@Update 7.0.1
@
text
@d168 2
@


1.75
log
@Reformatted the install file as it used to be
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.
d6 3
a8 3
> gunzip postgresql-7.0.tar.gz
> tar -xf postgresql-7.0.tar
> mv postgresql-7.0 /usr/src
d154 1
a154 1
     currently running. 7.0's pg_dumpall will not work on older databases.
d167 1
d204 2
a205 1
     Also move the old directories out of the way. Type the following:
d289 1
a289 2
 11. If you are upgrading from an existing installation, dump your data back
     in:
d316 1
a316 1
     > cd /usr/src/pgsql/postgresql-7.0/doc
@


1.75.2.1
log
@Fixups for 7.0.1
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.1.
d6 3
a8 3
> gunzip postgresql-7.0.1.tar.gz
> tar -xf postgresql-7.0.1.tar
> mv postgresql-7.0.1 /usr/src
d154 1
a154 1
     currently running. 7.0.1's pg_dumpall will not work on pre-7.0 databases.
a166 1

d203 1
a203 2
     If you used pg_dumpall, move the old directories out of the
     way.  Type the following:
d287 2
a288 1
 11. If you did a pg_dumpall, reload your data back in:
d315 1
a315 1
     > cd /usr/src/pgsql/postgresql-7.0.1/doc
@


1.75.2.2
log
@Mention pg_upgrade
@
text
@a167 2
      Rather than using pg_dumpall, pg_upgrade can often be used.

@


1.75.2.3
log
@Update for 7.0.2.
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.2.
d6 3
a8 3
> gunzip postgresql-7.0.2.tar.gz
> tar -xf postgresql-7.0.2.tar
> mv postgresql-7.0.2 /usr/src
d141 1
a141 2
  5. If you are not upgrading an existing system, skip to step 7.
     If you are running 7.*, skip to step 6.
d143 2
a144 2
     You now need to back up your existing database. To dump your 
     database installation, type:
d154 7
a160 2
     currently running. 7.0.2's pg_dumpall should not be used on older
     databases.
d170 1
a170 1
  6. If you are upgrading an existing system, kill the database server
d302 1
a302 1
suggestions:
d318 1
a318 1
     > cd /usr/src/pgsql/postgresql-7.0.2/doc
@


1.75.2.4
log
@Update install for upgraders.
@
text
@d202 1
a202 1
     If you used pg_dumpall, move the old directory out of the
d253 1
a253 2
  9. If you moved the old directory out of the way, 
     create the database installation (the working data files). To do this
@


1.75.2.5
log
@Brand 7.0.3.
@
text
@d1 1
a1 1
     Installation instructions for PostgreSQL 7.0.3.
d6 3
a8 3
> gunzip postgresql-7.0.3.tar.gz
> tar -xf postgresql-7.0.3.tar
> mv postgresql-7.0.3 /usr/src
d155 1
a155 1
     currently running. 7.0.3's pg_dumpall should not be used on older
d315 1
a315 1
     > cd /usr/src/pgsql/postgresql-7.0.3/doc
@


1.74
log
@Installation guide for 7.0 release. From SGML sources.
@
text
@d1 1
d3 6
a8 183
                    PostgreSQL Installation Guide
                   The PostgreSQL Development Team
                                  
                              Edited by
                           Thomas Lockhart

PostgreSQL is Copyright  1996-2000 by PostgreSQL Inc.

Table of Contents

      Summary                                                    
      1. Introduction                                            
      2. Ports                                                   
          Currently Supported Platforms                          
          Unsupported Platforms                                  
      3. Installation                                            
          Before you start                                       
          Installation Procedure                                 
      4. Configuration Options                                   
      5. Release Notes                                           
          Release 7.0                                            
             Migration to v7.0                                   
             Detailed Change List                                
      6. Regression Test                                         

Summary


       Postgres, developed originally in the UC Berkeley Computer 
      Science Department, pioneered many of the object-relational 
      concepts now becoming available in some commercial databases. 
      It provides SQL92/SQL3 language support, transaction integrity, 
      and type extensibility. PostgreSQL is an open-source descendant 
      of this original Berkeley code. 

Chapter 1. Introduction


       This installation procedure makes some assumptions about the 
      desired configuration and runtime environment for your system. 
      This may be adequate for many installations, and is almost 
      certainly adequate for a first installation. But you may want 
      to do an initial installation up to the point of unpacking the 
      source tree and installing documentation, and then print or 
      browse the Administrator's Guide. 

Chapter 2. Ports


       This manual describes version 7.0 of Postgres. The Postgres 
      developer community has compiled and tested Postgres on a 
      number of platforms. Check the web site 
      (http://www.postgresql.org/docs/admin/ports.htm) for the latest 
      information. 

Currently Supported Platforms


       At the time of publication, the following platforms have been 
      tested: 

      Table 2-1. Supported Platforms
      OS       Processor Version Reported    Remarks
      AIX      RS6000    v7.0    2000-04-05  Andreas Zeugswetter 
      4.3.2                                  (Andreas.Zeugswetter@@telecom.at)
      BSDI     x86       v7.0    2000-04-04  Bruce Momjian 
      4.01                                   (maillist@@candle.pha.pa.us)
      Compaq   Alpha     v7.0    2000-04-11  Andrew McMurry 
      Tru64                                  (andrew.mcmurry@@astro.uio.no)
      FreeBSD  x86       v7.0    2000-04-04  Marc Fournier 
      4.0                                    (scrappy@@hub.org)
      HPUX     PA-RISC   v7.0    2000-04-12  Both 9.0x and 10.20. Tom Lane 
                                             (tgl@@sss.pgh.pa.us)
      IRIX     MIPS      v6.5.3  2000-02-18  MIPSPro 7.3.1.1m N32 build. Kevin 
      6.5.6f                                 Wheatley (hxpro@@cinesite.co.uk)
      Linux    Alpha     v7.0    2000-04-05  With published patches.
      2.0.x                                  Ryan Kirkpatrick 
                                             (pgsql@@rkirkpat.net)
      Linux    armv4l    v7.0    2000-04-17  Regression test needs work.
      2.2.x                                  Mark Knox 
                                             (segfault@@hardline.org)
      Linux    x86       v7.0    2000-03-26  Lamar Owens 
      2.2.x                                  (lamar.owen@@wgcr.org)
      Linux    MIPS      v7.0    2000-04-13  Cobalt Qube. Tatsuo Ishii 
      2.0.x                                  (t-ishii@@sra.co.jp)
      Linux    Sparc     v7.0    2000-04-02  Tom Szybist 
      2.2.5                                  (szybist@@boxhill.com)
      Linux    PPC603e   v7.0    2000-04-13  Tatsuo Ishii 
      PPC R4                                 (t-ishii@@sra.co.jp)
      mklinux  PPC750    v7.0    2000-04-13  Tatsuo Ishii 
                                             (t-ishii@@sra.co.jp)
      NetBSD   arm32     v7.0    2000-04-08  Patrick Welche 
      1.4                                    (prlw1@@newn.cam.ac.uk)
      NetBSD   x86       v7.0    2000-03-26  Patrick Welche 
      1.4U                                   (prlw1@@newn.cam.ac.uk)
      NetBSD   m68k      v7.0    2000-04-10  Mac 8xx. Henry B. Hotz 
                                             (hotz@@jpl.nasa.gov)
      NetBSD-  Sparc     v7.0    2000-04-13  Tom I Helbekkmo 
      /sparc                                 (tih@@kpnQwest.no)
      QNX      x86       v7.0    2000-04-01  Dr. Andreas Kardos 
      4.25                                   (kardos@@repas-aeg.de)
      SCO Open x86       v6.5    1999-05-25  Andrew Merrill 
      Server 5                               (andrew@@compclass.com)
      SCO UW7  x86       v7.0    2000-04-18  See FAQ. Billy G. Allie 
                                             (Bill.Allie@@mug.org)
      Solaris  x86       v7.0    2000-04-12  Marc Fournier 
                                             (scrappy@@hub.org)
      Solaris  Sparc     v7.0    2000-04-12  Peter Eisentraut 
      2.5-.7                                 (peter_e@@gmx.net)
      SunOS    Sparc     v7.0    2000-04-13  Tatsuo Ishii 
      4.1.4                                  (t-ishii@@sra.co.jp)
      Windows  x86       v7.0    2000-04-02  No server-side. Magnus Hagander 
      Win32                                  (mha@@sollentuna.net)
      WinNT    x86       v7.0    2000-03-30  Uses Cygwin library. Daniel Horak 
      Cygwin                                 (horak@@sit.plzen-city.cz) 


       

         Note: For Windows NT, the server-side port of Postgres uses 
         the RedHat/Cygnus Cygwin library and toolset. For Windows 
         9x, no server-side port is available due to OS limitations.

Unsupported Platforms


       Platforms listed for v6.3.x-v6.5.x should also work with v7.0, 
      but we did not receive explicit confirmation of such at the 
      time this list was compiled. We include these here to let you 
      know that these platforms could be supported if given some 
      attention. 
       At the time of publication, the following platforms have not 
      been tested for v7.0 or v6.5.x: 

      Table 2-2. Unsupported Platforms
      OS       Processor Version  Reported   Remarks
      BeOS     x86       v7.0     2000-05-01 Client-side coming soon?
                                             Adam Haberlach 
                                             (adam@@newsnipple.com)
      DGUX     m88k      v6.3     1998-03-01 v6.4 probably OK. Needs new 
      5.4R4.11                               maintainer. Brian E Gallew 
                                             (geek+@@cmu.edu)
      NetBSD   NS32532   v6.4     1998-10-27 Date/time math annoyances.
      current                                Jon Buller (jonb@@metronet.com)
      NetBSD   VAX       v6.3     1998-03-01 v7.0 should work. Tom I Helbekkmo 
      1.3                                    (tih@@kpnQwest.no)
      SVR4 4.4 m88k      v6.2.1   1998-03-01 v6.4.x will need TAS spinlock 
                                             code. Doug Winterburn 
                                             (dlw@@seavme.xroads.com)
      SVR4     MIPS      v6.4     1998-10-28 No 64-bit int. Frank Ridderbusch 
                                             (ridderbusch.pad@@sni.de)
      Ultrix   MIPS, VAX v6.x     1998-03-01 No recent reports; obsolete?


       
       There are a few platforms which have been attempted and which 
      have been reported to not work with the standard distribution. 
      Others listed here do not provide sufficient library support 
      for an attempt. 

      Table 2-3. Incompatible Platforms
      OS       Processor Version  Reported    Remarks
      MacOS    all       v6.x     1998-03-01  Not library compatible; use 
                                              ODBC/JDBC
      NextStep x86       v6.x     1998-03-01  Client-only support; v1.0.9 
                                              worked with patches David 
                                              Wetzel 
                                              (dave@@turbocat.de)


       
Chapter 3. Installation


       Installation instructions for PostgreSQL 7.0. 

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

      > gunzip postgresql-7.0.tar.gz
      > tar -xf postgresql-7.0.tar
      > mv postgresql-7.0 /usr/src
         
a9 1
       
d13 36
a49 38
       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 
      (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. 
d53 362
d416 2
a417 1413
      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 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. 

                                     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. 



      6.  If you are upgrading an existing system then 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.

          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/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 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. 
      o   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. 
      o   You probably want to install the man and HTML documentation. 
        Type 
        > cd /usr/src/pgsql/postgresql-7.0/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. 
      o   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. 
         
      o   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. 
Chapter 4. Configuration Options


Parameters for Configuration (configure)


       The full set of parameters available in configure can be 
      obtained by typing 

      $ ./configure --help
          

       
       The following parameters may be of interest to installers: 

      Directories to install PostgreSQL in:
        --prefix=PREFIX         install architecture-independent files
                                [/usr/local/pgsql]
        --bindir=DIR            user executables in DIR [EPREFIX/bin]
        --libdir=DIR            object code libraries in DIR 
      [EPREFIX/lib]
        --includedir=DIR        C header files in DIR 
      [PREFIX/include]
        --mandir=DIR            man documentation in DIR [PREFIX/man]
      Features and packages:
        --disable-FEATURE       do not include FEATURE
        --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
        --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
        --without-PACKAGE       do not use PACKAGE
      --enable and --with options recognized:
        --with-template=template
                                use operating system template file
                                    see template directory
        --with-includes=dirs    look for header files for tcl/tk, etc 
        --with-libraries=dirs   look for additional libraries in DIRS
        --with-libs=dirs        alternate for --with-libraries
        --enable-locale         enable locale support
        --enable-recode         enable cyrillic recode support
        --enable-multibyte      enable multibyte character support
        --with-pgport=portnum   change default postmaster port
        --with-maxbackends=n    set default maximum number of processes 
        --with-tcl              build Tcl interfaces and pgtclsh
        --with-tclconfig=tcldir
                                tclConfig.sh and tkConfig.sh location
        --with-perl             build Perl interface and plperl
        --with-odbc             build ODBC driver package
        --with-odbcinst=odbcdir
                                default directory for odbcinst.ini
        --enable-cassert        enable assertion checks
        --enable-debug          build with debugging symbols (-g) 
        --with-CC=compiler
                                use specific C compiler
        --with-CXX=compiler
                                use specific C++ compiler
        --without-CXX           prevent building C++ code 
          

       
       Some systems may have trouble building a specific feature of 
      Postgres. For example, systems with a damaged C++ compiler may 
      need to specify --without-CXX to instruct the build procedure 
      to skip construction of libpq++. 
       Use the --with-includes and --with-libraries options if you 
      want to build Postgres using include files or libraries that 
      are not installed in your system's standard search path. For 
      example, you might use these to build with an experimental 
      version of Tcl. If you need to specify more than one 
      nonstandard directory for include files or libraries, do it 
      like this: 

      --with-includes="/opt/tcl/include /opt/perl5/include"
          

       

Parameters for Building (make)


       Many installation-related parameters can be set in the 
      building stage of Postgres installation. 
       In most cases, these parameters should be placed in a file, 
      Makefile.custom, intended just for that purpose. The default 
      distribution does not contain this optional file, so you will 
      create it using a text editor of your choice. When upgrading 
      installations, you can simply copy your old Makefile.custom to 
      the new installation before doing the build. 
       Alternatively, you can set variables on the make command line: 

      make [ variable=value [...] ]
          

       
       A few of the many variables that can be specified are: 

       POSTGRESDIR 
          Top of the installation tree. 

       BINDIR 
          Location of applications and utilities. 

       LIBDIR 
          Location of object libraries, including shared libraries. 

       HEADERDIR 
          Location of include files. 

       ODBCINST 
          Location of installation-wide psqlODBC (ODBC) configuration 
         file. 
       
       There are other optional parameters which are not as commonly 
      used. Many of those listed below are appropriate when doing 
      Postgres server code development. 

       CFLAGS 
          Set flags for the C compiler. Should be assigned with "+=" 
         to retain relevant default parameters. 

       YFLAGS 
          Set flags for the yacc/bison parser. -v might be used to 
         help diagnose problems building a new parser. Should be 
         assigned with "+=" to retain relevant default parameters. 

       USE_TCL 
          Enable Tcl interface building. 

       HSTYLE 
          DocBook HTML style sheets for building the documentation 
         from scratch. Not used unless you are developing new 
         documentation from the DocBook-compatible SGML source 
         documents in doc/src/sgml/. 

       PSTYLE 
          DocBook style sheets for building printed documentation 
         from scratch. Not used unless you are developing new 
         documentation from the DocBook-compatible SGML source 
         documents in doc/src/sgml/. 
       
       Here is an example Makefile.custom for a PentiumPro Linux 
      system: 

      # Makefile.custom
      # Thomas Lockhart 1999-06-01

      POSTGRESDIR= /opt/postgres/current
      CFLAGS+= -m486 -O2

      # documentation

      HSTYLE= /home/tgl/SGML/db118.d/docbook/html
      PSTYLE= /home/tgl/SGML/db118.d/docbook/print
          

       

Locale Support


       

         Note: Written by Oleg Bartunov. See Oleg's web page 
         (http://www.sai.msu.su/~megera/postgres/) for additional 
         information on locale and Russian language support.

       While doing a project for a company in Moscow, Russia, I 
      encountered the problem that postgresql had no support of 
      national alphabets. After looking for possible workarounds I 
      decided to develop support of locale myself. I'm not a 
      C-programer but already had some experience with locale 
      programming when I work with perl (debugging) and glimpse. 
      After several days of digging through the Postgres source tree 
      I made very minor corections to src/backend/utils/adt/varlena.c 
      and src/backend/main/main.c and got what I needed! I did 
      support only for LC_CTYPE and LC_COLLATE, but later LC_MONETARY 
      was added by others. I got many messages from people about this 
      patch so I decided to send it to developers and (to my 
      surprise) it was incorporated into the Postgres distribution. 
       People often complain that locale doesn't work for them. There 
      are several common mistakes: 
      o   Didn't properly configure postgresql before compilation. You 
        must run configure with --enable-locale option to enable 
        locale support. Didn't setup environment correctly when 
        starting postmaster. You must define environment variables 
        LC_CTYPE and LC_COLLATE before running postmaster because 
        backend gets information about locale from environment. I use 
        following shell script (runpostgres): 
               #!/bin/sh
               
               export LC_CTYPE=koi8-r
               export LC_COLLATE=koi8-r
               postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o 
        '-Fe'
              
         and run it from rc.local as 
               /bin/su - postgres -c "/home/postgres/runpostgres"
              
         
      o   Broken locale support in OS (for example, locale support in 
        libc under Linux several times has changed and this caused a 
        lot of problems). Latest perl has also support of locale and 
        if locale is broken perl -v will complain something like: 
               8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist
               8:18[mira]:~/WWW/postgres>perl -v
               perl: warning: Setting locale failed.
               perl: warning: Please check that your locale settings:
               LC_ALL = (unset),
                   LC_CTYPE = "not_exist",
                   LANG = (unset)
               are supported and installed on your system.
               perl: warning: Falling back to the standard locale 
        ("C").
              
         
      o   Wrong location of locale files! Possible locations include: 
        /usr/lib/locale (Linux, Solaris), /usr/share/locale (Linux), 
        /usr/lib/nls/loc (DUX 4.0). Check man locale to find the 
        correct location. Under Linux I did a symbolic link between 
        /usr/lib/locale and /usr/share/locale to be sure that the 
        next libc will not break my locale. 
       

What are the Benefits?


       You can use ~* and order by operators for strings contain 
      characters from national alphabets. Non-english users 
      definitely need that. If you won't use locale stuff just 
      undefine the USE_LOCALE variable. 

What are the Drawbacks?


       There is one evident drawback of using locale - its speed! So, 
      use locale only if you really need it. 

Kerberos Authentication


       Kerberos is an industry-standard secure authentication system 
      suitable for distributed computing over a public network. 

Availability


       The Kerberos authentication system is not distributed with 
      Postgres. Versions of Kerberos are typically available as 
      optional software from operating system vendors. In addition, a 
      source code distribution may be obtained through MIT Project 
      Athena (ftp://athena-dist.mit.edu). 

         Note: You may wish to obtain the MIT version even if your 
         vendor provides a version, since some vendor ports have been 
         deliberately crippled or rendered non-interoperable with the 
         MIT version.

       Users located outside the United States of America and Canada 
      are warned that distribution of the actual encryption code in 
      Kerberos is restricted by U. S. Government export regulations. 
       Inquiries regarding your Kerberos should be directed to your 
      vendor or MIT Project Athena (info-kerberos@@athena.mit.edu). 
      Note that FAQLs (Frequently-Asked Questions Lists) are 
      periodically posted to the Kerberos mailing list 
      (mailto:kerberos@@athena.mit.edu) (send mail to subscribe 
      (mailto:kerberos-request@@athena.mit.edu)), and USENET news 
      group (news:comp.protocols.kerberos). 

Installation


       Installation of Kerberos itself is covered in detail in the 
      Kerberos Installation Notes . Make sure that the server key 
      file (the srvtab or keytab) is somehow readable by the Postgres 
      account. 
       Postgres and its clients can be compiled to use either Version 
      4 or Version 5 of the MIT Kerberos protocols by setting the 
      KRBVERS variable in the file src/Makefile.global to the 
      appropriate value. You can also change the location where 
      Postgres expects to find the associated libraries, header files 
      and its own server key file. 
       After compilation is complete, Postgres must be registered as 
      a Kerberos service. See the Kerberos Operations Notes and 
      related manual pages for more details on registering services. 

Operation


       After initial installation, Postgres should operate in all 
      ways as a normal Kerberos service. For details on the use of 
      authentication, see the PostgreSQL User's Guide reference 
      sections for postmaster and psql. 
       In the Kerberos Version 5 hooks, the following assumptions are 
      made about user and service naming: 
      o   User principal names (anames) are assumed to contain the 
        actual Unix/Postgres user name in the first component. 
      o   The Postgres service is assumed to be have two components, 
        the service name and a hostname, canonicalized as in Version 
        4 (i.e., with all domain suffixes removed). 
       
       

      Table 4-1. Kerberos Parameter Examples
        Param-     Example 
       eter 
        user       frew@@S2K.ORG 
        user       aoki/HOST=miyu.S2K.Berkeley.EDU@@S2K.-
                  ORG 
        host       postgres_dbms/ucbvax@@S2K.ORG 


       
       Support for Version 4 will disappear sometime after the 
      production release of Version 5 by MIT. 

Chapter 5. Release Notes


Release 7.0


       This release contains improvements in many areas, 
      demonstrating the continued growth of PostgreSQL. There are 
      more improvements and fixes in 7.0 than in any previous 
      release. The developers have confidence that this is the best 
      release yet; we do our best to put out only solid releases, and 
      this one is no exception. 
       Major changes in this release: 

       Foreign Keys 
          Foreign keys are now implemented, with the exception of 
         PARTIAL MATCH foreign keys. Many users have been asking for 
         this feature, and we are pleased to offer it. 

       Optimizer Overhaul 
          Continuing on work started a year ago, the optimizer has 
         been improved, allowing better query plan selection and 
         faster performance with less memory usage. 

       Updated psql 
          psql, our interactive terminal monitor, has been updated 
         with a variety of new features. See the psql manual page for 
         details. 

       Join Syntax 
          SQL92 join syntax is now supported, though only as INNER 
         JOINs for this release. JOIN, NATURAL JOIN, JOIN/USING, 
         JOIN/ON are available, as are column correlation names. 
       

Migration to v7.0


       A dump/restore using pg_dump is required for those wishing to 
      migrate data from any previous release of Postgres. For those 
      upgrading from 6.5.*, you may instead use pg_upgrade to upgrade 
      to this release; however, a full dump/reload installation is 
      always the most robust method for upgrades. 
       Interface and compatibility issues to consider for the new 
      release include: 
      o   The date/time types datetime and timespan have been 
        superceded by the SQL92-defined types timestamp and interval. 
        Although there has been some effort to ease the transition by 
        allowing Postgres to recognize the deprecated type names and 
        translate them to the new type names, this mechanism may not 
        be completely transparent to your existing application. 
      o   The optimizer has been substantially improved in the area of 
        query cost estimation. In some cases, this will result in 
        decreased query times as the optimizer makes a better choice 
        for the preferred plan. However, in a small number of cases, 
        usually involving pathological distributions of data, your 
        query times may go up. If you are dealing with large amounts 
        of data, you may want to check your queries to verify 
        performance. 
      o   The JDBC and ODBC interfaces have been upgraded and 
        extended. 
      o   The string function CHAR_LENGTH is now a native function. 
        Previous versions translated this into a call to LENGTH, 
        which could result in ambiguity with other types implementing 
        LENGTH such as the geometric types. 
       

Detailed Change List


       

   Bug Fixes
   ---------
   Prevent function calls exceeding maximum number of arguments (Tom)
   Improve CASE construct (Tom)
   Fix SELECT coalesce(f1,0) FROM int4_tbl GROUP BY f1 (Tom)
   Fix SELECT sentence.words[0] FROM sentence GROUP BY 
    sentence.words[0] (Tom)
   Fix GROUP BY scan bug (Tom)
   Improvements in SQL grammar processing (Tom)
   Fix for views involved in INSERT ... SELECT ... (Tom)
   Fix for SELECT a/2, a/2 FROM missing_target GROUP BY a/2 (Tom)
   Fix for subselects in INSERT ... SELECT (Tom)
   Prevent INSERT ... SELECT ... ORDER BY (Tom)
   Fixes for relations greater than 2GB, including vacuum
   Improve propagating system table changes to other backends (Tom)
   Improve propagating user table changes to other backends (Tom)
   Fix handling of temp tables in complex situations (Bruce, Tom)
   Allow table locking at table open, improving concurrent 
    reliability (Tom)
   Properly quote sequence names in pg_dump (Ross J. Reedstrom)
   Prevent DROP DATABASE while others accessing
   Prevent any rows from being returned by GROUP BY if no rows 
    processed (Tom)
   Fix SELECT COUNT(1) FROM table WHERE ...' if no rows matching 
    WHERE (Tom)
   Fix pg_upgrade so it works for MVCC (Tom)
   Fix for SELECT ... WHERE x IN (SELECT ... HAVING SUM(x) > 1) (Tom)
   Fix for "f1 datetime DEFAULT 'now'"  (Tom)
   Fix problems with CURRENT_DATE used in DEFAULT (Tom)
   Allow comment-only lines, and ;;; lines too. (Tom)
   Improve recovery after failed disk writes, disk full (Hiroshi)
   Fix cases where table is mentioned in FROM but not joined (Tom)
   Allow HAVING clause without aggregate functions (Tom)
   Fix for "--" comment and no trailing newline, as seen in perl
   Improve pg_dump failure error reports (Bruce)
   Allow sorts and hashes to exceed 2GB file sizes (Tom)
   Fix for pg_dump dumping of inherited rules (Tom)
   Fix for NULL handling comparisons (Tom)
   Fix inconsistent state caused by failed CREATE/DROP (Hiroshi)
   Fix for dbname with dash
   Prevent DROP INDEX from interfering with other backends (Tom)
   Fix file descriptor leak in verify_password()
   Fix for "Unable to identify an operator =$" problem
   Fix ODBC so no segfault if CommLog and Debug enabled
    (Dirk Niggemann)
   Fix for recursive exit call (Massimo)
   Fix for extra-long timezones (Jeroen van Vianen)
   Make pg_dump preserve primary key information (Peter E)
   Prevent databases with single quotes (Peter E)
   Prevent DROP DATABASE inside  transaction (Peter E)
   ecpg memory leak fixes (Stephen Birch)
   Fix for SELECT null::text, SELECT int4fac(null)
    and SELECT 2 + (null) (Tom)
   Y2K timestamp fix (Massimo)
   Fix for VACUUM 'HEAP_MOVED_IN was not expected' errors (Tom)
   Fix for views with tables/columns containing spaces  (Tom)
   Prevent permissions on indexes (Peter E)
   Fix for spinlock stuck problem on error (Hiroshi)
   Fix ipcclean on Linux
   Fix handling of NULL constraint conditions (Tom)
   Fix memory leak in odbc driver (Nick Gorham)
   Fix for permission check on UNION tables (Tom)
   Fix to allow SELECT 'a' LIKE 'a' (Tom)
   Fix for SELECT 1 + NULL (Tom)
   Fixes to CHAR
   Fix log() on numeric type (Tom)
   Deprecate ':' and ';' operators
   Allow vacuum of temporary tables
   Disallow inherited columns with the same name as new columns
   Recover or force failure when disk space is exhausted(Hiroshi)
   Fix INSERT INTO ... SELECT with AS columns matching result columns
   Fix INSERT ... SELECT ... GROUP BY groups by target columns not 
    source columns(Tom)
   Fix CREATE TABLE test (a char(5) DEFAULT text '', b int4)
    with INSERT(Tom)
   Fix UNION with LIMIT
   Fix CREATE TABLE x AS SELECT 1 UNION SELECT 2
   Fix CREATE TABLE test(col char(2) DEFAULT user)
   Fix mismatched types in CREATE TABLE ... DEFAULT
   Fix SELECT * FROM pg_class where oid in (0,-1)
   Fix SELECT COUNT('asdf') FROM pg_class WHERE oid=12
   Prevent user who can create databases can modifying pg_database 
    table (Peter E)
   Fix btree to give a useful elog when key > 1/2 (page - overhead)
    (Tom)
   Fix INSERT of 0.0 into DECIMAL(4,4) field (Tom)

   Enhancements
   ------------
   New CLI interface include file sqlcli.h, based on SQL3/SQL98
   Remove all limits on query length, row length limit still 
    exists (Tom)
   Update jdbc protocol to 2.0 (Jens Glaser (jens@@jens.de))
   Add TRUNCATE command to quickly truncate relation (Mike Mascari)
   Fix to give super user and createdb user proper update catalog 
    rights (Peter E)
   Allow ecpg bool variables to have NULL values (Christof)
   Issue ecpg error if NULL value for variable with no NULL 
    indicator (Christof)
   Allow ^C to cancel COPY command (Massimo)
   Add SET FSYNC and SHOW PG_OPTIONS commands (Massimo)
   Function name overloading for dynamically-loaded C functions 
    (Frankpitt)
   Add CmdTuples() to libpq++(Vince)
   New CREATE CONSTRAINT TRIGGER and SET CONSTRAINTS commands (Jan)
   Allow CREATE FUNCTION/WITH clause to be used for all types
   configure --enable-debug adds -g (Peter E)
   configure --disable-debug removes -g (Peter E)
   Allow more complex default expressions (Tom)
   First real FOREIGN KEY constraint trigger functionality (Jan)
   Add FOREIGN KEY ... MATCH FULL ... ON DELETE CASCADE (Jan)
   Add FOREIGN KEY ... MATCH <unspecified> referential actions 
    (Don Baccus)
   Allow WHERE restriction on ctid (physical heap location) (Hiroshi)
   Move pginterface from contrib to interface directory,
    rename to pgeasy (Bruce)
   Change pgeasy connectdb() parameter ordering (Bruce)
   Require SELECT DISTINCT target list to have all ORDER BY 
    columns (Tom)
   Add Oracle's COMMENT ON command (Mike Mascari (mascarim@@yahoo))
   libpq's PQsetNoticeProcessor function now returns previous 
    hook (Peter E)
   Prevent PQsetNoticeProcessor from being set to NULL (Peter E)
   Make USING in COPY optional (Bruce)
   Allow subselects in the target list (Tom)
   Allow subselects on the left side of comparison operators (Tom)
   New parallel regression test (Jan)
   Change backend-side COPY to write files with permissions 644 
    not 666 (Tom)
   Force permissions on PGDATA directory to be secure, even if it 
    exists (Tom)
   Added psql LASTOID variable to return last inserted oid (Peter E)
   Allow concurrent vacuum and remove pg_vlock vacuum lock file (Tom)
   Add permissions check for vacuum (Peter E)
   New libpq functions to allow asynchronous connections: 
   PQconnectStart(), PQconnectPoll(), PQresetStart(), PQresetPoll(), 
   PQsetenvStart(), PQsetenvPoll(), PQsetenvAbort (Ewan Mellor)
   New libpq PQsetenv() function (Ewan Mellor)
   create/alter user extension (Peter E)
   New postmaster.pid and postmaster.opts under $PGDATA (Tatsuo)
   New scripts for create/drop user/db (Peter E)
   Major psql overhaul (Peter E)
   Add const to libpq interface (Peter E)
   New libpq function PQoidValue (Peter E)
   Show specific non-aggregate causing problem with GROUP BY (Tom)
   Make changes to pg_shadow recreate pg_pwd file (Peter E)
   Add aggregate(DISTINCT ...) (Tom)
   Allow flag to control COPY input/output of NULLs (Peter E)
   Make postgres user have a password by default (Peter E)
   Add CREATE/ALTER/DROP GROUP (Peter E)
   All administration scripts now support --long options
    (Peter E, Karel)
   Vacuumdb script now supports --all option (Peter E)
   ecpg new portable FETCH syntax
   Add ecpg EXEC SQL IFDEF, EXEC SQL IFNDEF, EXEC SQL ELSE, EXEC 
    SQL ELIF and EXEC SQL ENDIF directives
   Add pg_ctl script to control backend startup (Tatsuo)
   Add postmaster.opts.default file to store startup flags (Tatsuo)
   Allow --with-mb=SQL_ASCII
   Increase maximum number of index keys to 16 (Bruce)
   Increase maximum number of function arguments to 16 (Bruce)
   Allow configuration of maximum number of index keys and 
   arguments (Bruce)
   Allow unprivileged users to change their passwords (Peter E)
   Password authentication enabled; required for new users (Peter E)
   Disallow dropping a user who owns a database (Peter E)
   Change initdb option --with-mb to --enable-multibyte
   Add option for initdb to prompts for superuser password (Peter E)
   Allow complex type casts like col::numeric(9,2) and 
   col::int2::float8 (Tom)
   Updated user interfaces on initdb, initlocation, pg_dump, 
    ipcclean (Peter E)
   New pg_char_to_encoding() and pg_encoding_to_char() (Tatsuo)
   New libpq functions PQsetClientEncoding(), PQclientEncoding() 
    (Tatsuo)
   Libpq non-blocking mode (Alfred Perlstein)
   Improve conversion of types in casts that don't specify a length
   New plperl internal programming language (Mark Hollomon)
   Allow COPY IN to read file that do not end with a newline (Tom)
   Indicate when long identifiers are truncated (Tom)
   Allow aggregates to use type equivalency (Peter E)
   Add Oracle's to_char(), to_date(), to_datetime(), to_timestamp(),
    to_number() conversion functions (Karel Zak <zakkr@@zf.jcu.cz>)
   Add SELECT DISTINCT ON (expr [, expr ...]) targetlist ... (Tom)
   Check to be sure ORDER BY is compatible with DISTINCT (Tom)
   Add NUMERIC and int8 types to ODBC
   Improve EXPLAIN results for Append, Group, Agg, Unique (Tom)
   Add ALTER TABLE ... ADD FOREIGN KEY (Stephan Szabo)
   Allow SELECT .. FOR UPDATE in PL/pgSQL (Hiroshi)
   Enable backward sequential scan even after reaching EOF (Hiroshi)
   Add btree indexing of boolean values, >= and <= (Don Baccus)
   Print current line number when COPY FROM fails (Massimo)
   Recognize POSIX time zone e.g. "PST+8" and "GMT-8" (Thomas)
   Add DEC as synonym for DECIMAL (Thomas)
   Add SESSION_USER as SQL92 keyword (== CURRENT_USER) (Thomas)
   Implement SQL92 column aliases (aka correlation names) (Thomas)
   Implement SQL92 join syntax (Thomas)
   INTERVAL reserved word allowed as a column identifier (Thomas)
   Implement REINDEX command (Hiroshi)
   Accept ALL in aggregate function SUM(ALL col) (Tom)
   Prevent GROUP BY from using column aliases (Tom)
   New psql \encoding option (Tatsuo)
   Allow PQrequestCancel() to terminate when in waiting-for-lock 
    state (Hiroshi)
   Allow negation of a negative number in all cases
   Add ecpg descriptors (Christof, Michael)
   Allow CREATE VIEW v AS SELECT f1::char(8) FROM tbl
   Allow casts with length, like foo::char(8)
   Add support for SJIS user defined characters (Tatsuo)
   Larger views/rules supported
   Make libpq's PQconndefaults() thread-safe (Tom)
   Disable // as comment to be ANSI conforming, should use -- (Tom)
   Allow column aliases on views CREATE VIEW name (collist)
   Fixes for views with subqueries (Tom)
   Allow UPDATE table SET fld = (SELECT ...) (Tom)
   SET command options no longer require quotes
   Update pgaccess to 0.98.6
   New SET SEED command
   New pg_options.sample file
   New SET FSYNC command (Massimo)
   Allow pg_descriptions when creating tables
   Allow pg_descriptions when creating types, columns, and functions
   Allow psql \copy to allow delimiters(Peter E)
   Allow psql to print nulls as distinct from "" [null](Peter E)

   Types
   -----
   Many array fixes (Tom)
   Allow bare column names to be subscripted as arrays (Tom)
   Improve type casting of int and float constants (Tom)
   Cleanups for int8 inputs, range checking, and type conversion (Tom)
   Fix for SELECT timespan('21:11:26'::time) (Tom)
   netmask('x.x.x.x/0') is 255.255.255.255 instead of 0.0.0.0 
   (Oleg Sharoiko)
   Add btree index on NUMERIC (Jan)
   Perl fix for large objects containing NUL characters
    (Douglas Thomson) 
   ODBC fix for for large objects (free)
   Fix indexing of cidr data type
   Fix for Ethernet MAC addresses (macaddr type) comparisons
   Fix for date/time types when overflows happen (Tom)
   Allow array on int8 (Peter E)
   Fix for rounding/overflow of NUMERIC type, like NUMERIC(4,4) (Tom)
   Allow NUMERIC arrays
   Fix bugs in NUMERIC ceil() and floor() functions (Tom)
   Make char_length()/octet_length including trailing blanks (Tom)
   Made abstime/reltime use int4 instead of time_t (Peter E)
   New lztext data type for compressed text fields
   Revise code to handle coercion of int and float constants (Tom)
   Start at new code to implement a BIT and BIT VARYING type 
    (Adriaan Joubert)
   NUMERIC now accepts scientific notation (Tom)
   NUMERIC to int4 rounds (Tom)
   Convert float4/8 to NUMERIC properly (Tom)
   Allow type conversion with NUMERIC (Thomas)
   Make ISO date style (2000-02-16 09:33) the default (Thomas)
   Add NATIONAL CHAR [ VARYING ] (Thomas)
   Allow NUMERIC round and trunc to accept negative scales (Tom)
   New TIME WITH TIME ZONE type (Thomas)
   Add MAX()/MIN() on time type (Thomas)
   Add abs(), mod(), fac() for int8 (Thomas)
   Rename functions to round(), sqrt(), cbrt(), pow() for float8 
    (Thomas)
   Add transcendental math functions for float8 (Thomas)
   Add exp() and ln() for NUMERIC type (Jan)
   Rename NUMERIC power() to pow() (Thomas)
   Improved TRANSLATE() function (Edwin Ramirez, Tom)
   Allow X=-Y operators  (Tom)
   Allow SELECT float8(COUNT(*))/(SELECT COUNT(*) FROM t)
    FROM t GROUP BY f1; (Tom)
   Allow LOCALE to use indexes in regular expression searches (Tom)
   Allow creation of functional indexes to use default types

   Performance
   -----------
   Prevent exponential space usage with many AND's and OR's (Tom)
   Collect attribute selectivity values for system columns (Tom)
   Reduce memory usage of aggregates (Tom)
   Fix for LIKE optimization to use indexes with multi-byte 
    encodings (Tom)
   Fix r-tree index optimizer selectivity (Thomas)
   Improve optimizer selectivity computations and functions (Tom)
   Optimize btree searching when many equal keys exist (Tom)
   Enable fast LIKE index processing only if index present (Tom)
   Re-use free space on index pages with duplicates (Tom)
   Improve hash join processing (Tom)
   Prevent descending sort if result is already sorted(Hiroshi)
   Allow commuting of index scan query qualifications (Tom)
   Prefer index scans when ORDER BY/GROUP BY is required (Tom)
   Allocate large memory requests in fix-sized chunks for 
    performance (Tom)
   Fix vacuum's performance reducing memory requests (Tom)
   Implement constant-expression simplification
    (Bernard Frankpitt, Tom)
   Use secondary columns to be used to determine start of index 
    scan (Hiroshi)
   Prevent quadruple use of disk space when sorting (Tom)
   Faster sorting by calling fewer functions (Tom)
   Create system indexes to match all system caches
    (Bruce, Hiroshi)
   Make system caches use system indexes (Bruce)
   Make all system indexes unique (Bruce)
   Improve pg_statistics management to help VACUUM speed (Tom)
   Flush backend cache less frequently (Tom, Hiroshi)
   COPY now reuses previous memory allocation, improving 
    performance (Tom)
   Improve optimization cost estimation (Tom)
   Improve optimizer estimate of range queries
    (x > lowbound AND x < highbound) (Tom)
   Use DNF instead of CNF where appropriate (Tom, Taral)
   Further cleanup for OR-of-AND WHERE-clauses (Tom)
   Make use of index in OR clauses
    (x = 1 AND y = 2) OR (x = 2 AND y = 4) (Tom)
   Smarter optimizer for random index page access (Tom)
   New SET variable to control optimizer costs (Tom)
   Optimizer queries based on LIMIT, OFFSET, and EXISTS 
    qualifications (Tom)
   Reduce optimizer internal housekeeping of join paths for 
    speedup (Tom)
   Major subquery speedup (Tom)
   Fewer fsync writes when fsync is not disabled (Tom)
   Improved LIKE optimizer estimates (Tom)
   Prevent fsync in SELECT-only queries (Vadim)
   Index creation uses psort, since psort now faster (Tom)
   Allow creation of sort temp tables > 1 Gig

   Source Tree Changes
   -------------------
   Fix for linux PPC compile
   New generic expression-tree-walker subroutine (Tom)
   Change form() to varargform() to prevent portability problems
   Improved range checking for large integers on Alphas
   Clean up #include in /include directory (Bruce)
   Add scripts for checking includes (Bruce)
   Remove un-needed #include's from *.c files (Bruce)
   Change #include's to use <> and "" as appropriate (Bruce)
   Enable WIN32 compilation of libpq
   Alpha spinlock fix from Uncle George (gatgul@@voicenet.com)
   Overhaul of optimizer data structures (Tom)
   Fix to cygipc library (Yutaka Tanida)
   Allow pgsql to work on newer Cygwin snapshots (Dan)
   New catalog version number (Tom)
   Add Linux ARM
   Rename heap_replace to heap_update
   Update for QNX (Dr. Andreas Kardos)
   New platform-specific regression handling (Tom)
   Rename oid8 -> oidvector and int28 -> int2vector (Bruce)
   Included all yacc and lex files into the distribution (Peter E.)
   Remove lextest, no longer needed (Peter E)
   Fix for libpq and psql on Win32 (Magnus)
   Change datetime and timespan into timestamp and interval (Thomas)
   Fix for plpgsql on BSDI
   Add SQL_ASCII test case to the regression test (Tatsuo)
   configure --with-mb now deprecated (Tatsuo)
   NT fixes
   NetBSD fixes Johnny C. Lam (lamj@@stat.cmu.edu)
   Fixes for Alpha compiles
   New multibyte encodings           

Chapter 6. Regression Test


       Regression test instructions and analysis. 

       The PostgreSQL regression tests are a comprehensive set of 
      tests for the SQL implementation embedded in PostgreSQL. They 
      test standard SQL operations as well as the extended 
      capabilities of PostgreSQL. 
       There are two different ways in which the regression tests can 
      be run: the "sequential" method and the "parallel" method. The 
      sequential method runs each test script in turn, whereas the 
      parallel method starts up multiple server processes to run 
      groups of tests in parallel. Parallel testing gives confidence 
      that interprocess communication and locking are working 
      correctly. Another key difference is that the sequential test 
      procedure uses an already-installed postmaster, whereas the 
      parallel test procedure tests a system that has been built but 
      not yet installed. (The parallel test script actually does an 
      installation into a temporary directory and fires up a private 
      postmaster therein.) 
       Some properly installed and fully functional PostgreSQL 
      installations can "fail" some of these regression tests due to 
      artifacts of floating point representation and time zone 
      support. The tests are currently evaluated using a simple diff 
      comparison against the outputs generated on a reference system, 
      so the results are sensitive to small system differences. When 
      a test is reported as "failed", always examine the differences 
      between expected and actual results; you may well find that the 
      differences are not significant. 
       The regression tests were originally developed by Jolly Chen 
      and Andrew Yu, and were extensively revised/repackaged by Marc 
      Fournier and Thomas Lockhart. From PostgreSQL v6.1 onward the 
      regression tests are current for every official release. 

Regression Environment


       The regression testing notes below assume the following 
      (except where noted): 
      o   Commands are Unix-compatible. See note below. 
      o   Defaults are used except where noted. 
      o   User postgres is the Postgres superuser. 
      o   The source path is /usr/src/pgsql (other paths are 
        possible). 
      o   The runtime path is /usr/local/pgsql (other paths are 
        possible). 
       
       Normally, the regression tests should be run as the postgres 
      user since the 'src/test/regress' directory and sub-directories 
      are owned by the postgres user. If you run the regression test 
      as another user the 'src/test/regress' directory tree must be 
      writeable by that user. 
       It was formerly necessary to run the postmaster with system 
      time zone set to PST, but this is no longer required. You can 
      run the regression tests under your normal postmaster 
      configuration. The test script will set the PGTZ environment 
      variable to ensure that timezone-dependent tests produce the 
      expected results. However, your system must provide library 
      support for the PST8PDT time zone, or the timezone-dependent 
      tests will fail. To verify that your machine does have this 
      support, type the following: 

      setenv TZ PST8PDT
      date
          

       
       The "date" command above should have returned the current 
      system time in the PST8PDT time zone. If the PST8PDT database 
      is not available, then your system may have returned the time 
      in GMT. If the PST8PDT time zone is not available, you can set 
      the time zone rules explicitly: 

      setenv PGTZ PST8PDT7,M04.01.0,M10.05.03
          

       
       The directory layout for the regression test area is: 

      Table 6-1. Directory Layout
      Directory  Description
      input       Source files that are converted using make all 
                 into some of the .sql files in the sql 
                 subdirectory. 
      output      Source files that are converted using make all 
                 into .out files in the expected subdirectory. 
      sql         .sql files used to perform the regression tests. 
      expected    .out files that represent what we expect the 
                 results to look like. 
      results     .out files that contain what the results actually 
                 look like. Also used as temporary storage for table 
                 copy testing. 
      tmp_check   Temporary installation created by parallel testing 
                 script. 


       

Regression Test Procedure


       Commands were tested on RedHat Linux version 4.2 using the 
      bash shell. Except where noted, they will probably work on most 
      systems. Commands like ps and tar vary wildly on what options 
      you should use on each platform. Use common sense before typing 
      in these commands. 

      Postgres Regression Test
      1.  Prepare the files needed for the regression test with: 
                     cd /usr/src/pgsql/src/test/regress
                     gmake clean
                     gmake all
                   
          You can skip "gmake clean" if this is the first time you 
         are running the tests. 
          This step compiles a C program with PostgreSQL extension 
         functions into a shared library. Localized SQL scripts and 
         output-comparison files are also created for the tests that 
         need them. The localization replaces macros in the source 
         files with absolute pathnames and user names. 
      2.  If you intend to use the "sequential" test procedure, which 
         tests an already-installed postmaster, be sure that the 
         postmaster is running. If it isn't already running, start 
         the postmaster in an available window by typing 
                postmaster
                   
          or start the postmaster daemon running in the background by 
         typing 
               cd
                     nohup postmaster > regress.log 2>&1 &
                   
          The latter is probably preferable, since the regression 
         test log will be quite lengthy (60K or so, in Postgres 7.0) 
         and you might want to review it for clues if things go 
         wrong. 

         Note: Do not run postmaster from the root account.

          
      3.  Run the regression tests. For a sequential test, type 
                    cd /usr/src/pgsql/src/test/regress
                     gmake runtest
                   
          For a parallel test, type 
                cd /usr/src/pgsql/src/test/regress
                     gmake runcheck
                   
          The sequential test just runs the test scripts using your 
         already-running postmaster. The parallel test will perform a 
         complete installation of Postgres into a temporary 
         directory, start a private postmaster therein, and then run 
         the test scripts. Finally it will kill the private 
         postmaster (but the temporary directory isn't removed 
         automatically). 
      4.  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 can be 
         normal for some of the tests to "fail" due to 
         platform-specific variations. See the next section for 
         details on determining whether a "failure" is significant. 
          Some of the tests, notably "numeric", can take a while, 
         especially on slower platforms. Have patience. 
      5.  After running the tests and examining the results, type 
                  cd /usr/src/pgsql/src/test/regress
                     gmake clean
                   
          to recover the temporary disk space used by the tests. If 
         you ran a sequential test, also type 
                   dropdb regression
                   
          

Regression Analysis


       The actual outputs of the regression tests are in files in the 
      ./results directory. The test script uses diff to compare each 
      output file against the reference outputs stored in the 
      ./expected directory. Any differences are saved for your 
      inspection in ./regression.diffs. (Or you can run diff 
      yourself, if you prefer.) 
       The files might not compare exactly. The test script will 
      report any difference as a "failure", but the difference might 
      be due to small cross-system differences in error message 
      wording, math library behavior, etc. "Failures" of this type do 
      not indicate a problem with Postgres. 
       Thus, it is necessary to examine the actual differences for 
      each "failed" test to determine whether there is really a 
      problem. The following paragraphs attempt to provide some 
      guidance in determining whether a difference is significant or 
      not. 

Error message differences


       Some of the regression tests involve intentional invalid input 
      values. Error messages can come from either the Postgres code 
      or from the host platform system routines. In the latter case, 
      the messages may vary between platforms, but should reflect 
      similar information. These differences in messages will result 
      in a "failed" regression test which can be validated by 
      inspection. 

Date and time differences


       Most of the date and time results are dependent on timezone 
      environment. The reference files are generated for timezone 
      PST8PDT (Berkeley, California) and there will be apparent 
      failures if the tests are not run with that timezone setting. 
      The regression test driver sets environment variable PGTZ to 
      PST8PDT to ensure proper results. 
       Some of the queries in the "timestamp" test will fail if you 
      run the test on the day of a daylight-savings time changeover, 
      or the day before or after one. These queries assume that the 
      intervals between midnight yesterday, midnight today and 
      midnight tomorrow are exactly twenty-four hours ... which is 
      wrong if daylight-savings time went into or out of effect 
      meanwhile. 
       There appear to be some systems which do not accept the 
      recommended syntax for explicitly setting the local time zone 
      rules; you may need to use a different PGTZ setting on such 
      machines. 
       Some systems using older timezone libraries fail to apply 
      daylight-savings corrections to pre-1970 dates, causing 
      pre-1970 PDT times to be displayed in PST instead. This will 
      result in localized differences in the test results. 

Floating point differences


       Some of the tests involve computing 64-bit (float8) numbers 
      from table columns. Differences in results involving 
      mathematical functions of float8 columns have been observed. 
      The float8 and geometry tests are particularly prone to small 
      differences across platforms. Human eyeball comparison is 
      needed to determine the real significance of these differences 
      which are usually 10 places to the right of the decimal point. 
       Some systems signal errors from pow() and exp() differently 
      from the mechanism expected by the current Postgres code. 

Polygon differences


       Several of the tests involve operations on geographic date 
      about the Oakland/Berkley CA street map. The map data is 
      expressed as polygons whose vertices are represented as pairs 
      of float8 numbers (decimal latitude and longitude). Initially, 
      some tables are created and loaded with geographic data, then 
      some views are created which join two tables using the polygon 
      intersection operator (##), then a select is done on the view. 
      When comparing the results from different platforms, 
      differences occur in the 2nd or 3rd place to the right of the 
      decimal point. The SQL statements where these problems occur 
      are the following: 

          QUERY: SELECT * from street;
                QUERY: SELECT * from iexit;
              

       

Random differences


       There is at least one case in the "random" test script that is 
      intended to produce random results. This causes random to fail 
      the regression test once in a while (perhaps once in every five 
      to ten trials). Typing 

               diff results/random.out expected/random.out
              

       should produce only one or a few lines of differences. You 
      need not worry unless the random test always fails in repeated 
      attempts. (On the other hand, if the random test is never 
      reported to fail even in many trials of the regress tests, you 
      probably should worry.) 

The "expected" files


       The ./expected/*.out files were adapted from the original 
      monolithic expected.input file provided by Jolly Chen et al. 
      Newer versions of these files generated on various development 
      machines have been substituted after careful (?) inspection. 
      Many of the development machines are running a Unix OS variant 
      (FreeBSD, Linux, etc) on Ix86 hardware. The original 
      expected.input file was created on a SPARC Solaris 2.4 system 
      using the postgres5-1.02a5.tar.gz source tree. It was compared 
      with a file created on an I386 Solaris 2.4 system and the 
      differences were only in the floating point polygons in the 3rd 
      digit to the right of the decimal point. The original 
      sample.regress.out file was from the postgres-1.01 release 
      constructed by Jolly Chen. It may have been created on a DEC 
      ALPHA machine as the Makefile.global in the postgres-1.01 
      release has PORTNAME=alpha. 

Platform-specific comparison files


       Since some of the tests inherently produce platform-specific 
      results, we have provided a way to supply platform-specific 
      result comparison files. Frequently, the same variation applies 
      to multiple platforms; rather than supplying a separate 
      comparison file for every platform, there is a mapping file 
      that defines which comparison file to use. So, to eliminate 
      bogus test "failures" for a particular platform, you must 
      choose or make a variant result file, and then add a line to 
      the mapping file, which is "resultmap". 
       Each line in the mapping file is of the form 

                  testname/platformnamepattern=comparisonfilename
              

       The test name is just the name of the particular regression 
      test module. The platform name pattern is a pattern in the 
      style of expr(1) (that is, a regular expression with an 
      implicit ^ anchor at the start). It is matched against the 
      platform name as printed by config.guess. The comparison file 
      name is the name of the substitute result comparison file. 
       For example: the int2 regress test includes a deliberate entry 
      of a value that is too large to fit in int2. The specific error 
      message that is produced is platform-dependent; our reference 
      platform emits 

          ERROR:  pg_atoi: error reading "100000": Numerical result 
      out of range
              

       but a fair number of other Unix platforms emit 

          ERROR:  pg_atoi: error reading "100000": Result too large
              

       Therefore, we provide a variant comparison file, 
      int2-too-large.out, that includes this spelling of the error 
      message. To silence the bogus "failure" message on HPPA 
      platforms, resultmap includes 

                 int2/hppa=int2-too-large
              

       which will trigger on any machine for which config.guess's 
      output begins with 'hppa'. Other lines in resultmap select the 
      variant comparison file for other platforms where it's 
      appropriate. 
@


1.73
log
@Update readme for 7.0.
@
text
@a0 1
     Installation instructions for PostgreSQL 7.0.
d2 183
a184 2
If you haven't gotten the PostgreSQL distribution, get it from
ftp.postgresql.org, then unpack it:
d186 1
a186 3
gunzip postgresql-7.0.tar.gz
tar -xf postgresql-7.0.tar
mv postgresql-7.0 /usr/src
a189 35
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 noticable 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.
d191 38
a231 1
PostgreSQL Installation
d233 1413
a1645 309
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 and therefore won't be allowed.

     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. If you are not upgrading an existing system then skip to step 4.

     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. However, do not use the pg_dumpall script from 6.0
     or everything will be owned by the PostgreSQL super user. In that case
     you should grab pg_dumpall from a later 6.x.x release. 7.0's pg_dumpall
     will not work on older databases. 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.

                                        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.
  3. If you are upgrading an existing system then 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 which 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.

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

     mv /usr/local/pgsql /usr/local/pgsql.old

     or replace your particular paths.

  4. 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. Please note that the Perl interface
          will be installed into the usual place for Perl modules (typically
          under /usr/lib/perl), so you must have root access to use this
          option successfully.

     --with-odbc

          Builds the ODBC driver package.

     --with-tcl

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

  5. Compile the program. Type

     gmake

     The compilation process can take anywhere from 10 minutes to an hour.
     Your milage 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.

  6. Install the program. Type

     gmake install

  7. Tell your system how to find the new shared libraries. How to do this
     varies between platforms. What tends to work everywhere 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.

  8. Create the database installation. 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) 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.)

  9. The previous step should have told you how to start up the database
     server. Do so now.

     /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, use the -S.

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

   * Life will be more convenient if you set up some enviroment 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/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. The regression tests are a test suite to
     verify that PostgreSQL runs on your machine in the way the developers
     expected it to. You should definitely do this before putting a server
     into production use. The file
     /usr/src/pgsql/postgresql-7.0/src/test/regress/README has detailed
     instructions for running and interpreting the regression tests.

To start "playing around", 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 and start
experimenting.
@


1.72
log
@Added bug reporting guidelines
Some corrections in installation procedure
@
text
@d224 1
a224 1
     /usr/local/pgsql/initdb -D /usr/local/pgsql/data
@


1.71
log
@updated install file
updated date/time types doc
fixed small psql bug
removed libpq code that lower-cased db names
make notice when long identifier is truncated
@
text
@a2 5
Commands were tested on RedHat Linux version 5.2 using the bash shell.
Except where noted, they will probably work on most systems. Commands like
ps and tar may vary wildly between platforms on what options you should use.
Use common sense before typing in these commands.

d6 3
a8 5
$ gunzip postgresql-7.0.tar.gz
$ tar -xf postgresql-7.0.tar
$ mv postgresql-7.0 /usr/src

Again, these commands might differ on your system.
d18 1
a18 1
$ gmake --version
d42 1
a42 1
$ df -k
d73 1
a73 1
     $ pg_dumpall > db.out
a91 1

d95 3
a97 1
     $ ps ax | grep postmaster
d99 5
a103 2
     This should list the process numbers for a number of processes, similar
     to this:
d112 1
a112 1
     $ kill pid
d119 1
a119 1
          $ /etc/rc.d/init.d/postgres.init stop
d125 1
a125 1
     $ mv /usr/local/pgsql /usr/local/pgsql.old
d134 1
a134 1
     $ ./configure
d176 1
a176 1
     $ gmake
d179 1
a179 1
     Your milage will most certainly vary.
a184 2
     Remember, "gmake" may be called "make" on your system.

d187 1
a187 1
     $ gmake install
d193 4
a196 2
     $ LD_LIBRARY_PATH=/usr/local/pgsql/lib
     $ export LD_LIBRARY_PATH
d198 4
a201 2
     You might want to put this into a shell startup file such as
     ~/.bash_profile.
d213 1
a213 1
     ./psql: error in loading shared libraries
d221 4
a224 4
     $ mkdir /usr/local/pgsql/data
     $ chown postgres /usr/local/pgsql/data
     $ su - postgres
     $ /usr/local/pgsql/initdb -D /usr/local/pgsql/data
d237 1
a237 1
     $ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d245 1
a245 1
     $ /usr/local/pgsql/bin/psql < db.out
d268 2
a269 2
     $ cd /usr/src/pgsql/postgresql-7.0/doc
     $ gmake install
d283 2
a284 2
     $ cd /usr/local/pgsql/doc
     $ gunzip -c user.ps.tz | lpr
d289 1
a289 6
     $ 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
d291 2
a292 1
     If in doubt, confer your manuals or your local expert.
d350 12
@


1.70
log
@Rename 7.0.0 to 7.0 to be consistent with prior release numbering.
@
text
@a0 6
Chapter 0. Installation

Table of Contents
Before you start
Installation Procedure

a54 1
---------------------------------------------------------------------------
d75 1
a75 1
  2. If you are not upgrading an existing system then skip to .
d99 1
d137 1
a137 1
     $ ./configure [ options ]
d139 3
a141 1
     For a complete list of options, type:
d143 1
a143 1
          ./configure --help
d230 4
a233 1
     write to it (or create it) before starting initdb.
d238 1
a238 1
     $ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data
d272 6
a277 1
     This will install files under /usr/local/pgsql/doc.
@


1.69
log
@Update install file for 7.0 to match new SGML version.
@
text
@d7 1
a7 1
     Installation instructions for PostgreSQL 7.0.0.
d17 3
a19 3
$ gunzip postgresql-7.0.0.tar.gz
$ tar -xf postgresql-7.0.0.tar
$ mv postgresql-7.0.0 /usr/src
d270 1
a270 1
     $ cd /usr/src/pgsql/postgresql-7.0.0/doc
d349 1
a349 1
     /usr/src/pgsql/postgresql-7.0.0/src/test/regress/README has detailed
@


1.68
log
@Added new pg_id to fix initdb problems
New INSTALL file
Fixed a copyright notice
@
text
@d1 6
d61 1
d82 1
a82 1
  2. If you are not upgrading an existing system then skip to step 4.
a105 1

@


1.67
log
@
There is one section that changed, concernign startup...the rest is just
changes for v6.5->v6.5.1, so relatively harmless
@
text
@d1 1
d3 4
a6 2
PostgreSQL Installation Guide
by The PostgreSQL Development Team
d8 2
a9 2
PostgreSQL is  1998-9 by the Postgres Global Development Group.
Table of Contents
d11 3
a13 238
       Summary                                            
       1. Introduction                                    
       2. Ports                                           
          Currently Supported Platforms                   
          Unsupported Platforms                           
       3. Installation                                    
          Requirements to Run Postgres                    
          Installation Procedure                          
          Playing with Postgres                           
          The Next Step                                   
          Porting Notes                                   
       4. Configuration Options                           
          Parameters for Configuration (configure)        
          Parameters for Building (make)                  
          Locale Support                                  
             What are the Benefits?                       
             What are the Drawbacks?                      
          Kerberos Authentication                         
             Availability                                 
             Installation                                 
             Operation                                    
       5. Release Notes                                   
          Release 6.5.1                                   
             Migration to v6.5.1                          
             Detailed Change List                         
          Release 6.5                                     
             Migration to v6.5                            
                 Multi-Version Concurrency Control        
             Detailed Change List                         

Summary

       Postgres, developed originally in the UC Berkeley 
       Computer Science Department, pioneered many of the 
       object-relational concepts now becoming available in 
       some commercial databases. It provides SQL92/SQL3 
       language support, transaction integrity, and type 
       extensibility. PostgreSQL is a public-domain, open 
       source descendant of this original Berkeley code.

Chapter 1. Introduction

       This installation procedure makes some assumptions 
       about the desired configuration and runtime 
       environment for your system. This may be adequate for 
       many installations, and is almost certainly adequate 
       for a first installation. But you may want to do an 
       initial installation up to the point of unpacking the 
       source tree and installing documentation, and then 
       print or browse the Administrator's Guide.

Chapter 2. Ports

        This manual describes version 6.5.1 of Postgres. The 
       Postgres developer community has compiled and tested 
       Postgres on a number of platforms. Check the web site 
       (http://www.postgresql.org/docs/admin/ports.htm) for 
       the latest information. 

Currently Supported Platforms

        At the time of publication, the following platforms 
       have been tested: 

       Table 2-1. Supported Platforms
       OS          Processor   Version    Reported    Remarks
       AIX 4.3.2   RS6000      v6.5       1999-05-26  (Andreas Zeugswetter 
                                       (mailto:Andreas.Zeugswetter@@telecom.at))
       BSDI        x86         v6.5       1999-05-25  (Bruce Momjian 
                                          (mailto:maillist@@candle.pha.pa.us)
       FreeBSD     x86         v6.5       1999-05-25  (Tatsuo Ishii 
       2.2.x-4.0                          (mailto:t-ishii@@sra.co.jp), 
                                          Marc Fournier
                                          (mailto:scrappy@@hub.org))
       DGUX        m88k        v6.3       1998-03-01  v6.4 probably OK.
       5.4R4.11                           Needs new maintainer.
                                          (Brian E Gallew 
                                          (mailto:geek+@@cmu.edu))
       Digital     Alpha       v6.4       1998-10-29  Minor patchable problems 
       Unix 4.0                                       (Pedro J. Lobo 
                                          (mailto:pjlobo@@euitt.upm.es))
       HPUX        PA-RISC     v6.4       1998-10-25  Both 9.0x and 10.20
                                          (Tom Lane (mailto:tgl@@sss.pgh.pa.us), 
                                           Stan Brown (mailto:stanb@@awod.com))
       IRIX 6.5    MIPS        v6.4       1998-12-29  IRIX 5.x is different
                                          (Mark Dalphin (mdalphin@@amgen.com))
       linux       Alpha       v6.3.2     1998-04-16  Mostly successful. Needs 
       2.0.x                                          work for v6.4.
                                          (Ryan Kirkpatrick 
                                       (mailto:rkirkpat@@nag.cs.colorado.edu))
       linux       x86         v6.4       1998-10-27  (Thomas Lockhart 
       2.0.x/libc5                        (mailto:lockhart@@alumni.caltech.edu))
       linux       x86         v6.4       1999-05-24  (Thomas Lockhart 
       2.0.x/glibc2                       (mailto:lockhart@@alumni.caltech.edu))
       linux       MIPS        v6.4       1998-12-16  Cobalt Qube (Tatsuo Ishii 
       2.0.x                              (mailto:t-ishii@@sra.co.jp))
       linux       Sparc       v6.4       1998-10-25  (Tom Szybist 
       2.0.x                              (mailto:szybist@@boxhill.com))
       linuxPPC    PPC603e     v6.4       1998-10-26  Powerbook 2400c
       2.1.24                                         (Tatsuo Ishii 
                                          (mailto:t-ishii@@sra.co.jp))
       mklinux     PPC750      v6.4       1998-09-16  PowerMac 7600
       DR3                                (Tatsuo Ishii
                                          (mailto:t-ishii@@sra.co.jp))
       NetBSD      arm32       v6.5       1999-04-14  (Andrew McMurry 
                                      (mailto:a.mcmurry1@@physics.oxford.ac.uk))
       NetBSD/i3-  x86         v6.4       1998-10-25  (Brook Milligan 
       86 1.3.2                           (mailto:brook@@trillium.NMSU.Edu))
       NetBSD      m68k        v6.4.2     1998-12-28  Mac SE/30 (Mr. Mutsuki 
                                                      Nakajima, Tatsuo Ishii 
                                          (mailto:t-ishii@@sra.co.jp))
       NetBSD-     NS32532     v6.4       1998-10-27  small problems
       current                            in date/time math (Jon Buller 
                                          (mailto:jonb@@metronet.com))
       NetBSD/sp-  Sparc       v6.4       1998-10-27  (Tom I Helbekkmo 
       arc 1.3H                           (mailto:tih@@hamartun.priv.no))
       NetBSD 1.3  VAX         v6.3       1998-03-01  (Tom I Helbekkmo 
                                          (mailto:tih@@hamartun.priv.no))
       SCO         x86         v6.5       1999-05-25  (Andrew Merrill 
       OpenServer 5                       (mailto:andrew@@compclass.com))
       SCO         x86         v6.5       1999-05-25  (Andrew Merrill 
       UnixWare 7                         (mailto:andrew@@compclass.com))
       Solaris     x86         v6.4       1998-10-28  (Marc Fournier 
                                          (mailto:scrappy@@hub.org))
       Solaris     Sparc       v6.4       1998-10-28  (Tom Szybist 
       2.6-2.7                            (mailto:szybist@@boxhill.com),
                                           Frank Ridderbusch 
                                          (mailto:ridderbusch.pad@@sni.de))
       SunOS       Sparc       v6.3       1998-03-01  Patches submitted
       4.1.4                              (Tatsuo Ishii 
                                          (mailto:t-ishii@@sra.co.jp))
       SVR4        MIPS        v6.4       1998-10-28  No 64-bit int compiler 
                                          support (Frank Ridderbusch 
                                          (mailto:ridderbusch.pad@@sni.de))
       Windows     x86         v6.4       1999-01-06  Client-side libraries
                                          or ODBC/JDBC. No server yet. 
                                          (Magnus Hagander 
                                          (mha@@sollentuna.net)
       Windows NT  x86         v6.5       1999-05-26  Working with the Cygwin 
                                          library. (Daniel Horak 
                                          (mailto:Dan.Horak@@email.cz)) 


        
        Platforms listed for v6.3.x and v6.4.x should also 
       work with v6.5.1, but we did not receive explicit 
       confirmation of such at the time this list was 
       compiled. 

         Note: For Windows NT, the server-side port of 
         Postgres has recently been accomplished. The 
         Cygnus library is required to compile it.

Unsupported Platforms

        There are a few platforms which have been attempted 
       and which have been reported to not work with the 
       standard distribution. Others listed here do not 
       provide sufficient library support for an attempt. 

       Table 2-2. Possibly Incompatible Platforms
       OS          Processor   Version    Reported    Remarks
       MacOS       all         v6.3       1998-03-01  Not library compatible; 
                                          use ODBC/JDBC
       NextStep    x86         v6.x       1998-03-01  Client-only support; 
                                          v1.0.9 worked with patches 
                                          (David Wetzel 
                                          (mailto:dave@@turbocat.de))
       SVR4 4.4    m88k        v6.2.1     1998-03-01  Confirmed
                                          with patching; 
                                          v6.4.x will need TAS 
                                          spinlock code (Doug 
                                          Winterburn 
                                          (mailto:dlw@@seavme.xroads.com))
       Ultrix      MIPS,VAX?   v6.x       1998-03-01  No recent reports; 
                                                      obsolete?


Chapter 3. Installation

        Complete installation instructions for Postgres 
       v6.5.1. 

        Before installing Postgres, you may wish to visit 
       www.postgresql.org (http://www.postgresql.org) for up 
       to date information, patches, etc. 
        These installation instructions assume: 
       o  Commands are Unix-compatible. See note below. 
       o  Defaults are used except where noted. 
       o  User postgres is the Postgres superuser. 
       o  The source path is /usr/src/pgsql (other paths are 
        possible). 
       o  The runtime path is /usr/local/pgsql (other paths 
        are possible). 
        
        Commands were tested on RedHat Linux version 5.2 
       using the tcsh shell. Except where noted, they will 
       probably work on most systems. Commands like ps and 
       tar may vary wildly between platforms on what options 
       you should use. Use common sense before typing in 
       these commands. 
        Our Makefiles require GNU make (called ?gmake? in this 
       document). They will not work with non-GNU make 
       programs. If you have GNU make installed under the 
       name ?make? instead of ?gmake?, then you will use the 
       command make instead. That's OK, but you need to have 
       the GNU form of make to succeed with an installation. 

Requirements to Run Postgres

        Up to date information on supported platforms is at 
       http://www.postgresql.org/docs/admin/install.htm 
       (http://www.postgresql.org/docs/admin/install.htm). 
       In general, most Unix-compatible platforms with 
       modern libraries should be able to run Postgres. 
        Although the minimum required memory for running 
       Postgres 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. 
        Check that you have sufficient disk space. You will 
       need about 30 Mbytes for /usr/src/pgsql, about 5 
       Mbytes for /usr/local/pgsql (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. 
        We therefore recommend that during installation and 
       testing you have well over 20 Mbytes free under 
       /usr/local 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 /usr/local/pgsql, 1 Mbyte 
       for the empty database, plus about five times the 
       space you would require to store your database data 
       in a flat file. 
        To check for disk space, use 
d15 39
a53 2
       $ df -k
           
a54 1
        
d58 276
a333 1392
       Postgres Installation
       For a fresh install or upgrading from previous 
       releases of Postgres:
       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.
          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 
         Postgres 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 ftp://ftp.postgresql.org/pub/INSTALL.
       2. Create the Postgres superuser account (postgres is 
         commonly used) if it does not already exist.
         The owner of the Postgres files can be any 
         unprivileged user account. It must not be root, 
         bin, or any other account with special access 
         rights, as that would create a security risk.
       3. Log in to the Postgres superuser account. Most of 
         the remaining steps in the installation will 
         happen in this account.
       4. Ftp file 
         ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.tar.gz 
         from the Internet. Store it in your home 
         directory.
       5. Some platforms use flex. If your system uses flex 
         then make sure you have a good version. To check, 
         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 
         Postgres.
         You may want to do the entire flex 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: 
         $ 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
          This will update files /usr/man/man1/flex.1, 
         /usr/bin/flex, /usr/lib/libfl.a, 
         /usr/include/FlexLexer.h and will add a link 
         /usr/bin/flex++ which points to flex.
       6. If you are not upgrading an existing system then 
         skip to step 9. If you are upgrading from 6.5, you
         do not need to dump/reload or initdb. Simply
         compile the source code, stop the postmaster, do a
         "make install", and restart the postmaster.
         If you are upgrading from 6.4.* or earlier,
         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. 

            Tip: Do not use the pg_dumpall script from v6.0 
            or everything will be owned by the Postgres 
            super user.

         To dump your fairly recent post-v6.0 database 
         installation, type 
         $ pg_dumpall > db.out
         To use the latest pg_dumpall script on your 
         existing older database before upgrading Postgres, 
         pull the most recent version of pg_dumpall from 
         the new distribution: 
         $ cd
         $ gunzip -c postgresql-v6.5.1.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 > db.out
         $ rm -rf src
          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.
          If the pg_dumpall command seems to take a long 
         time and you think it might have died, then, from 
         another terminal, type 
         $ ls -l db.out
          several times to see if the size of the file is 
         growing.
          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 the release notes which should 
         cover any release-specific issues.

                                 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.



       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 pid 
         replaced by the process id for process postmaster. 
         (Do not use the id for process "grep postmaster".) 
         Type 
         $ kill pid
         to actually stop the process. 

         Tip: On systems which have Postgres 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 
            $ /etc/rc.d/init.d/postgres.init stop
            to halt Postgres.

       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. The 
         actual paths can be different for your 
         installation but you must be consistent throughout 
         this procedure.

            Note: 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 
            gmake install stage of installation.

          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.5.1.tar.gz | tar xvf -
       11.     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 
         $ cd /usr/src/pgsql/src
         $ ./configure [ options ]
            a. 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 --with-template=TEMPLATE option to 
              make the right file be chosen. 

               Please Report Problems: If your system is not 
                 automatically recognized by configure and 
                 you have to do this, please send email to 
                 scrappy@@hub.org (mailto:scrappy@@hub.org) 
                 with the output of the program 
                 ./config.guess. Indicate what the template 
                 file should be.

            b. Choose configuration options. Check 
              Configuration Options 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 
                   ./configure --help
               Some of the more commonly used ones are: 
                     --prefix=BASEDIR   Selects a different 
              base directory for the
                                        installation of the 
              Postgres 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.)
            c. Here is the configure script used on a Sparc 
              Solaris 2.5 system with /opt/postgres 
              specified as the installation base directory: 
              $ ./configure --prefix=/opt/postgres \
                  --with-template=sparc_solaris-gcc 
              --with-pgport=5432 \
                  --enable-hba --disable-locale

               Tip: Of course, you may type these three 
                 lines all on the same line.

       12.     Install the man and HTML documentation. Type 
         $ cd /usr/src/pgsql/doc
         $ gmake install
         The documentation is also available in Postscript 
         format. Look for files ending with .ps.gz in the 
         same directory.
       13.     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.
         Remember, ?gmake? may be called ?make? on your system. 
         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: 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 a message stating that 
         the flex command cannot be found then install flex 
         as described earlier. Next, change directory back 
         to this directory, type 
         $ gmake clean
         then recompile again.
          Compiler options, such as optimization and 
         debugging, may be specified on the command line 
         using the COPT variable. For example, typing 
         $ gmake COPT="-g" all >& make.log &
          would invoke your compiler's -g option in all 
         steps of the build. See src/Makefile.global.in for 
         further details.
       14.     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. Remember, ?gmake? may 
         be called ?make? on your system.
       15.     If necessary, tell your system how to find 
         the new shared libraries. You can do one of the 
         following, preferably the first:
            a. As root, edit file /etc/ld.so.conf. Add a 
              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.
       16.     If you used the --with-perl 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 su) and doing 
               $ cd /usr/src/pgsql/src/interfaces/perl5
               $ gmake install
              
          
       17.     If it has not already been done, then prepare 
         account postgres for using Postgres. Any account 
         that will use Postgres must be similarly prepared. 
          There are several ways to influence the runtime 
         environment of the Postgres server. Refer to the 
         Administrator's Guide for more information. 

            Note: The following instructions are for a 
            bash/sh shell. Adapt accordingly for other 
            shells.

          
            a. Add the following lines to your login 
              environment: shell, ~/.bash_profile: 
                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
                     
               
            b. Several regression tests could fail if the 
              user's locale collation scheme is different 
              from that of standard C locale. 
               If you configure and compile Postgres with 
              the --enable-locale option then set locale 
              environment to C (or unset all LC_* 
              variables) by putting these additional lines 
              to your login environment before starting 
              postmaster: 
                      LC_COLLATE=C
                      LC_CTYPE=C
                      LC_COLLATE=C
                      export LC_COLLATE LC_CTYPE LC_COLLATE
                     
               
                      
                     
               
            c. 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
                     
               
       18.     Create the database installation from your 
         Postgres superuser account (typically account 
         postgres). Do not do the following as root! This 
         would be a major security hole. Type 
         $ initdb
       19.     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 finished. If you are upgrading from v6.0 or 
         later you can copy file pg_hba.conf from your old 
         database on top of the one in your new database, 
         rather than redoing the file from scratch.
       20.     Briefly test that the backend will start and 
         run by running it from the command line.
            a. Start the postmaster daemon running in the 
              background by typing 
              $ cd
              $ nohup postmaster -i > pgserver.log 2>&1 &
            b. Create a database by typing 
              $ createdb
            c. Connect to the new database: 
              $ psql
            d. And run a sample query: 
              postgres=> SELECT datetime 'now';
            e. Exit psql: 
              postgres=> \q
            f. Remove the test database (unless you will 
              want to use it later for other tests): 
              $ destroydb
       21.     Run postmaster in the background from your 
         Postgres superuser account (typically account 
         postgres). Do not run postmaster from the root 
         account!
         Usually, you will want to modify your computer so 
         that it will automatically start postmaster 
         whenever it boots. It is not required; the 
         Postgres server can be run successfully from 
         non-privileged accounts without root intervention.
          Here are some suggestions on how to do this, 
         contributed by various users.
          Whatever you do, postmaster must be run by the 
         Postgres superuser (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. 
         o  If you are installing from a non-privileged 
           account and have no root access, then start the 
           postmaster and send it to the background: 
           $ cd
           $ nohup postmaster > regress.log 2>&1 &
         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.
         o  In RedHat Linux edit file /etc/inittab to add the 
           following as a 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.)
       22.     Run the regression tests. The file 
         /usr/src/pgsql/src/test/regress/README has 
         detailed instructions for running and interpreting 
         the regression tests. A short version follows 
         here:
            a. 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 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 Postgres. 
              The file ./regression.diffs 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.
              For example, 
              o   For a i686/Linux-ELF platform, no tests 
                failed since this is the v6.5 regression 
                testing reference platform.
               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 int8 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.
               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 Postgres. The regression 
              tests are a helpful tool, but they may 
              require some study to be useful.
               After running the regression tests, type 
              $ destroydb regression
              $ cd /usr/src/pgsql/src/test/regress
              $ gmake clean
               to recover the disk space used for the 
              tests. (You may want to save the 
              regression.diffs file in another place before 
              doing this.)
       23.     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:

         Minimal Backup Procedure
         1.    Run the SQL command VACUUM. This will clean 
            up your database.
         2.    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.

          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 crontab 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.)
       24.     If you are upgrading an existing system then 
         reinstall your old database. Type 
         $ cd
         $ psql -e template1 < db.out
          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) 
         UPDATE FirstTable SET PathCol = 
         UpgradePath(PathCol);
         UPDATE SecondTable SET PathCol = 
         UpgradePath(PathCol);
         ...
         VACUUM;
          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.
       25.     If you are a new user, you may wish to play 
         with Postgres as described below.
       26.     Clean up after yourself. Type 
         $ rm -rf /usr/src/pgsql_6_5
         $ rm -rf /usr/local/pgsql_6_5
         # Also delete old database directory tree if it is 
         not in
         #  /usr/local/pgsql_6_5/data
         $ rm ~/postgresql-v6.5.1.tar.gz
       27.     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 
         $ cd /usr/local/pgsql/doc
         $ gunzip 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. 
         $ alias gshp='gs -sDEVICE=laserjet -r300 
         -dNOPAUSE'
         $ export 
         GS_LIB=/usr/share/ghostscript:/usr/share/ghostscr-
         ipt/fonts
         $ gunzip user.ps.gz
         $ gshp -sOUTPUTFILE=user.hp user.ps
         $ gzip user.ps
         $ lpr -l -s -r manpage.hp
       28.     The Postgres team wants to keep Postgres 
         working on all of the supported platforms. We 
         therefore ask you to let us know if you did or did 
         not get Postgres to work on you system. Please 
         send a mail message to pgsql-ports@@postgresql.org 
         (mailto:pgsql-ports@@postgresql.org) telling us the 
         following: 
         o  The version of Postgres (v6.5.1, 6.5, beta 
           990318, etc.).
         o  Your operating system (i.e. RedHat v5.2 Linux 
           v2.0.36).
         o  Your hardware (SPARC, i486, etc.).
         o  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.
       29.     Now create, access and manipulate databases 
         as desired. Write client programs to access the 
         database server. In other words, enjoy!

Playing with Postgres

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

       % 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: 

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

       Create the database foo: 

       template1=> create database foo;
       CREATEDB

       (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.)
       Now connect to the new database: 

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

       ("slash" commands aren't SQL, so no semicolon. Use \? 
       to see all the slash commands.)
       And create a table: 

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

       Then inspect the new table: 

       foo=> \d bar

       Table    = bar
       +----------------------------------+-----------------
       ------------------+-------+
       |              Field               |              
       Type                | Length|
       +----------------------------------+-----------------
       ------------------+-------+
       | i                                | int4                             
       |     4 |
       | c                                | (bp)char                         
       |    16 |
       +----------------------------------+-----------------
       ------------------+-------+

       And so on. You get the idea.

The Next Step

       Questions? Bugs? Feedback? First, read the files in 
       directory /usr/src/pgsql/doc/. The FAQ in this 
       directory may be particularly useful.
       If Postgres 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.
       Check on the web site at http://www.postgresql.org 
       For more information on the various support mailing 
       lists.

Porting Notes

        Check for any platform-specific FAQs in the doc/ 
       directory of the source distribution. 

Chapter 4. Configuration Options

Parameters for Configuration (configure)

        The full set of parameters available in configure 
       can be obtained by typing 

           $ ./configure --help
          

        
        The following parameters may be of interest to 
       installers: 

       Directory and file names:
         --prefix=PREFIX         install 
       architecture-independent files in PREFIX
                                 [/usr/local/pgsql]
         --bindir=DIR            user executables in DIR 
       [EPREFIX/bin]
         --libdir=DIR            object code libraries in 
       DIR [EPREFIX/lib]
         --includedir=DIR        C header files in DIR 
       [PREFIX/include]
         --mandir=DIR            man documentation in DIR 
       [PREFIX/man]
       Features and packages:
         --disable-FEATURE       do not include FEATURE 
       (same as --enable-FEATURE=no)
         --enable-FEATURE[=ARG]  include FEATURE [ARG=yes]
         --with-PACKAGE[=ARG]    use PACKAGE [ARG=yes]
         --without-PACKAGE       do not use PACKAGE (same as 
       --with-PACKAGE=no)
       --enable and --with options recognized:
         --with-template=template
                                 use operating system 
       template file
                                     see template directory
         --with-includes=incdir  site header files for 
       tk/tcl, etc in DIR
         --with-libs=incdir      also search for libraries 
       in DIR
         --with-libraries=libdir also search for libraries 
       in DIR
         --enable-locale         enable locale support
         --enable-recode         enable cyrillic recode 
       support
         --with-mb=encoding    enable multi-byte support
         --with-pgport=portnum change default startup port
         --with-maxbackends=n  set default maximum number of 
       server processes 
         --with-tcl              build Tcl interfaces and 
       pgtclsh
         --with-tclconfig=tcldir tclConfig.sh and 
       tkConfig.sh are in DIR
         --with-perl             build Perl interface
         --with-odbc             build ODBC driver package
         --with-odbcinst=odbcdir change default directory 
       for odbcinst.ini
         --enable-cassert        enable assertion checks 
       (debugging)
         --with-CC=compiler      use specific C compiler
         --with-CXX=compiler     use specific C++ compiler
         --without-CXX           prevent building C++ code 
          

        
        Some systems may have trouble building a specific 
       feature of Postgres. For example, systems with a 
       damaged C++ compiler may need to specify 
       --without-CXX to instruct the build procedure to skip 
       construction of libpq++. 

Parameters for Building (make)

        Many installation-related parameters can be set in 
       the building stage of Postgres installation. 
        In most cases, these parameters should be placed in 
       a file, Makefile.custom, intended just for that 
       purpose. The default distribution does not contain 
       this optional file, so you will create it using a 
       text editor of your choice. When upgrading 
       installations, you can simply copy your old 
       Makefile.custom to the new installation before doing 
       the build. 

           make [ variable=value [,...] ]
          

        
        A few of the many variables which can be specified 
       are: 

        POSTGRESDIR 
          Top of the installation tree. 

        BINDIR 
          Location of applications and utilities. 

        LIBDIR 
          Location of object libraries, including shared 
         libraries. 

        HEADERDIR 
          Location of include files. 

        ODBCINST 
          Location of installation-wide psqlODBC (ODBC) 
         configuration file. 
        
        There are other optional parameters which are not as 
       commonly used. Many of those listed below are 
       appropriate when doing Postgres server code 
       development. 

        CFLAGS 
          Set flags for the C compiler. Should be assigned 
         with "+=" to retain relevant default parameters. 

        YFLAGS 
          Set flags for the yacc/bison parser. -v might be 
         used to help diagnose problems building a new 
         parser. Should be assigned with "+=" to retain 
         relevant default parameters. 

        USE_TCL 
          Enable Tcl interface building. 

        HSTYLE 
          DocBook HTML style sheets for building the 
         documentation from scratch. Not used unless you 
         are developing new documentation from the 
         DocBook-compatible SGML source documents in 
         doc/src/sgml/. 

        PSTYLE 
          DocBook style sheets for building printed 
         documentation from scratch. Not used unless you 
         are developing new documentation from the 
         DocBook-compatible SGML source documents in 
         doc/src/sgml/. 
        
        Here is an example Makefile.custom for a PentiumPro 
       Linux system: 

       # Makefile.custom
       # Thomas Lockhart 1998-03-01

       POSTGRESDIR= /opt/postgres/current
       CFLAGS+= -m486 # -g -O0
       USE_TCL= true
       TCL_LIB= -ltcl
       X_LIBS= -L/usr/X11/lib
       TK_LIB= -ltk

       # documentation

       HSTYLE= /home/tgl/SGML/db118.d/docbook/html
       PSTYLE= /home/tgl/SGML/db118.d/docbook/print
          

        

Locale Support

        

         Note: Written by Oleg Bartunov. See Oleg's web 
         page (http://www.sai.msu.su/~megera/postgres/) for 
         additional information on locale and Russian 
         language support.

        While doing a project for a company in Moscow, 
       Russia, I encountered the problem that postgresql had 
       no support of national alphabets. After looking for 
       possible workarounds I decided to develop support of 
       locale myself. I'm not a C-programer but already had 
       some experience with locale programming when I work 
       with perl (debugging) and glimpse. After several days 
       of digging through the Postgres source tree I made 
       very minor corections to 
       src/backend/utils/adt/varlena.c and 
       src/backend/main/main.c and got what I needed! I did 
       support only for LC_CTYPE and LC_COLLATE, but later 
       LC_MONETARY was added by others. I got many messages 
       from people about this patch so I decided to send it 
       to developers and (to my surprise) it was 
       incorporated into the Postgres distribution. 
        People often complain that locale doesn't work for 
       them. There are several common mistakes: 
       o  Didn't properly configure postgresql before 
        compilation. You must run configure with 
        --enable-locale option to enable locale support. 
        Didn't setup environment correctly when starting 
        postmaster. You must define environment variables 
        LC_CTYPE and LC_COLLATE before running postmaster 
        because backend gets information about locale from 
        environment. I use following shell script 
        (runpostgres): 
               #!/bin/sh
               
               export LC_CTYPE=koi8-r
               export LC_COLLATE=koi8-r
               postmaster -B 1024 -S 
        -D/usr/local/pgsql/data/ -o '-Fe'
              
         and run it from rc.local as 
               /bin/su - postgres -c 
        "/home/postgres/runpostgres"
              
         
       o  Broken locale support in OS (for example, locale 
        support in libc under Linux several times has 
        changed and this caused a lot of problems). Latest 
        perl has also support of locale and if locale is 
        broken perl -v will complain something like: 
               8:17[mira]:~/WWW/postgres>setenv LC_CTYPE 
        not_exist
               8:18[mira]:~/WWW/postgres>perl -v
               perl: warning: Setting locale failed.
               perl: warning: Please check that your locale 
        settings:
               LC_ALL = (unset),
                   LC_CTYPE = "not_exist",
                   LANG = (unset)
               are supported and installed on your system.
               perl: warning: Falling back to the standard 
        locale ("C").
              
         
       o  Wrong location of locale files! Possible locations 
        include: /usr/lib/locale (Linux, Solaris), 
        /usr/share/locale (Linux), /usr/lib/nls/loc (DUX 
        4.0). Check man locale to find the correct 
        location. Under Linux I did a symbolic link between 
        /usr/lib/locale and /usr/share/locale to be sure 
        that the next libc will not break my locale. 
        

What are the Benefits?

        You can use ~* and order by operators for strings 
       contain characters from national alphabets. 
       Non-english users definitely need that. If you won't 
       use locale stuff just undefine the USE_LOCALE 
       variable. 

What are the Drawbacks?

        There is one evident drawback of using locale - its 
       speed! So, use locale only if you really need it. 

Kerberos Authentication

        Kerberos is an industry-standard secure 
       authentication system suitable for distributed 
       computing over a public network. 

Availability

        The Kerberos authentication system is not 
       distributed with Postgres. Versions of Kerberos are 
       typically available as optional software from 
       operating system vendors. In addition, a source code 
       distribution may be obtained through MIT Project 
       Athena (ftp://athena-dist.mit.edu). 

         Note: You may wish to obtain the MIT version even 
         if your vendor provides a version, since some 
         vendor ports have been deliberately crippled or 
         rendered non-interoperable with the MIT version.

        Users located outside the United States of America 
       and Canada are warned that distribution of the actual 
       encryption code in Kerberos is restricted by U. S. 
       Government export regulations. 
        Inquiries regarding your Kerberos should be directed 
       to your vendor or MIT Project Athena 
       (info-kerberos@@athena.mit.edu). Note that FAQLs 
       (Frequently-Asked Questions Lists) are periodically 
       posted to the Kerberos mailing list 
       (mailto:kerberos@@ATHENA.MIT.EDU) (send mail to 
       subscribe (mailto:kerberos-request@@ATHENA.MIT.EDU)), 
       and USENET news group (news:comp.protocols.kerberos). 

Installation

        Installation of Kerberos itself is covered in detail 
       in the Kerberos Installation Notes . Make sure that 
       the server key file (the srvtab or keytab) is somehow 
       readable by the Postgres account. 
        Postgres and its clients can be compiled to use 
       either Version 4 or Version 5 of the MIT Kerberos 
       protocols by setting the KRBVERS variable in the file 
       src/Makefile.global to the appropriate value. You can 
       also change the location where Postgres expects to 
       find the associated libraries, header files and its 
       own server key file. 
        After compilation is complete, Postgres must be 
       registered as a Kerberos service. See the Kerberos 
       Operations Notes and related manual pages for more 
       details on registering services. 

Operation

        After initial installation, Postgres should operate 
       in all ways as a normal Kerberos service. For details 
       on the use of authentication, see the PostgreSQL 
       User's Guide reference sections for postmaster and 
       psql. 
        In the Kerberos Version 5 hooks, the following 
       assumptions are made about user and service naming: 
       o  User principal names (anames) are assumed to 
        contain the actual Unix/Postgres user name in the 
        first component. 
       o  The Postgres service is assumed to be have two 
        components, the service name and a hostname, 
        canonicalized as in Version 4 (i.e., with all 
        domain suffixes removed). 
        
        

       Table 4-1. Kerberos Parameter Examples
        Parameter   Example 
        user        frew@@S2K.ORG 
        user        aoki/HOST=miyu.S2K.Berkeley.EDU@@S2K.ORG 
        host        postgres_dbms/ucbvax@@S2K.ORG 


        
        Support for Version 4 will disappear sometime after 
       the production release of Version 5 by MIT. 

Chapter 5. Release Notes

Release 6.5

        This release marks a major step in the development 
       team's mastery of the source code we inherited from 
       Berkeley. You will see we are now easily adding major 
       features, thanks to the increasing size and 
       experience of our world-wide development team. 
        Here is a brief summary of some of the more 
       noticable changes: 

        Multi-version concurrency control(MVCC) 
          This removes our old table-level locking, and 
         replaces it with a locking system that is superior 
         to most commercial database systems. In a 
         traditional system, each row that is modified is 
         locked until committed, preventing reads by other 
         users. MVCC uses the natural multi-version nature 
         of PostgreSQL to allow readers to continue reading 
         consistent data during writer activity. Writers 
         continue to use the compact pg_log transaction 
         system. This is all performed without having to 
         allocate a lock for every row like traditional 
         database systems. So, basically, we no longer are 
         restricted by simple table-level locking; we have 
         something better than row-level locking. 

        Numeric data type 
          We now have a true numeric data type, with 
         user-specified precision. 

        Temporary tables 
          Temporary tables are guaranteed to have unique 
         names within a database session, and are destroyed 
         on session exit. 

        New SQL features 
          We now have CASE, INTERSECT, and EXCEPT statement 
         support. We have new LIMIT/OFFSET, SET TRANSACTION 
         ISOLATION LEVEL, SELECT ... FOR UPDATE, and an 
         improved LOCK command. 

        Speedups 
          We continue to speed up PostgreSQL, thanks to the 
         variety of talents within our team. We have sped 
         up memory allocation, optimization, table joins, 
         and row transfer routines. 

        Ports 
          We continue to expand our port list, this time 
         including WinNT/ix86 and NetBSD/arm32. 

        Interfaces 
          Most interfaces have new versions, and existing 
         functionality has been improved. 
        

Migration to v6.5

        A dump/restore using pg_dump or pg_dumpall is 
       required for those wishing to migrate data from any 
       previous release of Postgres. 
        The new Multi-Version Concurrency Control (MVCC) 
       features can give somewhat different behaviors in 
       multi-user environments. Read and understand the 
       following section to ensure that your existing 
       applications will give you the behavior you need. 

       Multi-Version Concurrency Control
        Because readers in 6.5 don't lock data, regardless 
       of transaction isolation level, data read by one 
       transaction can be overwritten by another. In the 
       other words, if a row is returned by SELECT it 
       doesn't mean that this row really exists at the time 
       it is returned (i.e. sometime after the statement or 
       transaction began) nor that the row is protected from 
       deletion or updation by concurrent transactions 
       before the current transaction does a commit or 
       rollback. 
        To ensure the actual existance of a row and protect 
       it against concurrent updates one must use SELECT FOR 
       UPDATE or an appropriate LOCK TABLE statement. This 
       should be taken into account when porting 
       applications from previous releases of Postgres and 
       other environments. 
        Keep above in mind if you are using contrib/refint.* 
       triggers for referential integrity. Additional 
       technics are required now. One way is to use LOCK 
       parent_table IN SHARE ROW EXCLUSIVE MODE command if a 
       transaction is going to update/delete a primary key 
       and use LOCK parent_table IN SHARE MODE command if a 
       transaction is going to update/insert a foreign key. 

         Note: Note that if you run a transaction in 
         SERIALIZABLE mode then you must execute LOCK 
         commands above before execution of any DML 
         statement 
         (SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO) in the 
         transaction.

        
        These inconveniences will disappear in the future 
       when the ability to read dirty (uncommitted) data 
       (regardless of isolation level) and true referential 
       integrity will be implemented. 

Detailed Change List

        

       Bug Fixes
       ---------
       Fix text<->float8 and text<->float4 conversion 
       functions(Thomas)
       Fix for creating tables with mixed-case 
       constraints(Billy)
       Change exp()/pow() behavior to generate error on 
       underflow/overflow(Jan)
       Fix bug in pg_dump -z
       Memory overrun cleanups(Tatsuo)
       Fix for lo_import crash(Tatsuo)
       Adjust handling of data type names to suppress double 
       quotes(Thomas)
       Use type coersion for matching columns and 
       DEFAULT(Thomas)
       Fix deadlock so it only checks once after one second 
       of sleep(Bruce)
       Fixes for aggregates and PL/pgsql(Hiroshi)
       Fix for subquery crash(Vadim)
       Fix for libpq function PQfnumber and case-insensitive 
       names(Bahman Rafatjoo)
       Fix for large object write-in-middle, no extra block, 
       memory consumption(Tatsuo)
       Fix for pg_dump -d or -D and  quote special 
       characters in INSERT
       Repair serious problems with dynahash(Tom)
       Fix INET/CIDR portability problems
       Fix problem with selectivity error in ALTER TABLE ADD 
       COLUMN(Bruce)
       Fix executor so mergejoin of different column types 
       works(Tom)
       Fix for Alpha OR selectivity bug
       Fix OR index selectivity problem(Bruce)
       Fix so \d shows proper length for 
       char()/varchar()(Ryan)
       Fix tutorial code(Clark)
       Improve destroyuser checking(Oliver)
       Fix for Kerberos(Rodney McDuff)
       Fix for dropping database while dirty buffers(Bruce)
       Fix so sequence nextval() can be 
       case-sensitive(Bruce)
       Fix !!= operator
       Drop buffers before destroying database files(Bruce)
       Fix case where executor evaluates functions 
       twice(Tatsuo)
       Allow sequence nextval actions to be 
       case-sensitive(Bruce)
       Fix optimizer indexing not working for negative 
       numbers(Bruce)
       Fix for memory leak in executor with fjIsNull
       Fix for aggregate memory leaks(Erik Riedel)
       Allow username containing a dash GRANT permissions
       Cleanup of NULL in inet types
       Clean up system table bugs(Tom)
       Fix problems of PAGER and \? command(Masaaki Sakaida)
       Reduce default multi-segment file size limit to 
       1GB(Peter)
       Fix for dumping of CREATE OPERATOR(Tom)
       Fix for backward scanning of cursors(Hiroshi Inoue)
       Fix for COPY FROM STDIN when using \i(Tom)
       Fix for subselect is compared inside an 
       expression(Jan)
       Fix handling of error reporting while returning 
       rows(Tom)
       Fix problems with reference to array types(Tom,Jan)
       Prevent UPDATE SET oid(Jan)
       Fix pg_dump so -t option can handle case-sensitive 
       tablenames
       Fixes for GROUP BY in special cases(Tom, Jan)
       Fix for memory leak in failed queries(Tom)
       DEFAULT now supports mixed-case identifiers(Tom)
       Fix for multi-segment uses of DROP/RENAME table, 
       indexes(Ole Gjerde)

       Enhancements
       ------------
       Add "vacuumdb" utility
       Speed up libpq by allocating memory better(Tom)
       EXPLAIN all indices used(Tom)
       Implement CASE, COALESCE, NULLIF  expression(Thomas)
       New pg_dump table output format(Constantin)
       Add string min()/max() functions(Thomas)
       Extend new type coersion techniques to 
       aggregates(Thomas)
       New moddatetime contrib(Terry)
       Update to pgaccess 0.96(Constantin)
       Add routines for single-byte "char" type(Thomas)
       Improved substr() function(Thomas)
       Improved multi-byte handling(Tatsuo)
       Multi-version concurrency control/MVCC(Vadim)
       New Serialized mode(Vadim)
       Fix for tables over 2gigs(Peter)
       New SET TRANSACTION ISOLATION LEVEL(Vadim)
       New LOCK TABLE IN ... MODE(Vadim)
       Update ODBC driver(Byron)
       New NUMERIC data type(Jan)
       New SELECT FOR UPDATE(Vadim)
       Handle "NaN" and "Infinity" for input values(Jan)
       Improved date/year handling(Thomas)
       Improved handling of backend connections(Magnus)
       New options ELOG_TIMESTAMPS and USE_SYSLOG options 
       for log files(Massimo)
       New TCL_ARRAYS option(Massimo)
       New INTERSECT and EXCEPT(Stefan)
       New pg_index.indisprimary for primary key 
       tracking(D'Arcy)
       New pg_dump option to allow dropping of tables before 
       creation(Brook)
       Speedup of row output routines(Tom)
       New READ COMMITTED isolation level(Vadim)
       New TEMP tables/indexes(Bruce)
       Prevent sorting if result is already sorted(Jan)
       New memory allocation optimization(Jan)
       Allow psql to do \p\g(Bruce)
       Allow multiple rule actions(Jan)
       Added LIMIT/OFFSET functionality(Jan)
       Improve optimizer when joining a large number of 
       tables(Bruce)
       New intro to SQL from S. Simkovics' Master's Thesis 
       (Stefan, Thomas)
       New intro to backend processing from S. Simkovics' 
       Master's Thesis (Stefan)
       Improved int8 support(Ryan Bradetich, Thomas, Tom)
       New routines to convert between int8 and text/varchar 
       types(Thomas)
       New bushy plans, where meta-tables are joined(Bruce)
       Enable right-hand queries by default(Bruce)
       Allow reliable maximum number of backends to be set 
       at configure time
             (--with-maxbackends and postmaster switch (-N 
       backends))(Tom)
       GEQO default now 10 tables because of optimizer 
       speedups(Tom)
       Allow NULL=Var for MS-SQL portability(Michael, Bruce)
       Modify contrib check_primary_key() so either 
       "automatic" or "dependent"(Anand)
       Allow psql \d on a view show query(Ryan)
       Speedup for LIKE(Bruce)
       Ecpg fixes/features, see 
       src/interfaces/ecpg/ChangeLog file(Michael)
       JDBC fixes/features, see 
       src/interfaces/jdbc/CHANGELOG(Peter)
       Make % operator have precedence like /(Bruce)
       Add new postgres -O option to allow system table 
       structure changes(Bruce)
       Update contrib/pginterface/findoidjoins script(Tom)
       Major speedup in vacuum of deleted rows with 
       indexes(Vadim) 
       Allow non-SQL functions to run different versions 
       based on arguments(Tom)
       Add -E option that shows actual queries sent by \dt 
       and friends(Masaaki Sakaida)
       Add version number in startup banners for 
       psql(Masaaki Sakaida)
       New contrib/vacuumlo removes large objects not 
       referenced(Peter)
       New initialization for table sizes so non-vacuumed 
       tables perform better(Tom)
       Improve error messages when a connection is 
       rejected(Tom)
       Support for arrays of char() and varchar() 
       fields(Massimo)
       Overhaul of hash code to increase reliability and 
       performance(Tom)
       Update to PyGreSQL 2.4(D'Arcy)
       Changed debug options so -d4 and -d5 produce 
       different node displays(Jan)
       New pg_options: pretty_plan, pretty_parse, 
       pretty_rewritten(Jan)
       Better optimization statistics for system table 
       access(Tom)
       Better handling of non-default block sizes(Massimo)
       Improve GEQO optimizer memory consumption(Tom)
       UNION now suppports ORDER BY of columns not in target 
       list(Jan)
       Major libpq++ improvements(Vince Vielhaber)

       Source Tree Changes
       -------------------
       Improve port matching(Tom)
       Portability fixes for SunOS
       Add NT/Win32 backend port and enable dynamic 
       loading(Magnus and Daniel Horak)
       New port to Cobalt Qube(Mips) running Linux(Tatsuo)
       Port to NetBSD/m68k(Mr. Mutsuki Nakajima)
       Port to NetBSD/sun3(Mr. Mutsuki Nakajima)
       Port to NetBSD/macppc(Toshimi Aoki)
       Fix for tcl/tk configuration(Vince)
       Removed CURRENT keyword for rule queries(Jan)
       NT dynamic loading now works(Daniel Horak)
       Add ARM32 support(Andrew McMurry)
       Better support for HPUX 11 and Unixware
       Improve file handling to be more uniform, prevent 
       file descriptor leak(Tom)
       New install commands for plpgsql(Jan)
            
d335 3
d339 6
@


1.66
log
@Cut down to 80 columns per Bruce. Mostly hacked at the porting table.
@
text
@d30 3
d61 1
a61 1
        This manual describes version 6.5 of Postgres. The 
d153 1
a153 1
       work with v6.5, but we did not receive explicit 
d189 1
a189 1
       v6.5. 
d288 2
a289 4
         ftp://ftp.postgresql.org/pub/postgresql-v6.5.tar.-
         gz 
         (ftp://ftp.postgresql.org/pub/postgresql-v6.5.tar-
         .gz) from the Internet. Store it in your home 
d334 6
a339 2
         skip to step 9. If you are upgrading an existing 
         system then back up your database. For alpha- and 
d359 1
a359 1
         $ gunzip -c postgresql-v6.5.tar.gz \
d453 1
a453 1
         $ gunzip -c ~/postgresql-v6.5.tar.gz | tar xvf -
d693 1
a693 1
              $ postmaster -i
d875 1
a875 1
         $ rm ~/postgresql-v6.5.tar.gz
d902 4
a905 4
         o  The version of Postgres (v6.5, 6.4.2, beta 
           981014, etc.).
         o  Your operating system (i.e. RedHat v5.1 Linux 
           v2.0.34).
@


1.66.2.1
log
@Update with release notes for v6.5.1.
Change references from v6.5 to v6.5.1 in the installation instructions.
@
text
@a29 3
          Release 6.5.1                                   
             Migration to v6.5.1                          
             Detailed Change List                         
d58 1
a58 1
        This manual describes version 6.5.1 of Postgres. The 
d150 1
a150 1
       work with v6.5.1, but we did not receive explicit 
d186 1
a186 1
       v6.5.1. 
d285 4
a288 2
         ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.tar.gz 
         from the Internet. Store it in your home 
d333 2
a334 6
         skip to step 9. If you are upgrading from 6.5, you
         do not need to dump/reload or initdb. Simply
         compile the source code, stop the postmaster, do a
         "make install", and restart the postmaster.
         If you are upgrading from 6.4.* or earlier,
         back up your database.  For alpha- and 
d354 1
a354 1
         $ gunzip -c postgresql-v6.5.1.tar.gz \
d448 1
a448 1
         $ gunzip -c ~/postgresql-v6.5.1.tar.gz | tar xvf -
d688 1
a688 1
              $ nohup postmaster -i > pgserver.log 2>&1 &
d870 1
a870 1
         $ rm ~/postgresql-v6.5.1.tar.gz
d897 4
a900 4
         o  The version of Postgres (v6.5.1, 6.5, beta 
           990318, etc.).
         o  Your operating system (i.e. RedHat v5.2 Linux 
           v2.0.36).
@


1.66.2.2
log
@Update for 6.5.3, including new INSTALL file and updated HISTORY.
@
text
@d2 2
a3 1
Chapter 0. Installation
d5 1
a6 27
Requirements to Run Postgres
Installation Procedure
Playing with Postgres
The Next Step
Porting Notes

     Complete installation instructions for Postgres v6.5.3.

Before installing Postgres, you may wish to visit www.postgresql.org for up
to date information, patches, etc.

These installation instructions assume:

   * Commands are Unix-compatible. See note below.

   * Defaults are used except where noted.

   * User postgres is the Postgres superuser.

   * The source path is /usr/src/pgsql (other paths are possible).

   * The runtime path is /usr/local/pgsql (other paths are possible).

Commands were tested on RedHat Linux version 5.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands like
ps and tar may vary wildly between platforms on what options you should use.
Use common sense before typing in these commands.
d8 207
a214 5
Our Makefiles require GNU make (called "gmake" in this document). They will
not work with non-GNU make programs. If you have GNU make installed under
the name "make" instead of "gmake", then you will use the command make
instead. That's OK, but you need to have the GNU form of make to succeed
with an installation.
d218 28
a245 22
Up to date information on supported platforms is at
http://www.postgresql.org/docs/admin/install.htm. In general, most
Unix-compatible platforms with modern libraries should be able to run
Postgres.

Although the minimum required memory for running Postgres 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.

Check that you have sufficient disk space. You will need about 30 Mbytes for
/usr/src/pgsql, about 5 Mbytes for /usr/local/pgsql (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.

We therefore recommend that during installation and testing you have well
over 20 Mbytes free under /usr/local 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 /usr/local/pgsql, 1
Mbyte for the empty database, plus about five times the space you would
require to store your database data in a flat file.
d247 2
a248 1
To check for disk space, use
d250 1
a250 4
$ df -k


  ------------------------------------------------------------------------
d254 662
a915 650
Postgres Installation

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

  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.

     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 Postgres 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
     ftp://ftp.postgresql.org/pub/INSTALL.

  2. Create the Postgres superuser account (postgres is commonly used) if it
     does not already exist.

     The owner of the Postgres files can be any unprivileged user account.
     It must not be root, bin, or any other account with special access
     rights, as that would create a security risk.

  3. Log in to the Postgres superuser account. Most of the remaining steps
     in the installation will happen in this account.

  4. Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.5.3.tar.gz from the
     Internet. Store it in your home directory.

  5. Some platforms use flex. If your system uses flex then make sure you
     have a good version. To check, 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
     Postgres.

     You may want to do the entire flex 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:

     $ 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

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

  6. If you are not upgrading an existing system then skip to . If you are
     upgrading from 6.5, you do not need to dump/reload or initdb. Simply
     compile the source code, stop the postmaster, do a "make install", and
     restart the postmaster. If you are upgrading from 6.4.* or earlier,
     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.

          Tip: Do not use the pg_dumpall script from v6.0 or everything
          will be owned by the Postgres super user.

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

     $ pg_dumpall > db.out

     To use the latest pg_dumpall script on your existing older database
     before upgrading Postgres, pull the most recent version of pg_dumpall
     from the new distribution:

     $ cd
     $ gunzip -c postgresql-v6.5.3.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 > db.out
     $ rm -rf src

     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.

     If the pg_dumpall command seems to take a long time and you think it
     might have died, then, from another terminal, type

     $ ls -l db.out

     several times to see if the size of the file is growing.

     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 the release notes which should cover any
     release-specific issues.

                                        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.
  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 pid replaced by the process id for process
     postmaster. (Do not use the id for process "grep postmaster".) Type

     $ kill pid

     to actually stop the process.

          Tip: On systems which have Postgres 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

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

          to halt Postgres.

  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. The actual paths can be
     different for your installation but you must be consistent throughout
     this procedure.

          Note: 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 gmake
          install stage of installation.

     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.5.3.tar.gz | tar xvf -

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

     $ cd /usr/src/pgsql/src
     $ ./configure [ options ]

       a. 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
          --with-template=TEMPLATE option to make the right file be chosen.

               Please Report Problems: If your system is not
               automatically recognized by configure and you have to do
               this, please send email to scrappy@@hub.org with the
               output of the program ./config.guess. Indicate what the
               template file should be.

       b. Choose configuration options. Check 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

               ./configure --help

          Some of the more commonly used ones are:

                 --prefix=BASEDIR   Selects a different base directory for the
                                    installation of the Postgres 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.)

       c. Here is the configure script used on a Sparc Solaris 2.5 system
          with /opt/postgres specified as the installation base directory:

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

               Tip: Of course, you may type these three lines all on
               the same line.

 12. Install the man and HTML documentation. Type

     $ cd /usr/src/pgsql/doc
     $ gmake install

     The documentation is also available in Postscript format. Look for
     files ending with .ps.gz in the same directory.

 13. Compile the program. Type

     $ cd /usr/src/pgsql/src
     $ gmake all > make.log 2>&1 &
     $ tail -f make.log

     The last line displayed will hopefully be

     All of PostgreSQL is successfully made. Ready to install.

     Remember, "gmake" may be called "make" on your system. 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: 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 a message stating that the flex command
     cannot be found then install flex as described earlier. Next, change
     directory back to this directory, type

     $ gmake clean

     then recompile again.

     Compiler options, such as optimization and debugging, may be specified
     on the command line using the COPT variable. For example, typing

     $ gmake COPT="-g" all > make.log 2>&1 &

     would invoke your compiler's -g option in all steps of the build. See
     src/Makefile.global.in for further details.

 14. Install the program. Type

     $ cd /usr/src/pgsql/src
     $ gmake install > make.install.log 2>&1 &
     $ 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. Remember, "gmake" may be called "make" on your system.

 15. If necessary, tell your system how to find the new shared libraries.
     You can do one of the following, preferably the first:

       a. As root, edit file /etc/ld.so.conf. Add a 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.

 16. If you used the --with-perl 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 su) and doing

           $ cd /usr/src/pgsql/src/interfaces/perl5
           $ gmake install


 17. If it has not already been done, then prepare account postgres for
     using Postgres. Any account that will use Postgres must be similarly
     prepared.

     There are several ways to influence the runtime environment of the
     Postgres server. Refer to the Administrator's Guide for more
     information.

          Note: The following instructions are for a bash/sh shell.
          Adapt accordingly for other shells.

       a. Add the following lines to your login environment: shell,
          ~/.bash_profile:

                  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


       b. Several regression tests could fail if the user's locale collation
          scheme is different from that of the standard C locale.

          If you configure and compile Postgres with --enable-locale then
          you should set the locale environment to "C" (or unset all "LC_*"
          variables) by putting these additional lines to your login
          environment before starting postmaster:

                  LC_COLLATE=C
                  LC_CTYPE=C
                  export LC_COLLATE LC_CTYPE





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


 18. Create the database installation from your Postgres superuser account
     (typically account postgres). Do not do the following as root! This
     would be a major security hole. Type

     $ initdb

 19. 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 finished. If you are upgrading from v6.0 or later you can
     copy file pg_hba.conf from your old database on top of the one in your
     new database, rather than redoing the file from scratch.

 20. Briefly test that the backend will start and run by running it from the
     command line.

       a. Start the postmaster daemon running in the background by typing

          $ cd
          $ nohup postmaster -i > pgserver.log 2>&1 &

       b. Create a database by typing

          $ createdb

       c. Connect to the new database:

          $ psql

       d. And run a sample query:

          postgres=> SELECT datetime 'now';

       e. Exit psql:

          postgres=> \q

       f. Remove the test database (unless you will want to use it later for
          other tests):

          $ destroydb

 21. Run postmaster in the background from your Postgres superuser account
     (typically account postgres). Do not run postmaster from the root
     account!

     Usually, you will want to modify your computer so that it will
     automatically start postmaster whenever it boots. It is not required;
     the Postgres server can be run successfully from non-privileged
     accounts without root intervention.

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

     Whatever you do, postmaster must be run by the Postgres superuser
     (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.

        o If you are installing from a non-privileged account and have no
          root access, then start the postmaster and send it to the
          background:

          $ cd
          $ nohup postmaster > regress.log 2>&1 &

        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.

        o In RedHat Linux edit file /etc/inittab to add the following as a
          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.)

 22. Run the regression tests. The file
     /usr/src/pgsql/src/test/regress/README has detailed instructions for
     running and interpreting the regression tests. A short version follows
     here:

       a. 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 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 Postgres. The file ./regression.diffs
          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.

          For example,

             + For a i686/Linux-ELF platform, no tests failed since this is
               the v6.5.3 regression testing reference platform.

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

          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 Postgres. The regression tests are a
          helpful tool, but they may require some study to be useful.

          After running the regression tests, type

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

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

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

     Minimal Backup Procedure

       1. Run the SQL command VACUUM. This will clean up your database.

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

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

 24. If you are upgrading an existing system then reinstall your old
     database. Type

     $ cd
     $ psql -e template1 < db.out

     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)

     UPDATE FirstTable SET PathCol = UpgradePath(PathCol);
     UPDATE SecondTable SET PathCol = UpgradePath(PathCol);
     ...
     VACUUM;

     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.

 25. If you are a new user, you may wish to play with Postgres as described
     below.

 26. Clean up after yourself. Type

     $ rm -rf /usr/src/pgsql_6_5
     $ rm -rf /usr/local/pgsql_6_5
     # Also delete old database directory tree if it is not in
     #  /usr/local/pgsql_6_5/data
     $ rm ~/postgresql-v6.5.3.tar.gz

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

     $ cd /usr/local/pgsql/doc
     $ gunzip 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.

     $ 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

 28. The Postgres team wants to keep Postgres working on all of the
     supported platforms. We therefore ask you to let us know if you did or
     did not get Postgres to work on you system. Please send a mail message
     to pgsql-ports@@postgresql.org telling us the following:

        o The version of Postgres (v6.5.3, 6.5, beta 990318, etc.).

        o Your operating system (i.e. RedHat v5.1 Linux v2.0.34).

        o Your hardware (SPARC, i486, etc.).

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

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

  ------------------------------------------------------------------------
d919 66
a984 4
After Postgres is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to see
Postgres do something. That's easy. Invoke the interactive interface to
Postgres, psql:
d986 1
a986 1
% psql template1
d988 1
a988 3
(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.)
d990 10
a999 1
The response from psql is:
d1001 1
a1001 23
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=>

Create the database foo:

template1=> create database foo;
CREATEDB

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

Now connect to the new database:

template1=> \c foo
connecting to new database: foo
d1003 2
a1004 2
("slash" commands aren't SQL, so no semicolon. Use \? to see all the slash
commands.)
d1006 1
a1006 1
And create a table:
d1008 1
a1008 2
foo=> create table bar (i int4, c char(16));
CREATE
d1010 636
a1645 1
Then inspect the new table:
a1646 31
foo=> \d bar

Table    = bar
+----------------------------------+----------------------------------+-------+
|              Field               |              Type                | Length|
+----------------------------------+----------------------------------+-------+
| i                                | int4                             |     4 |
| c                                | (bp)char                         |    16 |
+----------------------------------+----------------------------------+-------+

And so on. You get the idea.

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


The Next Step

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

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

Check on the web site at http://www.postgresql.org For more information on
the various support mailing lists.

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


Porting Notes
a1647 2
Check for any platform-specific FAQs in the doc/ directory of the source
distribution.
@


1.66.2.3
log
@Fix typo in the startup example for RH Linux.
Thanks to Kovacs Zoltan <kovacsz@@pc10.radnoti-szeged.sulinet.hu>.
@
text
@d571 1
a571 1
               /usr/local/pgsql/server.log 2>&1 /dev/null"
@


1.65
log
@Add a mention of doc changes in the release notes.
@
text
@d1 1
a3 3
Edited by Thomas Lockhart

PostgreSQL is  1996-9 by the Postgres Global Development Group.
d5 1
a34 6
List of Tables

       2-1. Supported Platforms                           
       2-2. Possibly Incompatible Platforms               
       4-1. Kerberos Parameter Examples                   

d72 1
a72 1
                                                      (mailto:Andreas.Zeugswetter@@telecom.at))
d74 1
a74 1
                                                      (mailto:maillist@@candle.pha.pa.us)
d76 7
a82 6
       2.2.x-4.0                                      (mailto:t-ishii@@sra.co.jp), 
                                                      Marc Fournier 
                                                      (mailto:scrappy@@hub.org))
       DGUX        m88k        v6.3       1998-03-01  v6.4 probably OK. Needs new 
       5.4R4.11                                       maintainer. (Brian E Gallew 
                                                      (mailto:geek+@@cmu.edu))
d85 6
a90 7
                                                      (mailto:pjlobo@@euitt.upm.es))
       HPUX        PA-RISC     v6.4       1998-10-25  Both 9.0x and 10.20 (Tom Lane 
                                                      (mailto:tgl@@sss.pgh.pa.us), 
                                                      Stan Brown 
                                                      (mailto:stanb@@awod.com))
       IRIX 6.5    MIPS        v6.4       1998-12-29  IRIX 5.x is different (Mark Dalphin 
                                                      (mdalphin@@amgen.com))
d92 3
a94 2
       2.0.x                                          work for v6.4. (Ryan Kirkpatrick 
                                                      (mailto:rkirkpat@@nag.cs.colorado.edu))
d96 3
a98 3
       2.0.x/libc5                                    (mailto:lockhart@@alumni.caltech.edu))
       linux       x86         v6.5       1999-05-24  (Thomas Lockhart 
       2.0.x/glibc                                    (mailto:lockhart@@alumni.caltech.edu))
d100 1
a100 1
       2.0.x                                          (mailto:t-ishii@@sra.co.jp))
d102 7
a108 5
       2.0.x                                          (mailto:szybist@@boxhill.com))
       linuxPPC    PPC603e     v6.4       1998-10-26  Powerbook 2400c (Tatsuo Ishii
       2.1.24                                         (mailto:t-ishii@@sra.co.jp))
       mklinux DR3 PPC750      v6.4       1998-09-16  PowerMac 7600 (Tatsuo Ishii 
                                                      (mailto:t-ishii@@sra.co.jp))
d110 1
a110 1
                                                      (mailto:a.mcmurry1@@physics.oxford.ac.uk))
d112 1
a112 1
       86 1.3.2                                       (mailto:brook@@trillium.NMSU.Edu))
d115 4
a118 4
                                                      (mailto:t-ishii@@sra.co.jp))
       NetBSD-     NS32532     v6.4       1998-10-27  small problems in date/time 
       current                                        math (Jon Buller 
                                                      (mailto:jonb@@metronet.com))
d120 1
a120 1
       arc 1.3H                                       (mailto:tih@@hamartun.priv.no))
d122 1
a122 1
                                                      (mailto:tih@@hamartun.priv.no))
d124 1
a124 1
       OpenServer 5                                   (mailto:andrew@@compclass.com))
d126 1
a126 1
       UnixWare 7                                     (mailto:andrew@@compclass.com))
d128 1
a128 1
                                                      (mailto:scrappy@@hub.org))
d130 6
a135 5
       2.6-2.7                                        (mailto:szybist@@boxhill.com),
                                                      Frank Ridderbusch 
                                                      (mailto:ridderbusch.pad@@sni.de))
       SunOS       Sparc       v6.3       1998-03-01  Patches submitted (Tatsuo Ishii
       4.1.4                                          (mailto:t-ishii@@sra.co.jp))
d137 6
a142 6
                                                      support (Frank Ridderbusch 
                                                      (mailto:ridderbusch.pad@@sni.de))
       Windows     x86         v6.4       1999-01-06  Client-side libraries or 
                                                      ODBC/JDBC. No server yet. 
                                                      (Magnus Hagander 
                                                      (mha@@sollentuna.net)
d144 2
a145 2
                                                      library. (Daniel Horak 
                                                      (mailto:Dan.Horak@@email.cz)) 
d168 1
a168 1
                                                      use ODBC/JDBC
d170 11
a180 8
                                                      v1.0.9 worked with 
                                                      patches (David Wetzel 
                                                      (mailto:dave@@turbocat.de))
       SVR4 4.4    m88k        v6.2.1     1998-03-01  Confirmed with patching; 
                                                      v6.4.x will need TAS 
                                                      spinlock code (Doug Winterburn 
                                                      (mailto:dlw@@seavme.xroads.com))
       Ultrix      MIPS,VAX?   v6.x       1998-03-01  No recent reports; obsolete?
a182 2
        

d195 4
a198 2
       o  The source path is /usr/src/pgsql (other paths are possible). 
       o  The runtime path is /usr/local/pgsql (other paths are possible). 
d246 1
d285 5
a289 2
         ftp://ftp.postgresql.org/pub/postgresql-v6.5.tar.gz 
         from the Internet. Store it in your home directory.
d486 6
a491 3
                     --prefix=BASEDIR   Selects a different base directory for the
                                        installation of the Postgres configuration.
                                        The default is /usr/local/pgsql.
d493 18
a510 9
                                        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
d512 2
a513 1
                     --enable-cassert   Enables ASSERT_CHECKING
d515 2
a516 1
                                        Use a specific C compiler that the configure
d520 6
a525 3
                                        Use a specific C++ compiler that the configure
                                        script cannot find, or exclude C++ compilation
                                        altogether.   (This only affects libpq++ at
d727 1
a727 1
           su postgres -c "/usr/local/pgsql/bin/postmaster \
d736 4
a739 4
                 /usr/local/pgsql/bin/postmaster \
                   -D/usr/local/pgsql/data \
                   -S -o -F > /usr/local/pgsql/errlog' \
                 & echo -n ' pgsql'
d754 3
a756 3
               "/usr/local/pgsql/bin/postmaster \
           -D/usr/local/pgsql/data \
               >> /usr/local/pgsql/server.log 2>&1 \
d849 4
a852 2
         UPDATE FirstTable SET PathCol = UpgradePath(PathCol);
         UPDATE SecondTable SET PathCol = UpgradePath(PathCol);
d867 2
a868 1
         # Also delete old database directory tree if it is not in
d884 2
a885 1
         GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
d968 12
a979 6
       +--------------+---------------+-------+
       |    Field     |     Type      | Length|
       +--------------+---------------+-------+
       | i            | int4          |     4 |
       | c            | (bp)char      |    16 |
       +--------------+---------------+-------+
d1016 2
a1017 1
         --prefix=PREFIX         install architecture-independent files in PREFIX
d1019 8
a1026 4
         --bindir=DIR            user executables in DIR [EPREFIX/bin]
         --libdir=DIR            object code libraries in DIR [EPREFIX/lib]
         --includedir=DIR        C header files in DIR [PREFIX/include]
         --mandir=DIR            man documentation in DIR [PREFIX/man]
d1028 2
a1029 1
         --disable-FEATURE       do not include FEATURE (same as --enable-FEATURE=no)
d1032 2
a1033 1
         --without-PACKAGE       do not use PACKAGE (same as --with-PACKAGE=no)
d1036 2
a1037 1
                                 use operating system template file
d1039 6
a1044 3
         --with-includes=incdir  site header files for tk/tcl, etc in DIR
         --with-libs=incdir      also search for libraries in DIR
         --with-libraries=libdir also search for libraries in DIR
d1046 2
a1047 1
         --enable-recode         enable cyrillic recode support
d1052 4
a1055 2
         --with-tcl              build Tcl interfaces and pgtclsh
         --with-tclconfig=tcldir tclConfig.sh and tkConfig.sh are in DIR
d1058 4
a1061 2
         --with-odbcinst=odbcdir change default directory for odbcinst.ini
         --enable-cassert        enable assertion checks (debugging)
d1151 4
d1158 2
a1159 2
       HSTYLE= /home/lockhart/SGML/db118.d/docbook/html
       PSTYLE= /home/lockhart/SGML/db118.d/docbook/print
d1324 4
a1327 6
        Parameter                     Example 
        user                          frew@@S2K.ORG 
        user                          aoki/HOST=miyu.S2K.Berkel-
                                     ey.EDU@@S2K.ORG 
        host                          postgres_dbms/ucbvax@@S2K.-
                                     ORG 
a1390 13
        Documentation
          New and updated material is present throughout the
         documentation. New FAQs have been contributed for SGI
         and AIX platforms. The Tutorial has introductory
         information on SQL from Stefan Simkovics. For the User's
         Guide, there are reference pages covering the postmaster
         and more utility programs, and a new appendix contains
         details on date/time behavior. The Administrator's Guide
         has a new chapter on troubleshooting from Tom Lane. And
         the Programmer's Guide has a description of query
         processing, also from Stefan, and details on obtaining
         the Postgres source tree via anonymous CVS and CVSup.

@


1.64
log
@Installation notes for v6.5.
Generated from install.sgml and installation.sgml.
@
text
@d1342 13
@


1.63
log
@Remove need for doc 'install man' in INSTALL file.  install does both
html and man.
@
text
@a0 2


a2 1

d5 1
a5 2
PostgreSQL is copyright (C) 1998
by the Postgres Global Development Group.
a19 6
             Ultrix4.x                                    
             Linux                                        
                 Linux ELF                                
                 Linux a.out                              
             BSD/OS                                       
             NeXT                                         
d31 3
a33 2
          Release 6.4                                     
             Migration to v6.4                            
d38 3
a40 3
       2-1. Supported Platforms                          
       2-2. Possibly Incompatible Platforms              
       4-1. Kerberos Parameter Examples                  
d65 1
a65 1
       This manual describes version 6.4 of Postgres. The 
d68 2
a69 1
       for the latest information.
d73 1
a73 1
       At the time of publication, the following platforms 
d77 79
a155 54
       OS             Processor     Version  Reported     Remarks
       AIX 4.2.1      RS6000        v6.4     1998-10-27   (Andreas Zeugswetter)
       BSDI           x86           v6.4     1998-10-25   (Bruce Momjian
       FreeBSD        x86           v6.4     1998-10-26   (Tatsuo Ishii, Marc 
       2.2.x-3.x                                          Fournier)
       DGUX 5.4R4.11  m88k          v6.3     1998-03-01   v6.4 probably OK. Needs 
                                                          new maintainer. (Brian E 
                                                          Gallew)
       Digital Unix   Alpha         v6.4     1998-10-29   Minor patchable problems 
       4.0                                                (Pedro J. Lobo)
       HPUX           PA-RISC       v6.4     1998-10-25   Both 9.0x and 10.20 
                                                          (Tom Lane, Stan Brown)
       IRIX 6.x       MIPS          v6.3     1998-03-01   5.x is different (Andrew 
                                                          Martin)
       linux 2.0.x    Alpha         v6.3.2   1998-04-16   Mostly successful. Needs 
                                                          work for v6.4. (Ryan 
                                                          Kirkpatrick)
       linux 2.0.x    x86           v6.4     1998-10-27   (Thomas Lockhart)
       linux          x86           v6.4     1998-10-25   (Oliver Elphick, Taral)
       2.0.x/glibc2
       linux 2.0.x    Sparc         v6.4     1998-10-25   (Tom Szybist)
       linuxPPC       PPC603e       v6.4     1998-10-26   Powerbook 2400c (Tatsuo 
       2.1.24                                             Ishii)
       mklinux DR3    PPC750        v6.4     1998-09-16   PowerMac 7600 (Tatsuo 
                                                          Ishii)
       NetBSD/i386    x86           v6.4     1998-10-25   (Brook Milligan)
       1.3.2
       NetBSD-        NS32532       v6.4     1998-10-27   (small problems in 
       current                                            date/time math 
                                                          (Jon Buller)
       NetBSD/sparc   Sparc         v6.4     1998-10-27   (Tom I Helbekkmo)
       1.3H
       NetBSD 1.3     VAX           v6.3     1998-03-01   (Tom I Helbekkmo)
       SCO UnixWare   x86           v6.3     1998-03-01   aka UNIVEL (Billy G. 
       2.x                                                Allie)
       SCO UnixWare   x86           v6.4     1998-10-04   (Billy G. Allie)
       7
       Solaris        x86           v6.4     1998-10-28   (Marc Fournier)
       Solaris        Sparc         v6.4     1998-10-28   (Tom Szybist, Frank 
       2.6-2.7                                            Ridderbusch)
       SunOS 4.1.4    Sparc         v6.3     1998-03-01   patches submitted (Tatsuo 
                                                          Ishii)
       SVR4           MIPS          v6.4     1998-10-28   no 64-bit int support 
                                                          (Frank Ridderbusch)
       SVR4 4.4       m88k          v6.2.1   1998-03-01   confirmed with patching 
                                                          (Doug Winterburn)
       Windows NT     x86           v6.4     1998-10-08   Mostly working with the 
                                                          Cygwin library. No DLLs 
                                                          yet. (Horak Daniel) 


       Platforms listed for v6.3.x should also work with 
       v6.4, but we did not receive confirmation of such at 
       the time this list was compiled. 
d158 2
a159 4
         Postgres has recently been accomplished. Check the 
         Askesis Postgres Home Page for up to date 
         information. You may also want to look for 
         possible patches on the Postgres web site.
d163 1
a163 1
       There are a few platforms which have been attempted 
d169 15
a183 20
       OS        Processor  Version  Reported      Remarks
       MacOS     all        v6.3     1998-03-01    not library compatible; 
                                                   use ODBC/JDBC
       NetBSD    arm32      v6.3     1998-03-01    not yet working (Dave 
                                                   Millen)
       NetBSD    m68k       v6.3     1998-03-01    Amiga, HP300, Mac; not 
                                                   yet working (Henry Hotz)
       NextStep  x86        v6.x     1998-03-01    client-only support; 
                                                   v1.0.9 worked with 
                                                   patches (David Wetzel)
       Ultrix    MIPS,VAX?  v6.x     1998-03-01    no recent reports; 
                                                   obsolete?
       Windows   x86        v6.3     1998-03-01    not library compatible; 
                                                   client side maybe; use 
                                                   ODBC/JDBC


       Note that Windows ports of the frontend are 
       apparently possible using third-party Posix porting 
       tools and libraries.
d187 14
a200 11
       Complete installation instructions for Postgres v6.4.
       Before installing Postgres, you may wish to visit 
       www.postgresql.org for up to date information, 
       patches, etc.
       These installation instructions assume: 
       o Commands are Unix-compatible. See note below.
       o Defaults are used except where noted.
       o User postgres is the Postgres superuser.
       o The source path is /usr/src/pgsql (other paths are possible).
       o The runtime path is /usr/local/pgsql (other paths are possible).
       Commands were tested on RedHat Linux version 4.2 
d205 2
a206 2
       these commands.
       Our Makefiles require GNU make (called ?gmake? in this 
d211 1
a211 1
       the GNU form of make to succeed with an installation.
d215 6
a220 5
       Up to date information on supported platforms is at 
       http://www.postgresql.org/docs/admin/install.htm. In 
       general, most Unix-compatible platforms with modern 
       libraries should be able to run Postgres.
       Although the minimum required memory for running 
d225 2
a226 2
       you can never have too much memory.
       Check that you have sufficient disk space. You will 
d232 2
a233 2
       for the distribution tar file.
       We therefore recommend that during installation and 
d241 2
a242 2
       in a flat file.
       To check for disk space, use 
d245 2
d250 1
a250 2
       Procedure 3.1. Postgres Installation

a252 1

d263 1
a263 1
         Please note that a "tested" platform in the list 
a273 1

d275 1
a275 1
         commonly used) if it does not already exist. 
a279 1

d282 1
a282 2
         happen in this account. 

d284 1
a284 1
         ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz
a285 1

d290 5
a294 6

         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 
d296 1
a296 1
         If you need flex and don't have it or have the 
d324 1
a324 1
         This will update files /usr/man/man1/flex.1, 
a327 1

d329 1
a329 1
         skip to  step 9. If you are upgrading an existing 
d338 3
a340 3
         Tip: Do not use the pg_dumpall script from v6.0 or 
            everything will be owned by the Postgres super 
            user.
d344 1
a344 1
         $ pg_dumpall -z > db.out
d350 1
a350 1
         $ gunzip -c postgresql-v6.4.tar.gz \
d353 1
a353 1
         $ src/bin/pg_dump/pg_dumpall -z > db.out
d355 1
a355 1
         If you wish to preserve object id's (oids), then 
d360 1
a360 1
         If the pg_dumpall command seems to take a long 
d366 1
a366 1
         Please note that if you are upgrading from a 
d374 1
a374 1
              You must make sure that your database is not 
a389 1

d409 1
a409 1
         Type the following: 
d416 2
a417 2
         If you are not using /usr/local/pgsql/data as your 
         data directory (check to see if environment 
a420 1

d423 2
a424 2
         installation but you must be consistant throughout 
         this procedure. 
d426 1
a426 1
         Note: There are two places in this installation 
d431 1
a431 1
            make install stage of installation.
d433 1
a433 1
         Type 
d444 1
a444 1
         $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
d464 4
a467 3
                 scrappy@@hub.org with the output of the 
                 program ./config.guess. Indicate what the 
                 template file should be.
d469 1
a469 1
            b. Choose configuration options. Check  
d482 2
a483 1
                     --prefix=BASEDIR   Selects a different base directory
d496 1
a496 2
                     --enable-cassert   Enables 
              ASSERT_CHECKING
d506 2
a507 1
            c. Here is the configure script used on a Sparc Solaris 2.5 system with /opt/postgres 
d523 1
a523 4

       13.     <removed>

       14.     Compile the program. Type 
d527 1
a527 1
         The last line displayed will hopefully be 
d530 2
a531 1
          At this point, or earlier if you wish, type 
d540 1
a540 1
         If the compiler fails with a message stating that 
d544 1
a544 1
         $ make clean
d546 1
a546 1
         Compiler options, such as optimization and 
d553 1
a553 2

       15.     Install the program. Type 
d557 1
a557 1
         The last line displayed will be 
d561 3
a563 3
         control-C to get out of tail.

       16.     If necessary, tell your system how to find 
d565 1
a565 1
         following, preferably the first: 
d576 1
a576 1
         Please note that the above commands may vary 
d580 1
a580 1
         If, when you create the database, you get the 
d585 1
a585 2

       17.     If you used the --with-perl option to 
d595 5
a599 4
         $ cd /usr/src/pgsql/src/interfaces/perl5
         $ gmake install

       18.     If it has not already been done, then prepare 
d602 1
a602 1
         There are several ways to influence the runtime 
d610 1
d613 8
a620 6
              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
            b. Several regression tests could failed if the 
d623 1
a623 1
              If you configure and compile Postgres with 
d629 9
a637 4
              LC_COLLATE=C
              LC_CTYPE=C
              LC_COLLATE=C
              export LC_COLLATE LC_CTYPE LC_COLLATE
d642 4
a645 3
              $ source ~/.bash_profile

       19.     Create the database installation from your 
d650 1
a650 2

       20.     Set up permissions to access the database 
d662 2
a663 3

       21.     Briefly test that the backend will start and 
         run by running it from the command line. 
d679 1
a679 2

       22.     Run postmaster in the background from your 
d682 1
a682 1
         account! 
d688 1
a688 1
         Here are some suggestions on how to do this, 
d690 1
a690 1
         Whatever you do, postmaster must be run by the 
d706 1
a706 1
           su postgres -c "/usr/local/pgsql/bin/postmaster 
d715 4
a718 4
           /usr/local/pgsql/bin/postmaster
                   -D/usr/local/pgsql/data
                   -S -o -F > /usr/local/pgsql/errlog' &
               echo -n ' pgsql'
d724 1
a724 1
           postmaster process so the parent is init. 
d729 1
a729 1
           /etc/rc.d/rc5.d/S98postgres.init. 
d732 5
a736 4
           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"

d739 2
a740 3
           doesn't know if there are other side effects.) 

       23.     Run the regression tests. The file 
d749 1
a749 1
              You do not need to type gmake clean if this 
d751 1
a751 1
              You should get on the screen (and also 
d774 1
a774 1
                failed since this is the v6.4 regression 
d776 1
a776 9
              o   For the SPARC/Linux-ELF platform, using the 
                970525 beta version of Postgres 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.
              Even if a test result clearly indicates a 
d786 1
a786 1
              Conclusion? If you do see failures, try to 
d792 1
a792 1
              After running the regression tests, type 
d800 1
a800 2

       24.     If you haven't already done so, this would be 
d803 1
a803 1
         regular intervals: 
d805 1
a805 1
         Procedure 3.2. Minimal Backup Procedure
d807 1
a807 1
            up your database. 
d811 1
a811 8
            time. 

         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 crontab 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.)
d813 8
a820 1
       25.     If you are upgrading an existing system then 
d839 1
a839 2

       26.     If you are a new user, you may wish to play 
d841 7
a847 10

       27.     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.2.1.tar.gz

       28.     You will probably want to print out the 
d854 1
a854 1
         Here is how you might do it if you have 
d857 2
a858 1
         $ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
d865 1
a865 2

       29.     The Postgres team wants to keep Postgres 
d870 7
a876 4
         telling us the following: 
         o  The version of Postgres (v6.4, 6.3.2, beta 981014, etc.). 
         o  Your operating system (i.e. RedHat v5.1 Linux v2.0.34). 
         o  Your hardware (SPARC, i486, etc.). 
d882 2
a883 2
           need to report these. 
       30.     Now create, access and manipulate databases 
d943 6
a948 6
       +--------------+--------------+-------+
       |    Field     |    Type      | Length|
       +--------------+--------------+-------+
       | i            | int4         |     4 |
       | c            | (bp)char     |    16 |
       +--------------+--------------+-------+
d967 2
a968 50
         Note: Check for any platform-specific FAQs in the 
         doc/ directory of the source distribution. For 
         some ports, the notes below may be out of date.

Ultrix4.x

         Note: There have been no recent reports of Ultrix 
         usage with Postgres.

       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

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

       Linux a.out
       For non-ELF Linux, 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

BSD/OS

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

NeXT

       The NeXT port for v1.09 was supplied by Tom R. 
       Hageman. 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 Postgres for NEXTSTEP will be made 
       available to the general public. Contact Info@@RnA.nl 
       for information.
       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.
d974 2
a975 2
       The full set of parameters available in configure can 
       be obtained by typing 
d977 2
a978 1
       $ ./configure --help
d980 2
a981 1
       The following parameters may be of interest to 
d1004 1
a1004 2
         --enable-recode         enable cyrillic recode 
       support
d1007 3
a1009 1
         --with-tcl              use tcl
d1011 1
a1011 1
         --with-perl             use perl
d1017 2
a1018 1
         --without-CXX           do not build libpq++
d1020 2
a1021 1
       Some systems may have trouble building a specific 
d1024 2
a1025 2
       --without-CXX to encourage the build procedure to 
       ignore the libpq++ construction.
d1029 4
a1032 4
       Many installation-related parameters can be set in 
       the building stage of Postgres installation.
       In most cases, these parameters should be place in a 
       file, Makefile.custom, intended just for that 
d1040 2
a1041 1
       make [ variable=value [,...] ]
d1043 2
a1044 1
       A few of the many variables which can be specified 
d1046 9
a1054 6
       POSTGRESDIR 
         Top of the installation tree. 
       BINDIR 
         Location of applications and utilities. 
       LIBDIR 
         Location of object libraries, including shared 
d1056 6
a1061 4
       HEADERDIR 
         Location of include files. 
       ODBCINST 
         Location of installation-wide psqlODBC (ODBC) 
d1063 2
a1064 1
       There are other optional parameters which are not as 
d1068 3
a1070 2
       CFLAGS 
         Set flags for the C compiler. Should be assigned 
d1072 3
a1074 2
       YFLAGS 
         Set flags for the yacc/bison parser. -v might be 
d1078 6
a1083 4
       USE_TCL 
         Enable Tcl interface building. 
       HSTYLE 
         DocBook HTML style sheets for building the 
d1088 3
a1090 2
       PSTYLE 
         DocBook style sheets for building printed 
d1095 2
a1096 1
       Here is an example Makefile.custom for a PentiumPro 
d1107 5
a1111 2
       HSTYLE= /home/tgl/SGML/db118.d/docbook/html
       PSTYLE= /home/tgl/SGML/db118.d/docbook/print
d1115 2
d1118 3
a1120 2
         page for additional information on locale and 
         Russian language support.
d1122 1
a1122 1
       While doing a project for a company in Moscow, 
d1137 2
a1138 2
       incorporated into the Postgres distribution.
       People often complain that locale doesn't work for 
a1139 1

d1149 7
a1155 6
             #!/bin/sh

             export LC_CTYPE=koi8-r
             export LC_COLLATE=koi8-r
             postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe'

d1157 4
a1160 2
             /bin/su - postgres -c "/home/postgres/runpostgres"

d1166 1
a1166 1
             8:17[mira]:~/WWW/postgres>setenv LC_CTYPE 
d1168 3
a1170 3
             8:18[mira]:~/WWW/postgres>perl -v
             perl: warning: Setting locale failed.
             perl: warning: Please check that your locale 
d1172 5
a1176 6
                     LC_ALL = (unset),
                     LC_CTYPE = "not_exist",
                     LANG = (unset)
                 are supported and installed on your 
        system.
             perl: warning: Falling back to the standard 
d1178 2
a1179 1

d1186 2
a1187 1
        that the next libc will not break my locale.
d1191 1
a1191 1
       You can use ~* and order by operators for strings 
d1195 1
a1195 1
       variable.
d1199 2
a1200 2
       There is one evident drawback of using locale - it's 
       speed! So, use locale only if you really need it.
d1204 1
a1204 1
       Kerberos is an industry-standard secure 
d1206 1
a1206 1
       computing over a public network.
d1210 6
a1215 5
       The Kerberos authentication system is not distributed 
       with Postgres. Versions of Kerberos are typically 
       available as optional software from operating system 
       vendors. In addition, a source code distribution may 
       be obtained through MIT Project Athena. 
d1222 1
a1222 1
       Users located outside the United States of America 
d1225 4
a1228 3
       Government export regulations.
       Inquiries regarding your Kerberos should be directed 
       to your vendor or MIT Project Athena. Note that FAQLs 
d1230 4
a1233 2
       posted to the Kerberos mailing list (send mail to 
       subscribe), and USENET news group.
d1237 1
a1237 1
       Installation of Kerberos itself is covered in detail 
d1240 2
a1241 2
       readable by the Postgres account.
       Postgres and its clients can be compiled to use 
d1247 2
a1248 2
       own server key file.
       After compilation is complete, Postgres must be 
d1251 1
a1251 1
       details on registering services.
d1255 1
a1255 1
       After initial installation, Postgres should operate 
d1259 2
a1260 2
       psql.
       In the Kerberos Version 5 hooks, the following 
d1262 1
a1262 1
       o User principal names (anames) are assumed to 
d1265 1
a1265 1
       o The Postgres service is assumed to be have two 
d1269 2
d1273 6
a1278 6
       Param-   Example
       eter
       user     frew@@S2K.ORG
       user     aoki/HOST=miyu.S2K.Berkeley-
                .EDU@@S2K.ORG
       host     postgres_dbms/ucbvax@@S2K.ORG
d1281 3
a1283 2
       Support for Version 4 will disappear sometime after 
       the production release of Version 5 by MIT.
d1287 1
a1287 1
Release 6.4
d1289 53
a1341 38
       There are many new features and improvements in this 
       release. Thanks to our developers and maintainers, 
       nearly every aspect of the system has received some 
       attention since the previous release. Here is a 
       brief, incomplete summary: 
       o Views and rules are now functional thanks to 
        extensive new code in the rewrite rules system from 
        Jan Wieck. He also wrote a chapter on it for the 
        Programmer's Guide. 
       o Jan also contributed a second procedural language, 
        PL/pgSQL, to go with the original PL/pgTCL 
        procedural language he contributed last release. 
       o We have optional multiple-byte character set 
        support from Tatsuo Iishi to complement our 
        existing locale support. 
       o Client/server communications has been cleaned up, 
        with better support for asynchronous messages and 
        interrupts thanks to Tom Lane. 
       o The parser will now perform automatic type coersion 
        to match arguments to available operators and 
        functions, and to match columns and expressions 
        with target columns. This uses a generic mechanism 
        which supports the type extensibility features of 
        Postgres. There is a new chapter in the User's 
        Guide which covers this topic. 
       o Three new data types have been added. Two types, 
        inet and cidr, support various forms of IP network, 
        subnet, and machine addressing. There is now an 
        8-byte integer type available on some platforms. 
        See the chapter on data types in the User's Guide 
        for details. A fourth type, serial, is now 
        supported by the parser as an amalgam of the int4 
        type, a sequence, and a unique index. 
       o Several more SQL92-compatible syntax features have 
        been added, including INSERT DEFAULT VALUES 
       o The automatic configuration and installation system 
        has received some attention, and should be more 
        robust for more platforms than it has ever been. 
d1343 1
a1343 1
Migration to v6.4
d1345 1
a1345 1
       A dump/restore using pg_dump or pg_dumpall is 
d1347 44
a1390 1
       previous release of Postgres.
d1394 2
d1398 71
a1468 26
       Fix for a tiny memory leak in PQsetdb/PQfinish(Bryan)
       Remove char2-16 data types, use char/varchar(Darren)
       Pqfn not handles a NOTICE message(Anders)
       Reduced busywaiting overhead for spinlocks with many 
       backends (dg)
       Stuck spinlock detection (dg)
       Fix up "ISO-style" timespan decoding and 
       encoding(Thomas)
       Fix problem with table drop after rollback of 
       transaction(Vadim)
       Change error message and remove non-functional update 
       message(Vadim)
       Fix for COPY array checking
       Fix for SELECT 1 UNION SELECT NULL
       Fix for buffer leaks in large object calls(Pascal)
       Change owner from oid to int4 type(Bruce)
       Fix a bug in the oracle compatibility functions 
       btrim() ltrim() and rtrim()
       Fix for shared invalidation cache overflow(Massimo)
       Prevent file descriptor leaks in failed COPY's(Bruce)
       Fix memory leak in libpgtcl's pg_select(Constantin)
       Fix problems with username/passwords over 8 
       characters(Tom)
       Fix problems with handling of asynchronous NOTIFY in 
       backend(Tom)
       Fix of many bad system table entries(Tom)
d1472 100
a1571 136
       Upgrade ecpg and ecpglib,see 
       src/interfaces/ecpc/ChangeLog(Michael)
       Show the index used in an EXPLAIN(Zeugswetter)
       EXPLAIN  invokes  rule system and shows plan(s) for rewritten queries(Jan)
       Multi-byte awareness of many data types and functions, via configure(Tatsuo)
       New configure --with-mb option(Tatsuo)
       New initdb --pgencoding option(Tatsuo)
       New createdb -E multibyte option(Tatsuo)
       Select version(); now returns PostgreSQL version(Jeroen)
       Libpq now allows asynchronous clients(Tom)
       Allow cancel from client of backend query(Tom)
       Psql now cancels query with Control-C(Tom)
       Libpq users need not issue dummy queries to get NOTIFY messages(Tom)
       NOTIFY now sends sender's PID, so you can tell whether it was your own(Tom)
       PGresult struct now includes associated error message, if any(Tom)
       Define "tz_hour" and "tz_minute" arguments to date_part()(Thomas)
       Add routines to convert between varchar and bpchar(Thomas)
       Add routines to allow sizing of varchar and bpchar into target columns(Thomas)
       Add bit flags to support timezonehour and minute in data retrieval(Thomas)
       Allow more variations on valid floating point numbers (e.g. ".1", "1e6")(Thomas)
       Fixes for unary minus parsing with leading spaces(Thomas)
       Implement TIMEZONE_HOUR, TIMEZONE_MINUTE per SQL92 specs(Thomas)
       Check for and properly ignore FOREIGN KEY column constraints(Thomas)
       Define USER as synonym for CURRENT_USER per SQL92 specs(Thomas)
       Enable HAVING clause but no fixes elsewhere yet.
       Make "char" type a synonym for "char(1)" (actually implemented as bpchar)(Thomas)
       Save string type if specified for DEFAULT clause handling(Thomas)
       Coerce operations involving different data types(Thomas)
       Allow some index use for columns of different types(Thomas)
       Add capabilities for automatic type conversion(Thomas)
       Cleanups for large objects, so file is truncated on open(Peter)
       Readline cleanups(Tom)
       Allow psql  \f \ to make spaces as delimiter(Bruce)
       Pass pg_attribute.atttypmod to the frontend for column field lengths(Tom,Bruce)
       Msql compatibility library in /contrib(Aldrin)
       Remove the requirement that ORDER/GROUP BY clause identifiers be 
       included in the target list(David)
       Convert columns to match columns in UNION clauses(Thomas)
       Remove fork()/exec() and only do fork()(Bruce)
       Jdbc cleanups(Peter)
       Show backend status on ps command line(only works on some platforms)(Bruce)
       Pg_hba.conf now has a sameuser option in the database field
       Make lo_unlink take oid param, not int4
       New DISABLE_COMPLEX_MACRO for compilers that can't handle our macros(Bruce)
       Libpgtcl now handles NOTIFY as a Tcl event, need not send dummy queries(Tom)
       libpgtcl cleanups(Tom)
       Add -error option to libpgtcl's pg_result command(Tom)
       New locale patch, see docs/README/locale(Oleg)
       Fix for pg_dump so CONSTRAINT and CHECK syntax is correct(ccb)
       New contrib/lo code for large object orphan removal(Peter)
       New psql command "SET CLIENT_ENCODING TO 'encoding'" for multi-bytes
       feature, see /doc/README.mb(Tatsuo)
       /contrib/noupdate code to revoke update permission on a column
       Libpq can now be compiled on win32(Magnus)
       Add PQsetdbLogin() in libpq
       New 8-byte integer type, checked by configure for OS support(Thomas)
       Better support for quoted table/column names(Thomas)
       Surround table and column names with double-quotes in pg_dump(Thomas)
       PQreset() now works with passwords(Tom)
       Handle case of GROUP BY target list column number out of range(David)
       Allow UNION in subselects
       Add auto-size to screen to \d? commands(Bruce)
       Use UNION to show all \d? results in one query(Bruce)
       Add \d? field search feature(Bruce)
       Pg_dump issues fewer \connect requests(Tom)
       Make pg_dump -z flag work better, document it in manual page(Tom)
       Add HAVING clause with full support for subselects 
       and unions(Stephan)
       Full text indexing routines in contrib/fulltextindex(Maarten)
       Transaction ids now stored in shared memory(Vadim)
       New PGCLIENTENCODING when issuing COPY command(Tatsuo)
       Support for SQL92 syntax "SET NAMES"(Tatsuo)
       Support for LATIN2-5(Tatsuo)
       Add UNICODE regression test case(Tatsuo)
       Lock manager cleanup, new locking modes for LLL(Vadim)
       Allow index use with OR clauses(Bruce)
       Allows "SELECT NULL ORDER BY 1;"
       Explain VERBOSE prints the plan, and now pretty-prints the plan to
       the postmaster log file(Bruce)
       Add Indices display to \d command(Bruce)
       Allow GROUP BY on functions(David)
       New pg_class.relkind for large objects(Bruce)
       New way to send libpq NOTICE messages to a different location(Tom)
       New \w write command to psql(Bruce)
       New /contrib/findoidjoins scans oid columns to find join relationships(Bruce)
       Allow binary-compatible indices to be considered when checking for valid
       indices for restriction clauses containing a constant(Thomas)
       New ISBN/ISSN code in /contrib/isbn_issn
       Allow NOT LIKE, IN, NOT IN, BETWEEN, and NOT BETWEEN constraint(Thomas)
       New rewrite system fixes many problems with rules and views(Jan)
               * Rules on relations work
               * Event qualifications on insert/update/delete work
               * New OLD variable to reference CURRENT, CURRENT will be remove in future
               * Update rules can reference NEW and OLD in rule qualifications/actions
               * Insert/update/delete rules on views work
               * Multiple rule actions are now supported, surrounded by parentheses
               * Regular users can create views/rules on tables they have RULE permits
               * Rules and views inherit the permissions on the creator
               * No rules at the column level
               * No UPDATE NEW/OLD rules
               * New pg_tables, pg_indexes, pg_rules and pg_views system views
               * Only a single action on SELECT rules
               * Total rewrite overhaul, perhaps for 6.5
               * handle subselects
               * handle aggregates on views
               * handle insert into select from view works
       System indexes are now multi-key(Bruce)
       Oidint2, oidint4, and oidname types are removed(Bruce)
       Use system cache for more system table lookups(Bruce)
       New backend programming language PL/pgSQL in backend/pl(Jan)
       New SERIAL data type, auto-creates sequence/index(Thomas)
       Enable assert checking without a recompile(Massimo)
       User lock enhancements(Massimo)
       New setval() command to set sequence value(Massimo)
       Auto-remove unix socket file on startup if no postmaster running(Massimo)
       Conditional trace package(Massimo)
       New UNLISTEN command(Massimo)
       Psql and libpq now compile under win32 using win32.mak(Magnus)
       Lo_read no longer stores trailing NULL(Bruce)
       Identifiers are now truncated to 31 characters internally(Bruce)
       Createuser options now availble on the command line
       Code for 64-bit integer supported added, configure tested, int8 type(Thomas)
       Prevent file descriptor leaf from failed COPY(Bruce)
       New pg_upgrade command(Bruce)
       Updated /contrib directories(Massimo)
       New CREATE TABLE DEFAULT VALUES statement available(Thomas)
       New INSERT INTO TABLE DEFAULT VALUES statement available(Thomas)
       New DECLARE and FETCH feature(Thomas)
       libpq's internal structures now not exported(Tom)
       Allow up to 8 key indexes(Bruce)
       Remove ARCHIVE keyword, that is no longer used(Thomas)
       pg_dump -n flag to supress quotes around indentifiers
       disable system columns for views(Jan)
       new INET and CIDR types for network addresses(TomH, Paul)
       no more double quotes in psql output pg_dump now dumps views(Terry)
       new SET QUERY_LIMIT(Tatsuo,Jan)
d1575 19
a1593 30
       /contrib cleanup(Jun)
       Inline some small functions called for every row(Bruce)
       Alpha/linux fixes
       Hp/UX cleanups(Tom)
       Multi-byte regression tests(Soonmyung.)
       Remove --disabled options from configure
       Define PGDOC to use POSTGRESDIR by default
       Make regression optional
       Remove extra braces code to pgindent(Bruce)
       Add bsdi shared library support(Bruce)
       New --without-CXX support configure option(Brook)
       New FAQ_CVS
       Update backend flowchart in tools/backend(Bruce)
       Change atttypmod from int16 to int32(Bruce, Tom)
       Getrusage() fix for platforms that do not have it(Tom)
       Add PQconnectdb, PGUSER, PGPASSWORD to libpq man page
       NS32K platform fixes(Phil Nelson, John Buller)
       Sco 7/UnixWare 2.x fixes(Billy,others)
       Sparc/Solaris 2.5 fixes(Ryan)
       Pgbuiltin.3 is obsolete, move to doc files(Thomas)
       Even more documention(Thomas)
       Nextstep support(Jacek)
       Aix support(David)
       pginterface manual page(Bruce)
       shared libraries all have version numbers
       merged all OS-specific shared library defines into one file
       smarter TCL/TK configuration checking(Billy)
       smarter perl configuration(Brook)
       configure uses supplied install-sh if no install script found(Tom)
       new Makefile.shlib for shared library configuration(Tom)
@


1.62
log
@Generate from installation.sgml -> installation.rtf -> ApplixWare
 -> INSTALL with some cleanup in vi.
@
text
@d509 1
a509 1
       12.     Install the HTML documentation. Type 
d516 1
a516 3
       13.     Install the man page documentation. Type 
         $ cd /usr/src/pgsql/doc
         $ gmake man
@


1.62.2.1
log
@Remove need for doc 'install man' in INSTALL file.  install does both
html and man.
@
text
@d509 1
a509 1
       12.     Install the man and HTML documentation. Type 
d516 3
a518 1
       13.     <removed>
@


1.62.2.2
log
@Prepare for 6.4.1.
@
text
@d41 2
a42 2
          Release 6.4.1                                     
             Migration to v6.4.1                            
d74 1
a74 1
       This manual describes version 6.4.1 of Postgres. The 
d86 3
a88 3
       AIX 4.2.1      RS6000        v6.4.1     1998-10-27   (Andreas Zeugswetter)
       BSDI           x86           v6.4.1     1998-10-25   (Bruce Momjian
       FreeBSD        x86           v6.4.1     1998-10-26   (Tatsuo Ishii, Marc 
d90 1
a90 1
       DGUX 5.4R4.11  m88k          v6.3     1998-03-01   v6.4.1 probably OK. Needs 
d93 1
a93 1
       Digital Unix   Alpha         v6.4.1     1998-10-29   Minor patchable problems 
d95 1
a95 1
       HPUX           PA-RISC       v6.4.1     1998-10-25   Both 9.0x and 10.20 
d100 1
a100 1
                                                          work for v6.4.1. (Ryan 
d102 2
a103 2
       linux 2.0.x    x86           v6.4.1     1998-10-27   (Thomas Lockhart)
       linux          x86           v6.4.1     1998-10-25   (Oliver Elphick, Taral)
d105 2
a106 2
       linux 2.0.x    Sparc         v6.4.1     1998-10-25   (Tom Szybist)
       linuxPPC       PPC603e       v6.4.1     1998-10-26   Powerbook 2400c (Tatsuo 
d108 1
a108 1
       mklinux DR3    PPC750        v6.4.1     1998-09-16   PowerMac 7600 (Tatsuo 
d110 1
a110 1
       NetBSD/i386    x86           v6.4.1     1998-10-25   (Brook Milligan)
d112 1
a112 1
       NetBSD-        NS32532       v6.4.1     1998-10-27   (small problems in 
d115 1
a115 1
       NetBSD/sparc   Sparc         v6.4.1     1998-10-27   (Tom I Helbekkmo)
d120 1
a120 1
       SCO UnixWare   x86           v6.4.1     1998-10-04   (Billy G. Allie)
d122 2
a123 2
       Solaris        x86           v6.4.1     1998-10-28   (Marc Fournier)
       Solaris        Sparc         v6.4.1     1998-10-28   (Tom Szybist, Frank 
d127 1
a127 1
       SVR4           MIPS          v6.4.1     1998-10-28   no 64-bit int support 
d131 1
a131 1
       Windows NT     x86           v6.4.1     1998-10-08   Mostly working with the 
d137 1
a137 1
       v6.4.1, but we did not receive confirmation of such at 
d177 1
a177 1
       Complete installation instructions for Postgres v6.4.1.
d273 1
a273 1
         ftp://ftp.postgresql.org/pub/postgresql-v6.4.1.tar.gz
d342 1
a342 1
         $ gunzip -c postgresql-v6.4.1.tar.gz \
d438 1
a438 1
         $ gunzip -c ~/postgresql-v6.4.1.tar.gz | tar xvf -
d763 1
a763 1
                failed since this is the v6.4.1 regression 
d873 1
a873 1
         o  The version of Postgres (v6.4.1, 6.3.2, beta 981014, etc.). 
d1299 1
a1299 1
Release 6.4.1
d1340 1
a1340 1
Migration to v6.4.1
a1341 1
       A dump/restore is not required for those upgrading from 6.4.
d1343 2
a1344 4
       required for those wishing to migrate data from pre-6.4
       releases of Postgres.  pg_upgrade may be helpful for those
       upgrading from 6.3.*.

@


1.62.2.3
log
@Update for 6.4.2.
@
text
@d41 2
a42 2
          Release 6.4.2                                     
             Migration to v6.4.2                            
d74 1
a74 1
       This manual describes version 6.4.2 of Postgres. The 
d86 3
a88 3
       AIX 4.2.1      RS6000        v6.4.2     1998-10-27   (Andreas Zeugswetter)
       BSDI           x86           v6.4.2     1998-10-25   (Bruce Momjian
       FreeBSD        x86           v6.4.2     1998-10-26   (Tatsuo Ishii, Marc 
d90 1
a90 1
       DGUX 5.4R4.11  m88k          v6.3     1998-03-01   v6.4.2 probably OK. Needs 
d93 1
a93 1
       Digital Unix   Alpha         v6.4.2     1998-10-29   Minor patchable problems 
d95 1
a95 1
       HPUX           PA-RISC       v6.4.2     1998-10-25   Both 9.0x and 10.20 
d100 1
a100 1
                                                          work for v6.4.2. (Ryan 
d102 2
a103 2
       linux 2.0.x    x86           v6.4.2     1998-10-27   (Thomas Lockhart)
       linux          x86           v6.4.2     1998-10-25   (Oliver Elphick, Taral)
d105 2
a106 2
       linux 2.0.x    Sparc         v6.4.2     1998-10-25   (Tom Szybist)
       linuxPPC       PPC603e       v6.4.2     1998-10-26   Powerbook 2400c (Tatsuo 
d108 1
a108 1
       mklinux DR3    PPC750        v6.4.2     1998-09-16   PowerMac 7600 (Tatsuo 
d110 1
a110 1
       NetBSD/i386    x86           v6.4.2     1998-10-25   (Brook Milligan)
d112 1
a112 1
       NetBSD-        NS32532       v6.4.2     1998-10-27   (small problems in 
d115 1
a115 1
       NetBSD/sparc   Sparc         v6.4.2     1998-10-27   (Tom I Helbekkmo)
d120 1
a120 1
       SCO UnixWare   x86           v6.4.2     1998-10-04   (Billy G. Allie)
d122 2
a123 2
       Solaris        x86           v6.4.2     1998-10-28   (Marc Fournier)
       Solaris        Sparc         v6.4.2     1998-10-28   (Tom Szybist, Frank 
d127 1
a127 1
       SVR4           MIPS          v6.4.2     1998-10-28   no 64-bit int support 
d131 1
a131 1
       Windows NT     x86           v6.4.2     1998-10-08   Mostly working with the 
d137 1
a137 1
       v6.4.2, but we did not receive confirmation of such at 
d177 1
a177 1
       Complete installation instructions for Postgres v6.4.2.
d273 1
a273 1
         ftp://ftp.postgresql.org/pub/postgresql-v6.4.2.tar.gz
d342 1
a342 1
         $ gunzip -c postgresql-v6.4.2.tar.gz \
d438 1
a438 1
         $ gunzip -c ~/postgresql-v6.4.2.tar.gz | tar xvf -
d763 1
a763 1
                failed since this is the v6.4.2 regression 
d873 1
a873 1
         o  The version of Postgres (v6.4.2, 6.3.2, beta 981014, etc.). 
d1299 1
a1299 1
Release 6.4.2
d1340 1
a1340 1
Migration to v6.4.2
@


1.61
log
@shared library instructions.
@
text
@a0 2
POSTGRESQL INSTALLATION INSTRUCTIONS
Copyright (c) 1997 Regents of  the University of California
d2 1172
a1173 483
This is file /usr/src/pgsql/INSTALL.  It contains notes on how to install
PostgreSQL v6.4.  Up to date information on PostgreSQL may be found at
http://www.postgresql.org.

PostgreSQL is an RDBMS 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 are Unix-compatible. See note below.
  - Defaults are used except where noted.
  - User postgres is the Postgres superuser.
  - The source path is /usr/src/pgsql (other paths are possible).
  - The runtime path is /usr/local/pgsql (other paths are possible).

Commands were tested on RedHat Linux version 4.0 using the bash shell.
Except where noted, they will probably work on most systems. Commands
like ps and tar vary wildly on what options you should use on each
platform. USE COMMON SENSE before typing in these commands.

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 or 4.x
   alpha          DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0
   BSD44_derived  OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
   bsdi           BSD/OS 2.0, 2.01, 2.1, 3.0
   dgux           DG/UX 5.4R4.11
   hpux           HP PA-RISC on HP-UX 9.0, 10
   i386_solaris   i386 Solaris
   irix5          SGI MIPS on IRIX 5.3
   linux          Intel x86 on Linux 2.0 and Linux ELF
                  SPARC on Linux ELF
                  PPC on Linux ELF
                  (For non-ELF Linux, see LINUX_ELF below).
   sco            SCO 3.2v5
   sparc_solaris  SUN SPARC on Solaris 2.4, 2.5, 2.5.1
   sunos4         SUN SPARC on SunOS 4.1.3
   svr4           Intel x86 on Intel SVR4 and MIPS
   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 45 MB of disk space
to hold the source, binaries, and user databases.  After installation
you may reduce this to about 3 Mbytes plus space for user databases.

To those upgrading from PostgreSQL 6.3.*:
----------------------------------------

A dump/restore is required for those running 6.3.*, or you can use the
new pg_upgrade command to upgrade your data files without
dumping/loading them.  See the new pg_upgrade manual page.

To those doing a fresh install or upgrading from previous releases of
PostgreSQL:
----------------------------------------------

  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.

     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 PostgreSQL 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 ftp://ftp.postgresql.org/pub/INSTALL.

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

  3) Log into account postgres.

  3a) Check that you have sufficient disk space.  You will need about
      17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
      (excluding your database) and 1 Mbyte for an empty database.
      For the regression tests, you will need an extra 20 Mbytes.
      You will also need about 3 Mbytes for the distribution tar file.

      We therefore recommend that during installation and testing you
      have well over 20 Mbytes free under /usr/local and another 5 MB
      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 /usr/local/pgsql, 1 Mbyte for the empty
      database, plus about five times the space you would require to
      store your database data in a flat file.

      To check for disk space, use command "df -k".

  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-6.4.tar.gz from the
     Internet.  Store it in your home directory.

  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 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.  Type (with the gunzip line and the following line typed as one
     line):
        cd
        gunzip -c postgresql-6.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 > db.out
        rm -rf src
     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, don't do it.

     If the pg_dumpall command seems to take a long time and you think
     it might have died, then, from another terminal, use "ls -l db.out"
     several times to see if the size of the file is growing.

     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 the appropriate files 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.  The actual paths can be
     different for your installation; be consistant with your configuration
     in step (11).
     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-6.4.tar.gz | tar xvf -

 11) Configure the source code for your system.  It is this step at which
     you can specify your actual source path and installation paths for
     the build process (see the --prefix option below).  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 (DEFAULT)

       --enable-locale    Enables USE_LOCALE

       --enable-cassert   Enables ASSERT_CHECKING

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

       --with-tcl         Enables programs requiring Tcl/Tk and X11,
                          including pgtclsh and libpgtcl.

       --with-perl        Enables the perl interface.

       --with-includes=DIRS
                          Include DIRS in list of directories searched
                          for header files.  (Typical use will need
                          --with-includes=/usr/local/include)

       --with-libs=DIRS
       --with-libraries=DIRS
                          Include DIRS in list of directories searched
                          for archive libraries.  (Typical use will need
                          --with-libraries=/usr/local/lib)

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

     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

     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.  You can
     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=$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, you can NOT copy file pg_hba.conf from your
     old database on top of the one in your new database.  You will
     have to re-do your changes.


 18) If you wish to skip the regression tests then skip to step 21.

     The file /usr/src/pgsql/src/test/regress/README has detailed
     instructions for running and interpreting the regression tests.
     A short version follows here:

     Start the postmaster in preparation for the regression tests.  First,
     set the timezone for Berkeley, California.  On some systems you may do
     this by setting environment variable TZ.  I.e., using bash, type
        export TZ=PST8PDT

     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 can be normal for some of the tests to
     "fail".  For the failed tests, use diff to compare the files in
     directories ./results and ./expected.  If float8 failed, type
     something like:
        cd /usr/src/pgsql/src/test/regress
        diff -w expected/float8.out results

    "Failed" tests may have failed due to slightly different error messages,
     output formatting, failure to set the timezone correctly for your
     platform, etc.  "Failures" of this type do not indicate a problem with
     PostgreSQL.

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

     For the SPARC/Linux-ELF platform, using the 970525 beta version of
     PostgreSQL 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.

     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 PostgreSQL.  However, keep in mind that this is likely
     to be the most solid release of PostgreSQL to date, incorporating many
     bug fixes from v6.2.1, and that previous versions of PostgreSQL have been
     in use successfully for some time now.

     After running the tests, type
        destroydb regression
        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 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.
a1174 209
             [ -x /usr/local/pgsql/bin/postmaster ] && {
               su -l postgres -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 most
          other examples, this one has been tested.

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

       d) The contrib/linux area of the PostgreSQL distribution has an example
          init.d script compatible with and tested using recent RedHat packages.

 22a) 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:

        a) Run the SQL command vacuum.  This will clean up your database.
        b) Back up your system.  (You should probably keep the last few
           backups on hand.)  Ideally, no one else should be using the
           system at the time.

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

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

     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)
        update YourTable set PathCol = UpgradePath(PathCol);
        update YourTable set PolyCol = UpgradePoly(PolyCol);
        ...
        vacuum;

     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.

 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-6.4.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) The Postgres team wants to keep PostgreSQL working on all of the
     supported platforms.  We therefore ask you to let us know if you did
     or did not get PostgreSQL to work on you system.  Please send a
     mail message to pgsql-ports@@postgresql.org telling us the following:
       - The version of PostgreSQL (6.4, 6.3.2, beta 970703, etc.).
       - Your operating system (i.e. RedHat v4.0 Linux v2.0.26).
       - Your hardware (SPARC, i486, etc.).
       - 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.

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

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

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

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

foo=> \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:
        A linux-2.0.30/libc-5.3.12/RedHat-4.2 running on a dual processor
        i686 is the regression testing reference machine.
        The linux-elf port installs cleanly. If you are using an
        i486 processor or higher, you can edit template/linux-elf
        to include "-m486" as a compiler option. configure does not
        detect that sigsetjmp() is available, but you can edit
        include/config.h after running configure and before running
        make to include "#define HAVE_SIGSETJMP 1". Note that I have
        not seen any difference in PostgreSQL behavior either way.
                                (Thomas G. Lockhart
                                <lockhart@@alumni.caltech.edu> 97/10/14)

        For non-ELF Linux, 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)

BSD/OS:
        For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.

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.
d1176 374
@


1.60
log
@New shared library mentions.
@
text
@d339 2
a340 3
 14) If necessary, tell UNIX how to find your shared libraries.  If you
     are using an ELF-based system, such as Linux, do ONE of the following,
     preferably the first:
@


1.59
log
@Recommend ldconfig on any ELF.
@
text
@d340 1
a340 1
     are using Linux/ELF or any ELF-based system, do ONE of the following,
@


1.58
log
@Update INSTALL to mention pg_upgrade.
@
text
@d340 2
a341 1
     are using Linux-ELF do ONE of the following, preferably the first:
@


1.57
log
@Update INSTALL, etc. for release 6.4.  Update pgaccess to 0.88.
@
text
@d74 3
a76 2
A dump/restore is required for those running 6.3.*.  pg_dumpall can help
with this task.
@


1.56
log
@Here are two patches to fix up the c++ (and c) support in the
configuration system.  The idea is to make the configure arguments
that specify compilers to be compatible with the other --with
options.  The main point, though, is that the c++ support is on by
default, but can easily be disabled by the --without-CXX option
for those few(?) that don't want it.

Brook Milligan
@
text
@d5 1
a5 1
PostgreSQL v6.3.2.  Up to date information on PostgreSQL may be found at
d71 2
a72 7
To those upgrading from PostgreSQL 6.3:
---------------------------------------

A dump/restore is NOT required for those running 6.3.  A
'make distclean', 'make', and 'make install' is all that is required.
This last step should be performed while the postmaster is not running.
You should re-link any custom applications that use PostgreSQL libraries.
d74 2
d118 1
a118 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-6.3.2.tar.gz from the
d160 1
a160 1
        gunzip -c postgresql-6.3.2.tar.gz |
d226 1
a226 1
        gunzip -c ~/postgresql-6.3.2.tar.gz | tar xvf -
d433 1
a433 1
     v6.3.2 regression testing reference platform.
d553 1
a553 1
        rm ~/postgresql-6.3.2.tar.gz
d580 1
a580 1
       - The version of PostgreSQL (6.3.2, 6.2.1, beta 970703, etc.).
@


1.55
log
@Make regression optional.
@
text
@d289 10
@


1.54
log
@removed constraint for perl: installed pgsql
@
text
@d108 2
a109 3
      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.
d112 1
a112 1
      have well over 20 Mbytes free under /usr/local and another 25 Mbytes
a384 1
     However, we think skipping the tests is a BAD idea!
@


1.53
log
@Remove --disable in configure
@
text
@d277 1
a277 2
       --with-perl        Enables the perl interface.  Note that this
                          requires an installed version of postgreSQL.
@


1.52
log
@Cleanups for large objects, so file is trucated on open, fix for
solaris/spare shared libararies, new error message for postmaster
startup, and makefile cleanups.
@
text
@a257 2
       --disable-hba      Disables Host Based Authentication

a259 2
       --disable-locale   Disables USE_LOCALE (DEFAULT)

a261 2
       --disable-cassert  Disables ASSERT_CHECKING (DEFAULT)

d296 1
a296 1
		--enable-hba --disable-locale
@


1.51
log
@From: Brook Milligan <brook@@trillium.NMSU.Edu>

Here is a pair of patches that (I hope) finish the configuration
issues with tcl/tk and make the recognition of the two packages
completely parallel in organization.  This should make future changes
easier to maintain.

Hope to see this in 6.2.2.
@
text
@d122 1
a122 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.2.tar.gz from the
d164 1
a164 1
        gunzip -c postgresql-v6.3.2.tar.gz |
d230 1
a230 1
        gunzip -c ~/postgresql-v6.3.2.tar.gz | tar xvf -
d490 1
a490 1
               su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
d555 1
a555 1
        rm ~/postgresql-v6.3.2.tar.gz
d582 1
a582 1
       - The version of PostgreSQL (v6.3.2, 6.2.1, beta 970703, etc.).
@


1.50
log
@Update for 6.3.2
@
text
@d291 1
@


1.49
log
@Here are 3 patches (all relative to the src directory) to help with
the configuration of v6.3.1.  I have replaced the queries for
include/lib directories with --with configuration options.  I have
also included a list of potential tcl/tk include directories directly
in the CPPFLAGS variable.  As new versions are needed, these should
be added to the list in reverse numerical order (libraries are in
a separate list near the end).  This greatly simplifies the later
checks if --with-tcl is set.  I hope this solution works for
everyone.

I also added a check to disable the perl support if postgres was
not already installed (as per the instructions in the directory).
By the way, why must there be an installed pgsql to compile perl
support? This seems odd, at best.

Finally, I changed the Makefile in the libpgtcl interface to place
the shared libraries at the end of the list of files, not at the
beginning.  With NetBSD at least, libraries are linked in order,
so the original sequence does not work.

Brook Milligan
@
text
@d5 1
a5 1
PostgreSQL v6.3.1.  Up to date information on PostgreSQL may be found at
d122 1
a122 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.1.tar.gz from the
d164 1
a164 1
        gunzip -c postgresql-v6.3.1.tar.gz |
d180 2
a181 1
     You should also read files /usr/src/pgsql/migration/*.
d230 1
a230 1
        gunzip -c ~/postgresql-v6.3.1.tar.gz | tar xvf -
d434 1
a434 1
     v6.3.1 regression testing reference platform.
d554 1
a554 1
        rm ~/postgresql-v6.3.1.tar.gz
d581 1
a581 1
       - The version of PostgreSQL (v6.3.1, 6.2.1, beta 970703, etc.).
@


1.48
log
@install cleanup
@
text
@a278 3
       --with-defaults    Use default responses to several queries during
                          configuration.

d284 10
@


1.47
log
@update for 6.3.1
@
text
@d496 1
a496 1
                     >> /usr/local/pgsql/server.log 2>&1" /dev/null
@


1.46
log
@Configure patches from Brook Milligan.
@
text
@d5 1
a5 1
PostgreSQL v6.3.  Up to date information on PostgreSQL may be found at
d71 9
d122 1
a122 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.tar.gz from the
d164 1
a164 1
        gunzip -c postgresql-v6.3.tar.gz |
d229 1
a229 1
        gunzip -c ~/postgresql-v6.3.tar.gz | tar xvf -
d426 1
a426 1
     v6.3 regression testing reference platform.
d519 1
a519 1
 23) If you are upgrading an existing system then install your old database.
d546 1
a546 1
        rm ~/postgresql-v6.3.tar.gz
d573 1
a573 1
       - The version of PostgreSQL (v6.3, 6.2.1, beta 970703, etc.).
@


1.45
log
@Upgrade doc stuff to 6.3.
@
text
@d270 9
@


1.44
log
@Cleanups for 6.2.1.
@
text
@d5 1
a5 1
PostgreSQL v6.2.1.  Up to date information on PostgreSQL may be found at
d113 1
a113 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.2.1.tar.gz from the
d152 2
a153 3
     step.  Also, do not use the pg_dumpall script from v6.0 or everything
     will be owned by the Postgres super user.  Type (with the gunzip line
     and the following line typed as one line):
d155 1
a155 1
        gunzip -c postgresql-v6.2.1.tar.gz |
d220 1
a220 1
        gunzip -c ~/postgresql-v6.2.1.tar.gz | tar xvf -
d360 4
a363 3
     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.
d408 1
a408 1
     v6.2.1 regression testing reference platform.
d420 1
a420 1
     bug fixes from v6.1, and that previous versions of PostgreSQL have been
d528 1
a528 1
        rm ~/postgresql-v6.2.1.tar.gz
d555 1
a555 1
       - The version of PostgreSQL (v6.2.1, 6.1.1, beta 970703, etc.).
@


1.43
log
@Small updates for v6.2.1.
@
text
@d5 1
a5 1
PostgreSQL v6.2.  Up to date information on PostgreSQL may be found at
d528 1
a528 1
        rm ~/postgresql-v6.2.tar.gz
d555 1
a555 1
       - The version of PostgreSQL (v6.2, 6.1.1, beta 970703, etc.).
@


1.42
log
@Document which is default for:

	enable-hba/enable-cassert/enable-locale
@
text
@d14 2
a15 3
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.
d20 1
a20 1
  - User postgres is the postgres superuser.
d113 2
a114 2
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.2.tar.gz from the
     internet.  Store it in your home directory.
d148 7
a154 6
     The database format is liable to change every few weeks with no
     notice besides a quick comment in the HACKERS mailing list.  It is
     therefore a bad idea to skip this step.  Also, do not use the
     pg_dumpall script from v6.0 or everything will be owned by the
     postgres super user.  Type (with the gunzip line and the following
     line typed as one line):
d156 1
a156 1
        gunzip -c postgresql-v6.2.tar.gz |
d221 1
a221 1
        gunzip -c ~/postgresql-v6.2.tar.gz | tar xvf -
d381 1
a381 1
     Run postmaster from your postgres super user account (typically
d407 2
a408 3
     Here is an example from a i686/Linux-ELF platform (this is the platform
     on which most of the regression tests were generated). No tests failed
     since this is the v6.2 regression reference platform.
d410 2
a411 2
     Here is an example from the SPARC/Linux-ELF platform.  Using the
     970525 beta version of PostgreSQL v6.2 the following tests "failed".
d420 1
a420 1
     bug fixes from v6.0, and that previous versions of PostgreSQL have been
d436 1
a436 1
     Run postmaster from your postgres super user account (typically
d446 1
a446 1
     Whatever you do, postmaster must be run by user postgres, AND NOT BY
d458 1
a458 10
       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
d471 1
a471 1
          the postmaster process so the parent is init.  Note:  Unlike the
d474 11
a484 10
       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.)
d506 1
a506 1
     If your old database uses either path or polygon geometric data types,
d520 1
a520 1
 24) If you are a new user, you may wish to play with postgres as described
d642 2
d652 1
a652 1
                                <Thomas.Lockhart@@jpl.nasa.gov> 97/05/17)
d655 1
a655 1
        the system. It enables dynamic link loading capability to the postgres
@


1.41
log
@Update README, HISTORY, etc for beta release.
@
text
@d247 1
a247 1
       --enable-hba       Enables Host Based Authentication
d253 1
a253 1
       --disable-locale   Disables USE_LOCALE
d257 1
a257 1
       --disable-cassert  Disables ASSERT_CHECKING
a258 4
                          The default for ASSERT_CHECKING is normally
                          enabled for development versions and
                          disabled for release versions of PostgreSQL.
		
@


1.40
log
@Remove restart instructions from INSTALL.
@
text
@d5 1
a5 1
PostgreSQL v6.1.1.  Up to date information on PostgreSQL may be found at
d72 2
a73 11
To upgrade from PostgreSQL v6.1 to v6.1.1 do the following:
-----------------------------------------------------------
   1) Run configure on the new release
   2) Compile the new release
   3) Recompile your custom applications to use the new libpq library
   4) Stop the postmaster
   5) Install the new release
   6) Restart the postmaster

To those doing a fresh install or upgrading to PostgreSQL v6.1.1 
from 6.0 or 1.* release, do the following:
d114 1
a114 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.1.1.tar.gz from the
d156 1
a156 1
        gunzip -c postgresql-v6.1.1.tar.gz |
d221 1
a221 1
        gunzip -c ~/postgresql-v6.1.1.tar.gz | tar xvf -
d413 1
a413 1
     since this is the v6.1.1 regression reference platform.
d416 1
a416 1
     970525 beta version of PostgreSQL v6.1.1 the following tests "failed".
d541 1
a541 1
        rm ~/postgresql-v6.1.1.tar.gz
d568 1
a568 1
       - The version of PostgreSQL (v6.1, 6.1.1, beta 970703, etc.).
@


1.39
log
@Add PPC Linux to port list.
@
text
@a515 6
        c) Stop and restart the postmaster.  The software currently
           suffers from memory leaks.  This means that as more commands
           are processed, the program will allocate, then forget about,
           more and more memory.  Eventually your computer will run
           low on memory and start to swap excessively.  This problem
           will probably be gone in the next release.
@


1.38
log
@Add hpux 10 support to list.
@
text
@d53 1
@


1.37
log
@sco added to ports list
@
text
@d48 1
a48 1
   hpux           HP PA-RISC on HP-UX 9.0
@


1.36
log
@Solaris version update.
@
text
@d54 1
@


1.35
log
@Update supported ports.
@
text
@d54 1
a54 1
   sparc_solaris  SUN SPARC on Solaris 2.4
@


1.34
log
@Update for DGUX.
@
text
@d44 1
a44 1
   alpha          DEC Alpha AXP on Digital Unix 2.0 & 3.2
@


1.33
log
@Add sysv4 support to configure and docs.
@
text
@d47 1
a47 1
   dgux           DG/UX 5.4R3.10
@


1.32
log
@Update supported ports for 6.1.1 release.
@
text
@d56 1
a56 1
   svr4           Intel x86 on Intel SVR4
@


1.31
log
@Updates for 6.1.1.
@
text
@d44 1
a44 1
   alpha          DEC Alpha AXP on OSF/1 2.0
@


1.30
log
@MANPATH cleanup.
@
text
@d5 1
a5 1
PostgreSQL v6.1.  Up to date information on PostgreSQL may be found at
d43 1
a43 1
   aix            IBM on AIX 3.2.5
d46 1
a46 1
   bsdi           BSD/OS 2.0, 2.01, 2.1
d70 8
d79 2
a80 1
To upgrade to PostgreSQL v6.1 do the following:
d121 1
a121 1
  4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.1.tar.gz from the
d163 1
a163 1
        gunzip -c postgresql-v6.1.tar.gz |
d228 1
a228 1
        gunzip -c ~/postgresql-v6.1.tar.gz | tar xvf -
d420 1
a420 1
     since this is the v6.1 regression reference platform.
d423 1
a423 1
     970525 beta version of PostgreSQL v6.1 the following tests "failed".
d554 1
a554 1
        rm ~/postgresql-v6.1.tar.gz
d581 1
a581 1
       - The version of PostgreSQL (v6.1, v6.2 beta 970703, etc.).
@


1.29
log
@From: David Friend <dfriend@@atlsci.atlsci.com>
Subject: [PATCHES] Patch for INSTAL file.

The following patch does the following:

  - In step 6, recommend doing a database backup if you are upgrading
    from any version of the release, rather than ones before a specific
    date.

  - Added step 22a on regular maintainence.
@
text
@d343 1
a343 1
        MANPATH=/usr/local/pgsql/man
@


1.28
log
@From: PortSite <info@@portsite.nl>

Install file says: Type flex -- version
There is a space between -- and version that shouldn't
be there :-(
@
text
@d146 7
a152 6
  6) If you are upgrading an existing system from any version before
     version 6.1 beta release 970525 then back up the current
     database.  (If you don't mind the restored tables being owned by
     the postgres account then you may use your current pg_dumpall
     script instead of the new pg_dumpall script used below.)  Type
     (with the gunzip line and the following line typed as one line):
d497 20
a516 3
     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.
@


1.27
log
@Update comments for regression testing.
Include paragraph on upgrading old databases containing path or polygon types.
@
text
@d117 1
a117 1
        flex -- version
@


1.26
log
@From: David Friend <dfriend@@atlsci.atlsci.com>
Subject: [PATCHES] INSTALL patch

This patch makes the following changes to the INSTALL instructions:
  - Before step 1, describe disk space requirements.
  - Step 1 now defines a "tested" platform.
  - Add step 3a on checking for disk space.
  - Added new step 27 asking for feedback.
@
text
@d369 4
d376 1
a376 1
        export TZ=PST8PDT7,M04.01.0,M10.05.03
d409 2
a410 4
     on which most of the regression tests were generated). float8 failed
     on exponentiation and logarithmic operations due to known differences
     in error handling for those math functions between this platform
     and the original Sun (?) Postgres v4.2 development environment.
d415 2
a416 13
     floating point numbers.  float8 also "failed" due to a table being
     printed out in place of the expected warning message of a floating
     point number being out of range.  timespan and horology fail
     because of a bug on this platform that causes a timespan of
     "14 secs ago" to be returned as "1 day 23 hours 59 mins 46 secs
     ago".  (If you don't intend to use the timespan data type, then
     this would not be a problem for you.)  datetime also fails due
     to similar problems with the timespan data type.  errors fail
     due to a parsing error.  (This bug was introduced within the
     previous week, and is probably in the regression test itself.)
     select_views produces massively different output, but the
     differences are due to the timespan bug and minor floating point
     differences.  (Note:  The timespan bug was fixed before v6.1 came out.)
d422 1
a422 1
     bug fixes from v6.0, and that previous versions of PostgreSQL has been
d504 14
@


1.25
log
@From: David Friend <dfriend@@atlsci.atlsci.com>
Subject: [PATCHES] INSTALL changes

This patch modifies the INSTALL file.  The changes are:
  - SPARC/Linux-ELF was added to the list of supported platforms.
    The special notes for it at the bottom of the file were removed.
  - Changed "database server" to "RDBMS database server".
  - Modified step 6 so that when you restore your database the
    tables will be owned by the original owners instead of the
    postgresql superuser.
  - Modified step 19 on diagnosing the regression tests for the
    SPARC Linux platform with a beta release.
  - Other minor changes.
@
text
@d66 3
a68 2
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.
d82 9
d95 17
d162 4
d419 1
a419 1
     this will not be a problem for you.)  datetime also fails due
d424 2
a425 2
     differences are probably due to the same reasons the other tests
     failed.
d435 1
d545 14
a558 1
 27) Now create, access and manipulate databases as desired.  Write client
@


1.24
log
@Add information on regression testing and Linux ports.
Fix typos in TZ setting for regression testing and in gmake redirection.
@
text
@d8 1
a8 1
PostgreSQL is a database server.  It is not completely ANSI SQL
d52 1
d86 1
a86 1
     internet.
d120 5
a124 2
     version 6.1 beta release 970512 then back up the current
     database.  Type
d126 8
a133 6
        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.
d379 16
a394 9
     Here is an example from a SPARC/Linux-ELF platform (note that this is
     for an "unsupported" 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". datetime, abstime and tinterval had "GMT" for the time
     zone rather than "PST" or "PDT". These differences were due to a
     mis-typed string for the TZ environment variable from step (18).
     select_views failed for unknown reasons.
a607 4
        To compile with flex, you need a recent version (v2.5.2 or v2.5.4 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.

d609 1
a609 3
        For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2 or
        flex version 2.5.4 as well as the GNU dld library.
        Flex version 2.5.3 has a known bug on all platforms.
a617 25

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.  After running "configure" and before
        compiling PostgreSQL, make the following changes:
          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 
        For more details, look in ftp://ftp.postgresql.org/pub/majordomo/ports
        for a May 16, 1997 mail message called "regression tests on a
        SPARC/Linux platform".
@


1.23
log
@From: David Friend <dfriend@@atlsci.atlsci.com>

Here are the latest changes to the INSTALL instructions.

The main changes are:
  - Step 5, on flex
  - Steps 18 and 19, on regression tests
  - Step 22 c) on starting postmaster on bootup on FreeBSD
  - Added porting notes for SPARC/Linux at end.

If there is time, Thomas should review step 19.
@
text
@d19 2
a20 6
  - 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.
d22 7
d51 1
a51 1
   linux          Intel x86 on Linux 1.2 and Linux ELF
d166 4
a169 1
  9) Make new source and install directories.  Type
d183 3
a185 1
 11) Configure the source code for your system.  Type
d247 1
a247 1
        gmake all &> make.log &
d249 1
d270 1
a270 1
        gmake install &> make.install.log &
d272 1
d333 1
a333 1
     set the timezone for Berkley, California.  On some systems you may do
d335 2
a336 1
        export TZ=PST8PDT7,M04.01.0,M10.0503
d340 1
d355 4
a358 4
     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:
d361 28
a388 19
     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.)
d532 3
a534 2
(Don't ever forget those SQL semicolons.  Psql won't execute anything until it
sees the semicolon.)
d542 1
a542 1
template1=> CREATE TABLE bar (column1 int4, column2 char16);
d545 1
a545 1
template1=> \d bar
d578 14
a591 9
        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.
d595 1
a595 1
        To compile with flex, you need a recent version (2.5.2 or
d600 3
a602 2
        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.
d616 2
a617 2
        have a Linux-elf platform.  Between configuring and compiling
        PostgreSQL, edit the following files:
d633 2
a634 3
        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
@


1.22
log
@From: David Friend <dfriend@@atlsci.atlsci.com>
Subject: [PATCHES] Patch for INSTALL

The following patch makes a number of modifications to file INSTALL.
Among other things, it restores some platform specific notes I deleted.
It also no longer requires a separate compile for the regression tests.

Please note that this patch already incorporates the patch Hal Snyder
submitted on Monday.  Do not apply Hal's patch.
@
text
@d93 6
a114 4
     If you have flex v2.5.3 and do not have handy access to the
     internet, you can apply the patch in /usr/src/pgsql/doc/README.flex
     instead.

d167 1
a167 2
        chown postgres pgsql
        chgrp postgres pgsql
d170 1
a170 2
        chown postgres pgsql
        chgrp postgres pgsql
d319 4
a322 1
 18) Start the postmaster in preparation for the regression tests.  First,
d344 24
a367 5
     "fail".  For the failed tests, use diff to compare the files in
     directories ./results and ./expected.  "Failed" tests may have
     failed due to slightly different error messages, output formatting,
     failure to set the timezone correctly for your platform, etc.
     "Failures" of this type do not indicate a problem with PostgreSQL.
d412 3
a414 2
       c) In FreeBSD edit /usr/local/etc/rc.d/pgsql.sh to contain the
          following two lines, and make it 755 root:bin :
d416 11
a426 4
             [ -x /usr/local/pgsql/bin/postmaster ] &&
               su -l pgsql -c '/usr/local/pgsql/bin/postmaster
               -D/usr/local/pgsql/data -o -F > /usr/local/pgsql/errlog
               &' && echo -n ' pgsql'
d583 26
@


1.21
log
@From: David Friend <dfriend@@atlsci.atlsci.com>
Subject: [PATCHES] New INSTALL file.

I have created a much more comprehensive version of the
/usr/src/pgsql/INSTALL file.  It should replace the current 970428 version
of this file.
@
text
@d72 4
a75 3
     files in directory /usr/src/pgsql/doc, including platform specific
     notes for Irix and Linux.  Also look in directory
     ftp://ftp.postgresql.org/pub.
d84 2
a85 2
  5) Some platforms, like Linux and BSD/OS use flex.  If your system uses
     flex then make sure you have a good version.  Type
d88 1
d113 2
a114 1
  6) If you are upgrading an existing system then back up the current
d127 6
a141 5
     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.

d207 1
a207 1
       --enable-cassert   Enables ASSERT_CHECKING (default)
d210 4
d237 1
a237 6
 12) If you plan to run the regression tests, then turn off the genetic
     (GEQ) optimizer.  Edit file /usr/src/pgsql/src/include/config.h
     to comment out the line containing "#define GEQ" near the end of
     the file.

 13) Compile the program.  Type
d254 6
a259 1
 14) Install the program.  Type
d267 1
a267 1
 15) If necessary, tell UNIX how to find your shared libraries.  If you
d288 1
a288 1
 16) If it has not already been done, then prepare account postgres
d304 1
a304 1
 17) Create the database.  DO NOT DO THE FOLLOWING AS ROOT!  This would
d308 1
a308 1
 18) Set up permissions to access the database system.  Do this by editing
d319 3
a321 11
 19) If you are going to skip the regression tests then skip to step number
     24.  It is highly recommended that you do these tests in order to
     make sure that PostgreSQL is working on your system.  However, running
     them will probably increase your installation time by an hour or so.

     If you did not turn off the genetic optimizer (GEQ) before compiling
     then you should skip the regression tests.

 20) Log into a second shell as user postgres.  Set the timezone for Berkley,
     California.  On some systems you may do this by setting environment
     variable TZ.  I.e., using bash, type
d323 5
a327 4
     Now run postmaster by typing
        postmaster
     Leave this program running until after you finish running the regression
     tests in the other shell.  DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
d329 1
a329 1
 21) Run the regression tests.  From the first shell type
d340 6
a345 11
     failed.  Currently, tests sanity_check, float8, select and misc fail.
     (This may change between the time this note was written and the final
     release of v6.1.)  See the notes in file README for more detailed
     explanations.

     If you wish to know why some of the tests failed, you may use diff
     to compare the files in directories ./results and ./expected.

     If you did not set the timezone as indicated above or if you did not
     disable the genetic optimizer (GEQ) as described in step 8 then you
     will get a lot of failures.
d351 4
a354 24
 22) In the other window that is running postmaster, press control-C to
     stop the process.  Restore the timezone to normal.  (If you simply
     set TZ for this one shell, this is as simple of logging out of the
     shell.)

 23) Recompile the back end with the genetic optimizer (GEQ) turned on.
     This is not necessary but is highly recommended if you plan to use
     large databases.

     Go and restore file /usr/src/pgsql/src/include/config.h to the
     original state where "#define GEQ" is not commented out.

     Type the following:
        cd /usr/src/pgsql/src
        gmake all &> make2.log &
        tail -f make2.log
        # Once compiling is done, control-C out of tail.
        cd /usr/src/pgsql/src
        gmake install &> make.install2.log &
        tail -f make.install2.log
        # Once compiling is done, control-C out of tail.

 24) If you were skipping the regression tests then you skipped steps 20
     to 23 and continued here.
d356 1
a356 1
 25) Start the postmaster daemon running.  Type
d359 2
a360 2
     Run postmaster from your postgres super user account.  DO NOT RUN
     POSTMASTER FROM THE ROOT ACCOUNT.
d362 1
a362 1
 26) If you haven't already done so, this would be a good time to modify
d390 2
a391 3
       c) In FreeBSD edit an unspecified file that will, on boot up, run
          a file containing the short line followed by the following single
          line:
d393 4
a396 3
             [ -x /usr/local/pgsql/bin/postmaster ] && su -l pgsql -c
                     '/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
                     -o -F > /usr/local/pgsql/errlog &' && echo -n ' pgsql'
d398 2
a399 2
       d) In RedHat v4.0 Linux edit an unspecified file to contain the
          following single line:
d402 6
d410 2
a411 1
     the vacuum command nightly.
d413 1
a413 1
 27) If you are upgrading an existing system then install your old database.
d418 1
a418 1
 28) If you are a new user, you may wish to play with postgres as described
d421 1
a421 1
 29) Clean up after yourself.  Type
d428 1
a428 1
 30) You will probably want to print out the documentation.  Here is how
d449 1
a449 1
 31) Now create, access and manipulate databases as desired.  Write client
d503 2
a504 2
First, read files doc/FAQ in directory /usr/src/pgsql.  The latest version
of the FAQ may be found at http://www.postgresql.org/ under documentation.
d507 2
a508 2
in file /usr/src/pgsql/doc/bug.template and mail it to
pgsql-ports@@postgresql.org.
d514 39
@


1.20
log
@Remove chunk from regression tests about regress.out vs expected.out...the
tests now let you know if it is ok/failed :)
@
text
@d2 1
a2 1
Copyright (c) 1996 Regents of the University of California
d4 11
a14 5
This directory contains the source and documentation for PostgreSQL
(version 6.1) PostgreSQL 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
d18 16
d66 152
a217 2
MIGRATING FROM POSTGRES VERSION 1.*
-----------------------------------
d219 2
a220 88
People migrating data from earlier releases must dump the data under
1.09 and reload them under 6.1.  The pg_dump utility is designed to do
this.  It is important you use 1.09 because earlier releases may not
have the proper copy format to load into the 6.1 database.

INSTALLING POSTGRESQL
---------------------

Installing PostgreSQL encompasses only installing the software on your system
so you can use it to access (or create or manipulate) databases.  This
step does not include actually creating any database or configuring your 
system to use it.

Before you start, if you are using GNU flex, you should ensure that you
are not using Version 2.5.3. If you have this version, you should either
change to 2.5.2 or 2.5.4 or apply the patch in doc/README.flex

To install PostgreSQL on UNIX platforms:

1. Unpack the source distribution into a source directory.  We'll assume
   "/usr/src/pgsql" in this discussion.  This should be a new directory.
  
2. Set your current directory to the source directory:

   cd /usr/src/pgsql

3. Build PostgreSQL:

   If you're installing PostgreSQL on Ultrix 4.x or Linux, see the 
   porting notes at the end for additional packages that you need to install
   before installing PostgreSQL.

   If using Linux or Irix, you should also read the machine-specific FAQs.

   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 to the location of this program. (eg. bsdinst, which comes
   with the MIT X Window System distribution) 

   In the simplest version, you can just do the following:

     % cd 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 (default)

     --disable-cassert	Disables ASSERT_CHECKING
			
     --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.
d222 1
a222 1
     % ./configure --prefix=/opt/postgres 
d226 2
a227 85
   Of course, in a real shell, you would type these three lines all on the
   same line.

   After configure has completed running, you can make the binaries.  We use 
   'gmake' to mean GNU make.
    
     % gmake 

   The gmake ultimately issues the message "All of PostgreSQL is
   successfully made.  Ready to install."  If you don't get that, the make
   failed, and there should be error messages at the end detailing why.

4. Install PostgreSQL

   Installing just means placing all the files built in the previous step
   into their live locations on your system. 

     % gmake install

   This will narrate all the files being installed.  You should watch and 
   be sure the files are going to reasonable places and confirm for yourself
   that they ended up where they belong.

   Any error messages indicate something is wrong and you probably have to
   correct it before PostgreSQL will work.


HOW TO CREATE A DATABASE SYSTEM
-------------------------------

Once you have Postgres installed, you'll need at least one database system
on which to operate.  A database system is a collection of databases that
are used together and fall under a single authority.  You can have as many
database systems as you want on a single unix system.

You select a unix user to be the "postgres superuser" for a database
system and that user, for one thing, owns all the unix files that hold
all the data for that database system.  It is usually a good idea to create
a user for the sole purpose of being a postgres superuser.

WARNING: PostgreSQL is not secure.  Anyone who can connect to a database
system can easily assume all the unix privileges of its Postgres
superuser.  The simplest way is by creating and running a C language
function.  There are plans to remedy this in future developent.

The program initdb (part of Postgres) is what initializes (creates) a
database system.  Initdb uses the defaults specified in Makefile.global
or Makefile.custom. See the man page for initdb for more information.

  % initdb --pgdata=/usr/local/pgsql/data --pglib=/usr/local/pgsql/lib

By default, the user issuing the initdb command becomes the Postgres
superuser, and only the unix superuser can specify any other user as the
Postgres superuser.

Setting up Permissions
----------------------

The first thing you should do after creating a database system is set up
the permissions for connecting to the database.  These are kept in the 
file pg_hba.conf in the lib directory.  Initdb creates a sample version of
this file, which contains comments telling you how to set it up.

The Postmaster Daemon
---------------------

Finally, in order to use the database system, you'll need to have a
postmaster daemon running.  There is one postmaster process per database
system.  The postmaster runs the program "postgres" and must run as the
Postgres superuser.  See the postgres man page.

So, for example, you can login as the Postgres superuser and issue the
command:

  $ nohup postmaster -D/usr/local/pgsql/data >server.log 2>&1 &

This says to run the postmaster against the database system created
above.

This is a good daemon to start via system startup scripts, using su (be
careful NOT to run the postmaster as the unix superuser by mistake).


TESTING POSTGRESQL
------------------
d229 236
a464 4
We suggest you run the regression tests to make sure the release was
installed successfully and works as designed in your environment.  The
regression tests can be found in src/test/regress. (see
src/test/regress/README for more details)
d466 2
a467 2
     % cd /usr/src/pgsql/src/test/regress
     % gmake all runtest
a468 2
This will run a whole slew of regression tests and might take an hour
to run.  
d499 1
a499 1
sees the semicolon).
d505 1
a505 1
(\ commands aren't SQL, so no semicolon.  Use \? to see all the \ commands).
d517 2
d520 2
a521 2
QUESTIONS? BUGS? FEEDBACK?
--------------------------
d523 7
a529 2
First, please read the Frequently Asked Questions and answers in the file
called FAQ.
a530 2
If you still have questions, please send them to:
questions@@postgreSQL.org
a531 44
If you have a bug report to make, please send a filled out version of
the file named "bug.template" to bugs@@postgreSQL.org.

If you would like to help out with the development and maintenance of
PostgreSQL, send subscribe to the developers mailing list.  See
README.support for more information

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

Porting Notes:
-------------
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.
@


1.19
log
@Document --enable-cassert/--disable-cassert configure options
@
text
@d235 1
a235 6
to run.  When it's done, the output is in the file obj/regress.out.  You
can compare this to a sample run that we supply in the file
sample.regress.out. (You should get roughly the same output except for
some pathnames.)

     % diff expected.out regress.out
@


1.18
log
@Major cleanup of Install instructions

Provided by: adrian@@waltham.harvard.net
@
text
@d118 4
@


1.17
log
@Move nextstep into problem/bug section.
@
text
@d5 1
a5 1
(version 6.0) PostgreSQL is a derivative of POSTGRES 4.2 (the last
d29 1
a29 1
   sunos4          SUN SPARC on SunOS 4.1.3
d48 1
a48 1
1.09 and reload them under 6.0.  The pg_dump utility is designed to do
d50 1
a50 1
have the proper copy format to load into the 6.0 database.
d88 1
a88 40
   Customization can be done by editing src/Makefile.global. You may change
   the various configuration options here, such as where the PostgreSQL
   executable files are installed and where postgres looks for the database
   directory.  

   PostgreSQL V6.0 also supports src/Makefile.custom. This is not supplied
   with the distribution, but may be created to contain only the options 
   you wish to change in src/Makefile.global. This has the advantage that
   it will not be overwritten when you install a new version of PostgreSQL
   over the top of your current installation.

   The configuration switches are fairly self-explanatory, but we
   will go over some of the more commonly-changed options:

     - PORTNAME specifies the platform on which PostgreSQL is being built.
       This is set to UNDEFINED. You will need to change it to reflect
       your platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris
       2.4, ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0, etc.)

     - SRCDIR specifies where the source files are located. (defaults to
       $(POSTGRESDIR)/src.)

     - POSTGRESDIR specifies the top-level directory where PostgreSQL
       binaries, header files, libraries, and databases are installed.

     - USE_READLINE specifies whether you want to use the GNU readline and
       history libraries for the psql interactive frontend program.  GNU
       readline is not supplied with PostgreSQL and can be found in the
       usual ftp sites for GNU software.

   In the simplest case, you would create src/Makefile.custom containing
   just the line:

       PORTNAME= portname

   (where you replace portname with the name of the system you are using).

   Even easier is to enter the src directory and run the customize shell
   script which will prompt you with various questions and create
   Makefile.custom for you:
d91 1
a91 1
     % customize
d93 49
a141 5
   After editing src/Makefile.global or src/Makefile.custom, you are ready 
   to compile PostgreSQL (it takes about 10 minutes on a 133Mhz Pentium 
   running linux):

     % cd src                              ( if you're not already there )
a338 2


@


1.16
log
@flex 2.5.3 warning from Andrew Martin.
@
text
@a27 1
   nextstep       Motorola MC68K or Intel x86 on NeXTSTEP 3.2
d32 4
@


1.15
log
@Change 'next' to 'nextstep' as port name

Pointed out by Andrew Martin
@
text
@d57 4
@


1.14
log
@Point bug reports at bugs@@postgresql.org
@
text
@d28 1
a28 1
   next           Motorola MC68K or Intel x86 on NeXTSTEP 3.2
@


1.13
log
@point the installer at src/test/regress for testing

pointed out by Andrew...
@
text
@d284 1
a284 1
the file named "bug.template" to hackers@@postgreSQL.org.
@


1.12
log
@Various updates to install, including redirecting installers to
Makefile.custom and pointers at the customize script...
@
text
@d215 1
a215 1
     % cd /usr/src/pgsql/test/regress
@


1.11
log
@INSTALL fix for pg_hba.conf
@
text
@d84 9
a92 1
   directory.  The configuration switches are fairly self-explanatory, but we
d111 4
a114 3
     - HBA specifies whether you wish to use host-based authentication
       for PostgreSQL.  See the section "How to Create a Database System"
       for how to set up the HBA permissions if you decide to use HBA.
d116 5
a120 2
   After editing src/Makefile.global, you are ready to compile PostgreSQL
   (it takes about 10 minutes on a 133Mhz Pentium running linux):
d123 7
d170 2
a171 2
database system.  Initdb uses the defaults specified in Makefile.global.
See the man page for initdb for more information.
@


1.10
log
@documentation updating to 6.0 release
@
text
@d165 1
a165 1
file pg_hba in the data directory.  Initdb creates a sample version of
@


1.9
log
@Cleanup initdb for 1.*.
@
text
@d5 1
a5 1
(version 1.09) PostgreSQL is a derivative of POSTGRES 4.2 (the last
d18 15
a32 17
	alpha		-	DEC Alpha AXP on OSF/1 2.0
	hpux		-	HP PA-RISC on HP-UX 9.0
	i386_solaris	-	i386 Solaris
	sparc_solaris	-	SUN SPARC on Solaris 2.4
	sparc		-	SUN SPARC on SunOS 4.1.3
	ultrix4		-	DEC MIPS on Ultrix 4.4
	linux		-	Intel x86 on Linux 1.2 (or above) ELF or a.out
	BSD44_derived	-	OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
        bsdi            -       BSD/OS 2.0 and 2.01
        bsdi_2_1        -       BSD/OS 2.1
	aix		-	IBM on AIX 3.2.5
	irix5		-	SGI MIPS on IRIX 5.3 
	dgux            -       DG/UX 5.4R3.10
  Some hooks are provided for
	svr4		-	Intel x86 on Intel SVR4
	next		-	Motorola MC68K or Intel x86 on NeXTSTEP 3.2
  but these are guaranteed not to work as of yet.
d41 1
a41 1
MIGRATING FROM POSTGRES VERSION 1.0
d44 4
a47 9
Version 1.01 and 1.02 (and above) are mostly backward compatible with Version
1.0, but the database format is incompatible, so if you have databases that
you use with Version 1, you need to convert them before you can use them with
Version 1.02.  Once you do that, you won't be able to use them with Version 1
anymore.

For details on how to do this conversion, see the files doc/MIGRATION_1.0_to_1.01
and MIGRATION_to_1.02.1

d60 1
a60 1
   "/usr/src/postgres95" in this discussion.  This should be a new directory.
d64 1
a64 1
   cd /usr/src/postgres95
a97 6
     - NAMEDATALEN and OIDNAMELEN allows you to set the maximum length of
       system identifiers (table names, function names, etc.)  It
       defaults to 32.  You may alter this if you like, but be aware that
       databases created with different NAMEDATALEN's do not
       interoperate.

d113 1
a113 1
   The gmake ultimately issues the message "All of Postgres95 is
d154 1
a154 1
  % initdb
d179 1
a179 1
  % postmaster -S -D/usr/lib/postgres/postgres_data -p5432
d181 2
a182 4
This says to run the postmaster against the database system created above,
to accept connections from users on the conventional TCP port 5432, and
(-S) to run in the background without issuing messages about normal 
execution.
d196 1
a196 1
     % cd /usr/src/postgres95/src/test/regress
d199 1
a199 1
This will run a whole slew of regression tests and might take a long time
d205 1
a205 5
     % diff obj/regress.out sample.regress.out

The regression test takes about half an hour to run on a Sparc 10.  You
may want to use 'grep -v' to remove unsignificant differences.

d215 1
a215 1
  % psql -p 5432 template1
a220 3
Note that we have told psql to connect to Port 5432, which is what we told
the postmaster to listen on when we started it above.

d261 2
a262 2
If you still have questions, please send them to
postgres95@@postgres95.vnet.net.
d265 1
a265 1
the file named "bug.template" to pg95-dev@@ki.net.
@


1.8
log
@Update initdb instructions for a 1.* database.
@
text
@d164 2
a165 1
database system.  See the man page for initdb.
a166 1
Example for postgres version 1.*:
a167 7

Example for postgres version 2.0:(to be released in several months)
  % initdb -d /usr/lib/postgres_data -u postgres

  This example creates the files for the database system in the directory
  /usr/lib/postgres_data and makes user "postgres" the Postgres superuser
  for the new database system.
@


1.7
log
@Bring in minor changes from Andrew
@
text
@d166 2
a167 1
Example:
d169 2
a170 1
  % initdb --pgdata=/usr/lib/postgres_data --username=postgres
d172 3
a174 3
This example creates the files for the database system in the directory
/usr/lib/postgres_data and makes user "postgres" the Postgres superuser
for the new database system.
@


1.6
log
@Fix up INSTALL file

From Andrew
@
text
@d46 5
a50 4
Version 1.02 is mostly backward compatible with Version 1.0, but the database
format is incompatible, so if you have databases that you use with Version
1, you need to convert them before you can use them with Version 1.02.  Once
you do that, you won't be able to use them with Version 1 anymore.
d52 2
a53 1
For details on how to do this conversion, see the file MIGRATION_V1_TO_V2.
d77 1
a77 2
   before installing PostgreSQL. For Linux and Irix, read the machine-
   specific FAQs.
d94 2
a95 2
     - PORTNAME specifies the platform on which PostgreSQL is being build
       (BSD44_derived is the default). You might need to change it to reflect
d97 1
a97 1
       2.4, ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0)
@


1.5
log
@Slight changes to INSTALL to point ppl at the Linux/IRIX specific
FAQs
@
text
@d1 1
a1 1
POSTGRES95 INSTALLATION INSTRUCTIONS
d4 2
a5 2
This directory contains the source and documentation for Postgres95
(version 2) Postgres95 is a derivative of POSTGRES 4.2 (the last
d7 1
a7 1
postgres95, please see the file named COPYRIGHT.  This version was
d13 1
a13 1
REQUIREMENTS TO RUN POSTGRES95
d16 1
a16 1
Postgres95 has been tested on the following platforms:
d36 1
a36 1
Postgres95 is also known to work on a number of other platforms that the
d43 2
a44 2
MIGRATING FROM POSTGRES VERSION 1
---------------------------------
d46 1
a46 1
Version 2 is mostly backward compatible with Version 1, but the database
d48 1
a48 1
1, you need to convert them before you can use them with Version 2.  Once
d54 1
a54 1
INSTALLING POSTGRES95
d57 1
a57 1
Installing Postgres95 encompasses only installing the software on your system
d62 1
a62 1
To install Postgres95 on UNIX platforms:
d71 1
a71 1
3. Build Postgres95:
d73 1
a73 1
   If you're installing Postgres95 on Ultrix 4.x or Linux, see the 
d75 2
a76 1
   before installing Postgres95.
d88 1
a88 1
   the various configuration options here, such as where the Postgres95
d93 1
a93 1
     - PORTNAME specifies the platform on which Postgres95 is being build
d101 1
a101 1
     - POSTGRESDIR specifies the top-level directory where Postgres95
d112 1
a112 1
       readline is not supplied with postgres95 and can be found in the
d116 1
a116 1
       for postgres95.  See the section "How to Create a Database System"
d119 1
a119 1
   After editing src/Makefile.global, you are ready to compile Postgres95
d129 1
a129 1
4. Install Postgres95
d141 1
a141 1
   correct it before Postgres95 will work.
d157 1
a157 1
WARNING: Postgres95 is not secure.  Anyone who can connect to a database
d207 1
a207 1
TESTING POSTGRES95
d230 1
a230 1
PLAYING WITH POSTGRES95
d233 1
a233 1
After Postgres95 is installed, a database system is created, a postmaster
d235 2
a236 2
see Postgres95 do something.  That's easy.  Invoke the interactive interface
to Postgres95, psql, and start typing SQL:
d294 1
a294 1
postgres95, send subscribe to the developers mailing list.  See
d321 1
d332 1
a332 1
        binary releases of postgres95 for NEXTSTEP will be made available to
@


1.4
log
@This patch corrects some errors in sample commands in the INSTALL file.

Submitted by:  bryanh@@giraffe.netgate.net (Bryan Henderson)
@
text
@d24 1
a24 1
	linux		-	Intel x86 on Linux 1.2 and Linux ELF
d29 1
a29 1
	irix5		-	SGI MIPS on IRIX 5.3
d76 2
@


1.3
log
@Changed default port name.
@
text
@d193 1
a193 1
  % postgres -S -D/usr/lib/postgres/postgres_data -p5432
d235 1
a235 1
  % psql -d/usr/lib/postgres_data template1
d240 3
@


1.2
log
@Finish commiting Bryan's patches...
@
text
@d91 1
a91 1
       (linux is the default). You might need to change it to reflect
@


1.1
log
@Initial revision
@
text
@a0 1

d5 10
a14 5
(version 1.02)  Postgres95 is a derivative of POSTGRES 4.2 (the last
release of the UC Berkeley research project).   For copyright terms
for postgres95, please see the file named COPYRIGHT.   This version 
was developed by a team of developers on the postgres developers
mailing list.  Version 1.01 was developed by Jolly Chen and Andrew Yu.
d36 2
a37 2
Postgres95 is also known to work on a number of other platforms that
the authors have not personally tested.
a41 3
If you would like to migrate your databases from postgres 1.0 to
postgres 1.02, see the directory called MIGRATION_1.0_TO_1.02.  People
upgrading from version 1.01 do not have to make any database changes.
d43 19
a61 1
----------------------------------------------------------------------
d64 4
a67 10
1. Create the postgres login.
   
   Create a login called postgres (this requires root privileges). We 
   recommend that you run the postmaster as the user postgres for security 
   reasons.

   If you run the postmaster as yourself, be warned that you essentially
   grant all database users the ability to execute arbitrary C functions
   as you without your password. (In any case, DO NOT run the postmaster 
   as root.)
d69 1
a69 1
2. Compile and install Postgres95.
d71 1
a71 2
   If you have earlier versions of Postgres installed, you might want
   to install Postgres95 in a different place.
d90 28
a117 35
     -  PORTNAME specifies the platform on which Postgres95 is being build
        (linux is the default). You might need to change it to reflect your 
        platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris 2.4, 
        ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0)

     -  SRCDIR specifies where the source files are located. (defaults
        to $(POSTGRESDIR)/src.)

     -  POSTSGRESDIR specifies the top-level directory where Postgres95
        binaries, header files, libraries, and databases are installed.

     -  POSTGRESLOGIN specifies the user who will be doing initdb and
        running the postmaster (defaults to postgres).  Do not set
	this to root, or any users with UID = 0!

     -  NAMEDATALEN and OIDNAMELEN allows you to set the maximum
        length of system identifiers (table names, function names, etc.)
        It defaults to 32.  You may alter this if you like, but
        be aware that databases created with different NAMEDATALEN's
        do not interoperate. 

     -  USE_READLINE specifies whether you want to use the GNU
        readline and history libraries for the psql interactive 
        frontend program.
        GNU readline is not supplied with postgres95 and can be found
        in the usual ftp sites for GNU software.

      - HBA specifies whether you wish to use host-based
        authentication for postgres95.  If you do use host-based
        authentication, after installing, modify the file
        $PGDATA/pg_hba accordingly. 

   After editing src/Makefile.global, you are ready to compile and
   install Postgres95 (it takes about 10 minutes on a 133Mhz Pentium
   running linux):
a120 1
     % gmake install
d122 1
a122 1
   The first gmake ultimately issues the message "All of Postgres95 is 
d126 27
a152 2
   After the installation is complete, check that you have the following files
   in the top level Postgres95 directory (eg. /usr/local/postgres95).
d154 4
a157 2
   You will find the following executables in the bin directory (which
   should be included in the search path of your shell):
d159 2
a160 4
     % ls /usr/local/postgres95/bin
     cleardbdir*   destroydb*    pg_dump*      postgres*
     createdb*     destroyuser*  pg_id*        postmaster@@
     createuser*   initdb*       pg_version*   psql*
d162 1
a162 1
   You will find the following in the database directory:
d164 1
a164 7
     % ls -R /usr/local/postgres95/data
     files/
     pg_hba
	
     data/files:
     global1.bki                   local1_template1.bki
     global1.bki.source            local1_template1.bki.source
d166 3
a168 1
3. Initialize the database.
d170 3
a172 1
   After you have installed Postgres95, initialize the database by typing:
d174 2
a175 1
     % initdb
d177 4
a180 1
4. Start the postmaster.
d182 2
a183 7
   Now, you are ready to make the system operational by running the
   postmaster daemon. There are a few environment variables which affect
   its operation:
	PGDATA	- location of the database (eg. /usr/local/postgres95/data)
	PGPORT	- TCP port where it listens for connection (eg. 5432)
   You don't have to set these variables if you use the (compile time) 
   default.
d185 4
a188 1
     % postmaster -S
d190 2
a191 2
   
5. Testing.
d193 1
a193 3
   We suggest you run the regression tests to make sure the release
   was installed successfully. The regression tests can be found in
   src/test/regress. (see src/test/regress/README for more details)
d195 18
a212 1
     % cd /usr/local/postgres95/src/test/regress
d215 5
a219 5
   This will run a whole slew of regression tests and might take a long
   time to run.  When it's done, the output is in the file obj/regress.out.
   You can compare this to a sample run that we supply in the file 
   sample.regress.out. (You should get roughly the same output except
   for some pathnames.) 
d223 2
a224 2
   The regression test takes about half an hour to run on a Sparc 10.
   You may want to use 'grep -v' to remove unsignificant differences.
a225 1
6. Run queries.
d227 2
a228 2
   After the database is initialized, you can create a new database. To
   create a database, do the following:
d230 12
a241 8
     % createdb foo

   To connect to the postmaster, you have a choice of two front-end programs.
   ("psql" is recommended.  "monitor" is the old terminal monitor
     supplied in earlier versions of Postgres)
   
     % psql foo
Please read the file COPYRIGHT for copyright terms of POSTGRES95
d246 27
a272 1
You are currently connected to the database: foo
a273 1
foo=> 
d275 2
a276 2
----------------------------------------------------------------------
Questions? Bugs? Feedback?
d278 2
a279 2
First, please read the Frequently Asked Questions and answers
in the file called FAQ.
d282 1
a282 1
postgres95@@postgres95.vnet.net.   
@


1.1.1.1
log
@Support Docs & Contrib
@
text
@@
