
                    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
         

       

Before you start


       Building PostgreSQL requires GNU make. It will not work with 
      other make programs. On GNU/Linux systems GNU make is the 
      default tool, on other systems you may find that GNU make is 
      installed under the name gmake. We will use that name from now 
      on to indicate GNU make, no matter what name it has on your 
      system. To test for GNU make enter 

      > gmake --version
          

       If you need to get GNU make, you can find it at 
      ftp://ftp.gnu.org. 
       Up to date information on supported platforms is at 
      http://www.postgresql.org/docs/admin/ports.htm 
      (http://www.postgresql.org/docs/admin/ports.htm). In general, 
      most Unix-compatible platforms with modern libraries should be 
      able to run PostgreSQL. In the doc subdirectory of the 
      distribution are several platform-specific FAQ and README 
      documents you might wish to consult if you are having trouble. 
       Although the minimum required memory for running PostgreSQL 
      can be as little as 8MB, there are noticeable speed 
      improvements when expanding memory up to 96MB or beyond. The 
      rule is you can never have too much memory. 
       Check that you have sufficient disk space. You will need about 
      30 Mbytes for the source tree during compilation and about 5 
      Mbytes for the installation directory. An empty database takes 
      about 1 Mbyte, otherwise they take about five times the amount 
      of space that a flat text file with the same data would take. 
      If you run the regression tests you will temporarily need an 
      extra 20MB. 
       To check for disk space, use 

      > df -k

       
       Considering today's prices for hard disks, getting a large and 
      fast hard disk should probably be in your plans before putting 
      a database into production use. 

Installation Procedure


      PostgreSQL Installation
       For a fresh install or upgrading from previous releases of 
      PostgreSQL: 
      1.  Create the PostgreSQL superuser account. This is the user 
         the server will run as. For production use you should create 
         a separate, unprivileged account (postgres is commonly 
         used). If you do not have root access or just want to play 
         around, your own user account is enough. 
          Running PostgreSQL as root, bin, or any other account with 
         special access rights is a security risk; don't do it. The 
         postmaster will in fact refuse to start as root. 
          You need not do the building and installation itself under 
         this account (although you can). You will be told when you 
         need to login as the database superuser. 
      2.  Configure the source code for your system. It is this step 
         at which you can specify your actual installation path for 
         the build process and make choices about what gets 
         installed. Change into the src subdirectory and type: 
         > ./configure
               
          followed by any options you might want to give it. For a 
         first installation you should be able to do fine without 
         any. For a complete list of options, type: 
         > ./configure --help
               
          Some of the more commonly used ones are: 

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

         --enable-locale
            If you want to use locales. 

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

         --with-perl
            Builds the Perl interface and plperl extension language. 
           Please note that the Perl interface needs to be installed 
           into the usual place for Perl modules (typically under 
           /usr/lib/perl), so you must have root access to perform 
           the installation step. (It is often easiest to leave out 
           --with-perl initially, and then build and install the Perl 
           interface after completing the installation of PostgreSQL 
           itself.) 

         --with-odbc
            Builds the ODBC driver package. 

         --with-tcl
            Builds interface libraries and programs requiring Tcl/Tk, 
           including libpgtcl, pgtclsh, and pgtksh. 
          
      3.  Compile the program. Type 
         > gmake
               
          The compilation process can take anywhere from 10 minutes 
         to an hour. Your mileage will most certainly vary. Remember 
         to use GNU make. 
          The last line displayed will hopefully be 
         All of PostgreSQL is successfully made. Ready to install.
               
          
      4.  If you want to test the newly built server before you 
         install it, you can run the regression tests at this point. 
         The regression tests are a test suite to verify that 
         PostgreSQL runs on your machine in the way the developers 
         expected it to. For detailed instructions see Regression 
         Test. (Be sure to use the "parallel regress test" method, 
         since the sequential method only works with an 
         already-installed server.) 
      5.  If you are not upgrading an existing system 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. 
