mirror/postgresql
2
0
Fork 0
mirror of https://git.postgresql.org/git/postgresql.git synced 2024-12-09 08:10:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
475cb157b9
postgresql/INSTALL
Thomas G. Lockhart 7db607f354 Installation guide for 7.0 release. From SGML sources.
2000-05-04 16:12:05 +00:00

1646 lines
73 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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.
Reference in New Issue View Git Blame Copy Permalink