+ Installation instructions for PostgreSQL 7.0.
+
+If you haven't gotten the PostgreSQL distribution, get it from
+ftp.postgresql.org, then unpack it:
+
+> gunzip postgresql-7.0.tar.gz
+> tar -xf postgresql-7.0.tar
+> mv postgresql-7.0 /usr/src
- PostgreSQL Installation Guide
- The PostgreSQL Development Team
-
- Edited by
- Thomas Lockhart\f
-
-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. \f
-
-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. \f
-
-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
- BSDI x86 v7.0 2000-04-04 Bruce Momjian
- Compaq Alpha v7.0 2000-04-11 Andrew McMurry
- FreeBSD x86 v7.0 2000-04-04 Marc Fournier
- HPUX PA-RISC v7.0 2000-04-12 Both 9.0x and 10.20. Tom Lane
- IRIX MIPS v6.5.3 2000-02-18 MIPSPro 7.3.1.1m N32 build. Kevin
- Linux Alpha v7.0 2000-04-05 With published patches.
- 2.0.x Ryan Kirkpatrick
- Linux armv4l v7.0 2000-04-17 Regression test needs work.
- 2.2.x Mark Knox
- Linux x86 v7.0 2000-03-26 Lamar Owens
- Linux MIPS v7.0 2000-04-13 Cobalt Qube. Tatsuo Ishii
- Linux Sparc v7.0 2000-04-02 Tom Szybist
- Linux PPC603e v7.0 2000-04-13 Tatsuo Ishii
- mklinux PPC750 v7.0 2000-04-13 Tatsuo Ishii
- NetBSD arm32 v7.0 2000-04-08 Patrick Welche
- NetBSD x86 v7.0 2000-03-26 Patrick Welche
- NetBSD m68k v7.0 2000-04-10 Mac 8xx. Henry B. Hotz
- NetBSD- Sparc v7.0 2000-04-13 Tom I Helbekkmo
- QNX x86 v7.0 2000-04-01 Dr. Andreas Kardos
- SCO Open x86 v6.5 1999-05-25 Andrew Merrill
- SCO UW7 x86 v7.0 2000-04-18 See FAQ. Billy G. Allie
- Solaris x86 v7.0 2000-04-12 Marc Fournier
- Solaris Sparc v7.0 2000-04-12 Peter Eisentraut
- SunOS Sparc v7.0 2000-04-13 Tatsuo Ishii
- Windows x86 v7.0 2000-04-02 No server-side. Magnus Hagander
- WinNT x86 v7.0 2000-03-30 Uses Cygwin library. Daniel Horak
-
-
-
-
- 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
- DGUX m88k v6.3 1998-03-01 v6.4 probably OK. Needs new
- 5.4R4.11 maintainer. Brian E Gallew
- NetBSD NS32532 v6.4 1998-10-27 Date/time math annoyances.
- NetBSD VAX v6.3 1998-03-01 v7.0 should work. Tom I Helbekkmo
- SVR4 4.4 m88k v6.2.1 1998-03-01 v6.4.x will need TAS spinlock
- code. Doug Winterburn
- SVR4 MIPS v6.4 1998-10-28 No 64-bit int. Frank Ridderbusch
- 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
-
-
- \f
-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. 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.
- 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 \
+ >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.
+
+ * Life will be more convenient if you set up some environment variables.
+ First of all you probably want to include /usr/local/pgsql/bin (or
+ equivalent) into your PATH. To do this, add the following to your shell
+ startup file, such as ~/.bash_profile (or /etc/profile, if you want it
+ to affect every user):
+
+ > PATH=$PATH:/usr/local/pgsql/bin
+
+
+ Furthermore, if you set PGDATA in the environment of the PostgreSQL
+ superuser, you can omit the -D for postmaster and initdb.
+
+ * You probably want to install the man and HTML documentation. Type
+
+ > cd /usr/src/pgsql/postgresql-7.0/doc
+ > gmake install
+
+
+ This will install files under /usr/local/pgsql/doc and
+ /usr/local/pgsql/man. To enable your system to find the man
+ documentation, you need to add a line like the following to a shell
+ startup file:
+
+ > MANPATH=$MANPATH:/usr/local/pgsql/man
+
+
+ The documentation is also available in Postscript format. If you have a
+ Postscript printer, or have your machine already set up to accept
+ Postscript files using a print filter, then to print the User's Guide
+ simply type
+
+ > cd /usr/local/pgsql/doc
+ > gunzip -c user.ps.tz | lpr
+
+
+ Here is how you might do it if you have Ghostscript on your system and
+ are writing to a laserjet printer.
+
+ > gunzip -c user.ps.gz \
+ | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
+ | lpr
+
+
+ Printer setups can vary wildly from system to system. If in doubt,
+ consult your manuals or your local expert.
+
+ The Adminstrator's Guide should probably be your first reading if you
+ are completely new to PostgreSQL, as it contains information about how
+ to set up database users and authentication.
+
+ * Usually, you will want to modify your computer so that it will
+ automatically start the database server whenever it boots. This is not
+ required; the PostgreSQL server can be run successfully from
+ non-privileged accounts without root intervention.
+
+ Different systems have different conventions for starting up daemons at
+ boot time, so you are advised to familiarize yourself with them. Most
+ systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost
+ certainly no bad place to put such a command. Whatever you do,
+ postmaster must be run by the PostgreSQL superuser (postgres) and not
+ by root or any other user. Therefore you probably always want to form
+ your command lines along the lines of su -c '...' postgres.
+
+ It might be advisable to keep a log of the server output. To start the
+ server that way try:
+
+ > nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
+
+
+ Here are a few more operating system specific suggestions.
+
+ o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
+ to contain the following single line:
+
+ > su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
+
+
+ o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
+ contain the following lines and make it chmod 755 and chown
+ root:bin.
+
+ #!/bin/sh
+ [ -x /usr/local/pgsql/bin/postmaster ] && {
+ su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
+ -D/usr/local/pgsql/data
+ -S -o -F > /usr/local/pgsql/errlog' &
+ echo -n ' pgsql'
+ }
+
+
+ You may put the line breaks as shown above. The shell is smart
+ enough to keep parsing beyond end-of-line if there is an
+ expression unfinished. The exec saves one layer of shell under the
+ postmaster process so the parent is init.
+
+ o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
+ based on the example in contrib/linux/. Then make a softlink to
+ this file from /etc/rc.d/rc5.d/S98postgres.init.
+
+ * Run the regression tests against the installed server (using the
+ sequential test method). If you didn't run the tests before
+ installation, you should definitely do it now. For detailed
+ instructions see Regression Test.
+
+To start experimenting with Postgres, set up the paths as explained above
+and start the server. To create a database, type
+
+> createdb testdb
+
+
+Then enter
+
+> psql testdb
+
- 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 \
- >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. \f
-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
- Note that FAQLs (Frequently-Asked Questions Lists) are
- periodically posted to the Kerberos mailing list
- 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
- ORG
-
-
-
- Support for Version 4 will disappear sometime after the
- production release of Version 5 by MIT. \f
-
-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)
- 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 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 )
- 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
- 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
- Fixes for Alpha compiles
- New multibyte encodings \f
-
-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.
+to connect to that database. At the prompt you can enter SQL commands and
+start experimenting.
projects / postgresql.git / commitdiff