mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-12-09 08:10:09 +08:00
1646 lines
73 KiB
Plaintext
1646 lines
73 KiB
Plaintext
|
||
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.
|