diff --git a/INSTALL b/INSTALL index 456b722185..b3307f34f3 100644 --- a/INSTALL +++ b/INSTALL @@ -1,813 +1,877 @@ + PostgreSQL Installation Instructions - PostgreSQL Installation Instructions - - This document describes the installation of PostgreSQL from the source - code distribution. - _________________________________________________________________ - - Short Version - -./configure -gmake -su -gmake install -adduser postgres -mkdir /usr/local/pgsql/data -chown postgres /usr/local/pgsql/data -su - postgres -/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data -/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 & -/usr/local/pgsql/bin/createdb test -/usr/local/pgsql/bin/psql test +This document describes the installation of PostgreSQL from the source code +distribution. - The long version is the rest of this document. - _________________________________________________________________ - - Requirements - - In general, a modern Unix-compatible platform should be able to run - PostgreSQL. The platforms that had received specific testing at the - time of release are listed in the section called Supported Platforms - below. In the "doc" subdirectory of the distribution there are several - platform-specific FAQ documents you might wish to consult if you are - having trouble. - - The following software packages are required for building PostgreSQL: - - * GNU make is required; other make programs will *not* work. GNU - make is often installed under the name "gmake"; this document will - always refer to it by that name. (On some systems GNU make is the - default tool with the name "make".) To test for GNU make enter -gmake --version - It is recommended to use version 3.76.1 or later. - * You need an ISO/ANSI C compiler. Recent versions of GCC are - recommendable, but PostgreSQL is known to build with a wide - variety of compilers from different vendors. - * gzip is needed to unpack the distribution in the first place. If - you are reading this, you probably already got past that hurdle. - * The GNU Readline library (for comfortable line editing and command - history retrieval) will be used by default. If you don't want to - use it then you must specify the "--without-readline" option for - "configure". (On NetBSD, the "libedit" library is - Readline-compatible and is used if "libreadline" is not found.) - * To build on Windows NT or Windows 2000 you need the Cygwin and - cygipc packages. See the file "doc/FAQ_MSWIN" for details. - - The following packages are optional. They are not required in the - default configuration, but they are needed when certain build options - are enabled, as explained below. - - * To build the server programming language PL/Perl you need a full - Perl installation, including the "libperl" library and the header - files. Since PL/Perl will be a shared library, the "libperl" - library must be a shared library also on most platforms. This - appears to be the default in recent Perl versions, but it was not - in earlier versions, and in general it is the choice of whomever - installed Perl at your site. - If you don't have the shared library but you need one, a message - like this will appear during the build to point out this fact: -*** Cannot build PL/Perl because libperl is not a shared library. -*** You might have to rebuild your Perl installation. Refer to -*** the documentation for details. - (If you don't follow the on-screen output you will merely notice - that the PL/Perl library object, "plperl.so" or similar, will not - be installed.) If you see this, you will have to rebuild and - install Perl manually to be able to build PL/Perl. During the - configuration process for Perl, request a shared library. - * To build the PL/Python server programming language, you need a - Python installation, including the header files. Since PL/Python - will be a shared library, the "libpython" library must be a shared - library also on most platforms. This is not the case in a default - Python installation. - If after building and installing you have a file called - "plpython.so" (possibly a different extension), then everything - went well. Otherwise you should have seen a notice like this - flying by: -*** Cannot build PL/Python because libpython is not a shared library. -*** You might have to rebuild your Python installation. Refer to -*** the documentation for details. - That means you have to rebuild (part of) your Python installation - to supply this shared library. - The catch is that the Python distribution or the Python - maintainers do not provide any direct way to do this. The closest - thing we can offer you is the information in Python FAQ 3.30. On - some operating systems you don't really have to build a shared - library, but then you will have to convince the PostgreSQL build - system of this. Consult the "Makefile" in the "src/pl/plpython" - directory for details. - * If you want to build Tcl or Tk components (clients and the PL/Tcl - language) you of course need a Tcl installation. - * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. - Ant is a special tool for building Java-based packages. It can be - downloaded from the Ant web site. - If you have several Java compilers installed, it depends on the - Ant configuration which one gets used. Precompiled Ant - distributions are typically set up to read a file ".antrc" in the - current user's home directory for configuration. For example, to - use a different JDK than the default, this may work: -JAVA_HOME=/usr/local/sun-jdk1.3 -JAVACMD=$JAVA_HOME/bin/java - - Note: Do not try to build the driver by calling "ant" or even - "javac" directly. This will not work. Run "gmake" normally as - described below. - * To enable Native Language Support (NLS), that is, the ability to - display a program's messages in a language other than English, you - need an implementation of the Gettext API. Some operating systems - have this built-in (e.g., Linux, NetBSD, Solaris), for other - systems you can download an add-on package from here: - http://www.postgresql.org/~petere/gettext.html. If you are using - the Gettext implementation in the GNU C library then you will - additionally need the GNU Gettext package for some utility - programs. For any of the other implementations you will not need - it. - * Kerberos, OpenSSL, or PAM, if you want to support authentication - using these services. - - If you are building from a CVS tree instead of using a released source - package, or if you want to do development, you also need the following - packages: - - * Flex and Bison are needed to build a CVS checkout or if you - changed the actual scanner and parser definition files. If you - need them, be sure to get Flex 2.5.4 or later and Bison 1.875 or - later. Other yacc programs can sometimes be used, but doing so - requires extra effort and is not recommended. Other lex programs - will definitely not work. - - If you need to get a GNU package, you can find it at your local GNU - mirror site (see http://www.gnu.org/order/ftp.html for a list) or at - ftp://ftp.gnu.org/gnu/. - - Also check that you have sufficient disk space. You will need about 65 - MB for the source tree during compilation and about 15 MB for the - installation directory. An empty database cluster takes about 25 MB, - databases take about five times the amount of space that a flat text - file with the same data would take. If you are going to run the - regression tests you will temporarily need up to an extra 90 MB. Use - the "df" command to check for disk space. - _________________________________________________________________ - - If You Are Upgrading - - The internal data storage format changes with new releases of - PostgreSQL. Therefore, if you are upgrading an existing installation - that does not have a version number "7.4.x", you must back up and - restore your data as shown here. These instructions assume that your - existing installation is under the "/usr/local/pgsql" directory, and - that the data area is in "/usr/local/pgsql/data". Substitute your - paths appropriately. - 1. Make sure that your database is not updated during or after the - backup. This does not affect the integrity of the backup, but the - changed data would of course not be included. If necessary, edit - the permissions in the file "/usr/local/pgsql/data/pg_hba.conf" - (or equivalent) to disallow access from everyone except you. - 2. To back up your database installation, type: -pg_dumpall > outputfile - If you need to preserve OIDs (such as when using them as foreign - keys), then use the "-o" option when running "pg_dumpall". - "pg_dumpall" does not save large objects. Check the documentation - if you need to do this. - To make the backup, you can use the "pg_dumpall" command from the - version you are currently running. For best results, however, try - to use the "pg_dumpall" command from PostgreSQL 7.4beta5, since - this version contains bug fixes and improvements over older - versions. While this advice might seem idiosyncratic since you - haven't installed the new version yet, it is advisable to follow - it if you plan to install the new version in parallel with the old - version. In that case you can complete the installation normally - and transfer the data later. This will also decrease the downtime. - 3. If you are installing the new version at the same location as the - old one then shut down the old server, at the latest before you - install the new files: -kill -INT `cat /usr/local/pgsql/data/postmaster.pid` - Versions prior to 7.0 do not have this "postmaster.pid" file. If - you are using such a version you must find out the process ID of - the server yourself, for example by typing "ps ax | grep - postmaster", and supply it to the "kill" command. - On systems that have PostgreSQL started at boot time, there is - probably a start-up file that will accomplish the same thing. For - example, on a Red Hat Linux system one might find that -/etc/rc.d/init.d/postgresql stop - works. Another possibility is "pg_ctl stop". - 4. If you are installing in the same place as the old version then it - is also a good idea to move the old installation out of the way, - in case you have trouble and need to revert to it. Use a command - like this: -mv /usr/local/pgsql /usr/local/pgsql.old - - After you have installed PostgreSQL 7.4beta5, create a new database - directory and start the new server. Remember that you must execute - these commands while logged in to the special database user account - (which you already have if you are upgrading). -/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data -/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data +------------------------------------------------------------------------------- - Finally, restore your data with -/usr/local/pgsql/bin/psql -d template1 -f outputfile +Short Version + + ./configure + gmake + su + gmake install + adduser postgres + mkdir /usr/local/pgsql/data + chown postgres /usr/local/pgsql/data + su - postgres + /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data + /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 & + /usr/local/pgsql/bin/createdb test + /usr/local/pgsql/bin/psql test + +The long version is the rest of this document. + +------------------------------------------------------------------------------- + +Requirements + +In general, a modern Unix-compatible platform should be able to run PostgreSQL. +The platforms that had received specific testing at the time of release are +listed in the Section called Supported Platforms below. In the "doc" +subdirectory of the distribution there are several platform-specific FAQ +documents you might wish to consult if you are having trouble. The following +software packages are required for building PostgreSQL: + + * GNU make is required; other make programs will *not* work. GNU make is + often installed under the name "gmake"; this document will always refer + to it by that name. (On some systems GNU make is the default tool with + the name "make".) To test for GNU make enter + + gmake --version + + It is recommended to use version 3.76.1 or later. + + * You need an ISO/ANSI C compiler. Recent versions of GCC are + recommendable, but PostgreSQL is known to build with a wide variety of + compilers from different vendors. + + * gzip is needed to unpack the distribution in the first place. If you are + reading this, you probably already got past that hurdle. + + * The GNU Readline library (for comfortable line editing and command + history retrieval) will be used by default. If you don't want to use it + then you must specify the "--without-readline" option for "configure". + (On NetBSD, the "libedit" library is Readline-compatible and is used if + "libreadline" is not found.) + + * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc + packages. See the file "doc/FAQ_MSWIN" for details. + +The following packages are optional. They are not required in the default +configuration, but they are needed when certain build options are enabled, as +explained below. + + * To build the server programming language PL/Perl you need a full Perl + installation, including the "libperl" library and the header files. Since + PL/Perl will be a shared library, the "libperl" library must be a shared + library also on most platforms. This appears to be the default in recent + Perl versions, but it was not in earlier versions, and in general it is + the choice of whomever installed Perl at your site. + If you don't have the shared library but you need one, a message like + this will appear during the build to point out this fact: + + *** Cannot build PL/Perl because libperl is not a shared library. + *** You might have to rebuild your Perl installation. Refer to + *** the documentation for details. + + (If you don't follow the on-screen output you will merely notice that the + PL/Perl library object, "plperl.so" or similar, will not be installed.) + If you see this, you will have to rebuild and install Perl manually to be + able to build PL/Perl. During the configuration process for Perl, request + a shared library. + + * To build the PL/Python server programming language, you need a Python + installation, including the header files. Since PL/Python will be a + shared library, the "libpython" library must be a shared library also on + most platforms. This is not the case in a default Python installation. + If after building and installing you have a file called "plpython.so" + (possibly a different extension), then everything went well. Otherwise + you should have seen a notice like this flying by: + + *** Cannot build PL/Python because libpython is not a shared library. + *** You might have to rebuild your Python installation. Refer to + *** the documentation for details. + + That means you have to rebuild (part of) your Python installation to + supply this shared library. + The catch is that the Python distribution or the Python maintainers do + not provide any direct way to do this. The closest thing we can offer you + is the information in Python FAQ 3.30. On some operating systems you + don't really have to build a shared library, but then you will have to + convince the PostgreSQL build system of this. Consult the "Makefile" in + the "src/pl/plpython" directory for details. + + * If you want to build Tcl or Tk components (clients and the PL/Tcl + language) you of course need a Tcl installation. + + * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a + special tool for building Java-based packages. It can be downloaded from + the Ant web site. + If you have several Java compilers installed, it depends on the Ant + configuration which one gets used. Precompiled Ant distributions are + typically set up to read a file ".antrc" in the current user's home + directory for configuration. For example, to use a different JDK than the + default, this may work: + + JAVA_HOME=/usr/local/sun-jdk1.3 + JAVACMD=$JAVA_HOME/bin/java + + Note: Do not try to build the driver by calling "ant" or even + "javac" directly. This will not work. Run "gmake" normally as + described below. + + * To enable Native Language Support (NLS), that is, the ability to display + a program's messages in a language other than English, you need an + implementation of the Gettext API. Some operating systems have this + built-in (e.g., Linux, NetBSD, Solaris), for other systems you can + download an add-on package from here: http://www.postgresql.org/~petere/ + gettext.html. If you are using the Gettext implementation in the GNU C + library then you will additionally need the GNU Gettext package for some + utility programs. For any of the other implementations you will not need + it. + + * Kerberos, OpenSSL, or PAM, if you want to support authentication using + these services. + +If you are building from a CVS tree instead of using a released source package, +or if you want to do development, you also need the following packages: + + * Flex and Bison are needed to build a CVS checkout or if you changed the + actual scanner and parser definition files. If you need them, be sure to + get Flex 2.5.4 or later and Bison 1.875 or later. Other yacc programs can + sometimes be used, but doing so requires extra effort and is not + recommended. Other lex programs will definitely not work. + +If you need to get a GNU package, you can find it at your local GNU mirror site +(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/ +gnu/. +Also check that you have sufficient disk space. You will need about 65 MB for +the source tree during compilation and about 15 MB for the installation +directory. An empty database cluster takes about 25 MB, databases take about +five times the amount of space that a flat text file with the same data would +take. If you are going to run the regression tests you will temporarily need up +to an extra 90 MB. Use the "df" command to check for disk space. + +------------------------------------------------------------------------------- + +If You Are Upgrading + +The internal data storage format changes with new releases of PostgreSQL. +Therefore, if you are upgrading an existing installation that does not have a +version number "7.4.x", you must back up and restore your data as shown here. +These instructions assume that your existing installation is under the "/usr/ +local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data". +Substitute your paths appropriately. + + 1. Make sure that your database is not updated during or after the backup. + This does not affect the integrity of the backup, but the changed data + would of course not be included. If necessary, edit the permissions in + the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow + access from everyone except you. + + 2. To back up your database installation, type: + + pg_dumpall > outputfile + + If you need to preserve OIDs (such as when using them as foreign keys), + then use the "-o" option when running "pg_dumpall". + "pg_dumpall" does not save large objects. Check the documentation if you + need to do this. + To make the backup, you can use the "pg_dumpall" command from the version + you are currently running. For best results, however, try to use the + "pg_dumpall" command from PostgreSQL 7.4, since this version contains + bug fixes and improvements over older versions. While this advice might + seem idiosyncratic since you haven't installed the new version yet, it is + advisable to follow it if you plan to install the new version in parallel + with the old version. In that case you can complete the installation + normally and transfer the data later. This will also decrease the + downtime. + + 3. If you are installing the new version at the same location as the old one + then shut down the old server, at the latest before you install the new + files: + + kill -INT `cat /usr/local/pgsql/data/postmaster.pid` + + Versions prior to 7.0 do not have this "postmaster.pid" file. If you are + using such a version you must find out the process ID of the server + yourself, for example by typing "ps ax | grep postmaster", and supply it + to the "kill" command. + On systems that have PostgreSQL started at boot time, there is probably a + start-up file that will accomplish the same thing. For example, on a Red + Hat Linux system one might find that + + /etc/rc.d/init.d/postgresql stop + + works. Another possibility is "pg_ctl stop". + + 4. If you are installing in the same place as the old version then it is + also a good idea to move the old installation out of the way, in case you + have trouble and need to revert to it. Use a command like this: + + mv /usr/local/pgsql /usr/local/pgsql.old + +After you have installed PostgreSQL 7.4, create a new database directory and +start the new server. Remember that you must execute these commands while +logged in to the special database user account (which you already have if you +are upgrading). + + /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data + /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data + +Finally, restore your data with + + /usr/local/pgsql/bin/psql -d template1 -f outputfile + +using the *new* psql. +These topics are discussed at length in the documentation, which you are +encouraged to read in any case. + +------------------------------------------------------------------------------- + +Installation Procedure + + 1. Configuration + The first step of the installation procedure is to configure the source + tree for your system and choose the options you would like. This is done + by running the "configure" script. For a default installation simply + enter + + ./configure + + This script will run a number of tests to guess values for various system + dependent variables and detect some quirks of your operating system, and + finally will create several files in the build tree to record what it + found. (You can also run "configure" in a directory outside the source + tree if you want to keep the build directory separate.) + The default configuration will build the server and utilities, as well as + all client applications and interfaces that require only a C compiler. + All files will be installed under "/usr/local/pgsql" by default. + You can customize the build and installation process by supplying one or + more of the following command line options to "configure": - using the *new* psql. - - These topics are discussed at length in the documentation, which you - are encouraged to read in any case. - _________________________________________________________________ - - Installation Procedure - - 1. Configuration - The first step of the installation procedure is to configure the - source tree for your system and choose the options you would like. - This is done by running the "configure" script. For a default - installation simply enter -./configure - This script will run a number of tests to guess values for various - system dependent variables and detect some quirks of your - operating system, and finally will create several files in the - build tree to record what it found. (You can also run "configure" - in a directory outside the source tree if you want to keep the - build directory separate.) - The default configuration will build the server and utilities, as - well as all client applications and interfaces that require only a - C compiler. All files will be installed under "/usr/local/pgsql" - by default. - You can customize the build and installation process by supplying - one or more of the following command line options to "configure": - --prefix=PREFIX - Install all files under the directory "PREFIX" instead of - "/usr/local/pgsql". The actual files will be installed - into various subdirectories; no files will ever be - installed directly into the "PREFIX" directory. - - If you have special needs, you can also customize the - individual subdirectories with the following options. - + + Install all files under the directory "PREFIX" instead of "/usr/ + local/pgsql". The actual files will be installed into various + subdirectories; no files will ever be installed directly into the + "PREFIX" directory. + If you have special needs, you can also customize the individual + subdirectories with the following options. + --exec-prefix=EXEC-PREFIX - You can install architecture-dependent files under a - different prefix, "EXEC-PREFIX", than what "PREFIX" was - set to. This can be useful to share - architecture-independent files between hosts. If you omit - this, then "EXEC-PREFIX" is set equal to "PREFIX" and - both architecture-dependent and independent files will be - installed under the same tree, which is probably what you - want. - + + You can install architecture-dependent files under a different + prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be + useful to share architecture-independent files between hosts. If + you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both + architecture-dependent and independent files will be installed + under the same tree, which is probably what you want. + --bindir=DIRECTORY - Specifies the directory for executable programs. The - default is "EXEC-PREFIX/bin", which normally means - "/usr/local/pgsql/bin". - + + Specifies the directory for executable programs. The default is + "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin". + --datadir=DIRECTORY - Sets the directory for read-only data files used by the - installed programs. The default is "PREFIX/share". Note - that this has nothing to do with where your database - files will be placed. - + + Sets the directory for read-only data files used by the installed + programs. The default is "PREFIX/share". Note that this has nothing + to do with where your database files will be placed. + --sysconfdir=DIRECTORY - The directory for various configuration files, - "PREFIX/etc" by default. - + + The directory for various configuration files, "PREFIX/etc" by + default. + --libdir=DIRECTORY - The location to install libraries and dynamically - loadable modules. The default is "EXEC-PREFIX/lib". - + + The location to install libraries and dynamically loadable modules. + The default is "EXEC-PREFIX/lib". + --includedir=DIRECTORY - The directory for installing C and C++ header files. The - default is "PREFIX/include". - + + The directory for installing C and C++ header files. The default is + "PREFIX/include". + --docdir=DIRECTORY - Documentation files, except "man" pages, will be - installed into this directory. The default is - "PREFIX/doc". - + + Documentation files, except "man" pages, will be installed into + this directory. The default is "PREFIX/doc". + --mandir=DIRECTORY - The man pages that come with PostgreSQL will be installed - under this directory, in their respective "manx" - subdirectories. The default is "PREFIX/man". - - Note: Care has been taken to make it possible to install PostgreSQL - into shared installation locations (such as "/usr/local/include") - without interfering with the namespace of the rest of the system. - First, the string "/postgresql" is automatically appended to - datadir, sysconfdir, and docdir, unless the fully expanded - directory name already contains the string "postgres" or "pgsql". - For example, if you choose "/usr/local" as prefix, the - documentation will be installed in "/usr/local/doc/postgresql", but - if the prefix is "/opt/postgres", then it will be in - "/opt/postgres/doc". The public C header files of the client - interfaces are installed into includedir and are namespace-clean. - The internal header files and the server header files are installed - into private directories under includedir. See the documentation of - each interface for information about how to get at the its header - files. Finally, a private subdirectory will also be created, if - appropriate, under libdir for dynamically loadable modules. - + + The man pages that come with PostgreSQL will be installed under + this directory, in their respective "manx" subdirectories. The + default is "PREFIX/man". + + Note: Care has been taken to make it possible to install + PostgreSQL into shared installation locations (such as "/usr/ + local/include") without interfering with the namespace of the + rest of the system. First, the string "/postgresql" is + automatically appended to datadir, sysconfdir, and docdir, + unless the fully expanded directory name already contains the + string "postgres" or "pgsql". For example, if you choose "/usr/ + local" as prefix, the documentation will be installed in "/usr/ + local/doc/postgresql", but if the prefix is "/opt/postgres", + then it will be in "/opt/postgres/doc". The public C header + files of the client interfaces are installed into includedir + and are namespace-clean. The internal header files and the + server header files are installed into private directories + under includedir. See the documentation of each interface for + information about how to get at the its header files. Finally, + a private subdirectory will also be created, if appropriate, + under libdir for dynamically loadable modules. + --with-includes=DIRECTORIES - "DIRECTORIES" is a colon-separated list of directories - that will be added to the list the compiler searches for - header files. If you have optional packages (such as GNU - Readline) installed in a non-standard location, you have - to use this option and probably also the corresponding - "--with-libraries" option. - - Example: - --with-includes=/opt/gnu/include:/usr/sup/include. - + + "DIRECTORIES" is a colon-separated list of directories that will be + added to the list the compiler searches for header files. If you + have optional packages (such as GNU Readline) installed in a non- + standard location, you have to use this option and probably also + the corresponding "--with-libraries" option. + Example: --with-includes=/opt/gnu/include:/usr/sup/include. + --with-libraries=DIRECTORIES - "DIRECTORIES" is a colon-separated list of directories to - search for libraries. You will probably have to use this - option (and the corresponding "--with-includes" option) - if you have packages installed in non-standard locations. - - Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib. - + + "DIRECTORIES" is a colon-separated list of directories to search + for libraries. You will probably have to use this option (and the + corresponding "--with-includes" option) if you have packages + installed in non-standard locations. + Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib. + --enable-nls[=LANGUAGES] - Enables Native Language Support (NLS), that is, the - ability to display a program's messages in a language - other than English. "LANGUAGES" is a space separated list - of codes of the languages that you want supported, for - example --enable-nls='de fr'. (The intersection between - your list and the set of actually provided translations - will be computed automatically.) If you do not specify a - list, then all available translations are installed. - - To use this option, you will need an implementation of - the Gettext API; see above. - + + Enables Native Language Support (NLS), that is, the ability to + display a program's messages in a language other than English. + "LANGUAGES" is a space separated list of codes of the languages + that you want supported, for example --enable-nls='de fr'. (The + intersection between your list and the set of actually provided + translations will be computed automatically.) If you do not specify + a list, then all available translations are installed. + To use this option, you will need an implementation of the Gettext + API; see above. + --with-pgport=NUMBER - Set "NUMBER" as the default port number for server and - clients. The default is 5432. The port can always be - changed later on, but if you specify it here then both - server and clients will have the same default compiled - in, which can be very convenient. Usually the only good - reason to select a non-default value is if you intend to - run multiple PostgreSQL servers on the same machine. - + + Set "NUMBER" as the default port number for server and clients. The + default is 5432. The port can always be changed later on, but if + you specify it here then both server and clients will have the same + default compiled in, which can be very convenient. Usually the only + good reason to select a non-default value is if you intend to run + multiple PostgreSQL servers on the same machine. + --with-perl - Build the PL/Perl server-side language. - + + Build the PL/Perl server-side language. + --with-python - Build the PL/Python server-side language. - + + Build the PL/Python server-side language. + --with-tcl - Build components that require Tcl/Tk, which are libpgtcl, - pgtclsh, pgtksh, and PL/Tcl. But see below about - "--without-tk". - + + Build components that require Tcl/Tk, which are libpgtcl, pgtclsh, + pgtksh, and PL/Tcl. But see below about "--without-tk". + --without-tk - If you specify "--with-tcl" and this option, then the - program that requires Tk (pgtksh) will be excluded. - + + If you specify "--with-tcl" and this option, then the program that + requires Tk (pgtksh) will be excluded. + --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY - Tcl/Tk installs the files "tclConfig.sh" and - "tkConfig.sh", which contain configuration information - needed to build modules interfacing to Tcl or Tk. These - files are normally found automatically at their - well-known locations, but if you want to use a different - version of Tcl or Tk you can specify the directory in - which to find them. - + + Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which + contain configuration information needed to build modules + interfacing to Tcl or Tk. These files are normally found + automatically at their well-known locations, but if you want to use + a different version of Tcl or Tk you can specify the directory in + which to find them. + --with-java - Build the JDBC driver and associated Java packages. - + + Build the JDBC driver and associated Java packages. + --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY] - Build with support for Kerberos authentication. You can - use either Kerberos version 4 or 5, but not both. The - "DIRECTORY" argument specifies the root directory of the - Kerberos installation; "/usr/athena" is assumed as - default. If the relevant header files and libraries are - not under a common parent directory, then you must use - the "--with-includes" and "--with-libraries" options in - addition to this option. If, on the other hand, the - required files are in a location that is searched by - default (e.g., "/usr/lib"), then you can leave off the - argument. - - "configure" will check for the required header files and - libraries to make sure that your Kerberos installation is - sufficient before proceeding. - + + Build with support for Kerberos authentication. You can use either + Kerberos version 4 or 5, but not both. The "DIRECTORY" argument + specifies the root directory of the Kerberos installation; "/usr/ + athena" is assumed as default. If the relevant header files and + libraries are not under a common parent directory, then you must + use the "--with-includes" and "--with-libraries" options in + addition to this option. If, on the other hand, the required files + are in a location that is searched by default (e.g., "/usr/lib"), + then you can leave off the argument. + "configure" will check for the required header files and libraries + to make sure that your Kerberos installation is sufficient before + proceeding. + --with-krb-srvnam=NAME - The name of the Kerberos service principal. postgres is - the default. There's probably no reason to change this. - + + The name of the Kerberos service principal. postgres is the + default. There's probably no reason to change this. + --with-openssl[=DIRECTORY] - Build with support for SSL (encrypted) connections. This - requires the OpenSSL package to be installed. The - "DIRECTORY" argument specifies the root directory of the - OpenSSL installation; the default is "/usr/local/ssl". - - "configure" will check for the required header files and - libraries to make sure that your OpenSSL installation is - sufficient before proceeding. - + + Build with support for SSL (encrypted) connections. This requires + the OpenSSL package to be installed. The "DIRECTORY" argument + specifies the root directory of the OpenSSL installation; the + default is "/usr/local/ssl". + "configure" will check for the required header files and libraries + to make sure that your OpenSSL installation is sufficient before + proceeding. + --with-pam - Build with PAM (Pluggable Authentication Modules) - support. - + + Build with PAM (Pluggable Authentication Modules) support. + --without-readline - Prevents the use of the Readline library. This disables - command-line editing and history in psql, so it is not - recommended. - + + Prevents the use of the Readline library. This disables command- + line editing and history in psql, so it is not recommended. + --with-rendezvous - Build with Rendezvous support. - + + Build with Rendezvous support. + --disable-spinlocks - Allows source builds to succeed without CPU spinlock - support. Lack of spinlock support will produce poor - performance. This option is to be used only by platforms - lacking spinlock support. - + + Allow the builds to succeed even if PostgreSQL has no CPU spinlock + support for the platform. The lack of spinlock support will result + in poor performance; therefore, this option should only be used if + the build aborts and informs you that the platform lacks spinlock + support. + --enable-thread-safety - Allow separate libpq and ecpg threads to safely control - their private connection handles. - + + Make the client libraries thread-safe. This allows concurrent + threads in libpq and ECPG programs to safely control their private + connection handles. + --without-zlib - Prevents the use of the Zlib library. This disables - compression support in pg_dump. This option is only - intended for those rare systems where this library is not - available. - + + Prevents the use of the Zlib library. This disables compression + support in pg_dump. This option is only intended for those rare + systems where this library is not available. + --enable-debug - Compiles all programs and libraries with debugging - symbols. This means that you can run the programs through - a debugger to analyze problems. This enlarges the size of - the installed executables considerably, and on non-GCC - compilers it usually also disables compiler optimization, - causing slowdowns. However, having the symbols available - is extremely helpful for dealing with any problems that - may arise. Currently, this option is recommended for - production installations only if you use GCC. But you - should always have it on if you are doing development - work or running a beta version. - + + Compiles all programs and libraries with debugging symbols. This + means that you can run the programs through a debugger to analyze + problems. This enlarges the size of the installed executables + considerably, and on non-GCC compilers it usually also disables + compiler optimization, causing slowdowns. However, having the + symbols available is extremely helpful for dealing with any + problems that may arise. Currently, this option is recommended for + production installations only if you use GCC. But you should always + have it on if you are doing development work or running a beta + version. + --enable-cassert - Enables assertion checks in the server, which test for - many "can't happen" conditions. This is invaluable for - code development purposes, but the tests slow things down - a little. Also, having the tests turned on won't - necessarily enhance the stability of your server! The - assertion checks are not categorized for severity, and so - what might be a relatively harmless bug will still lead - to server restarts if it triggers an assertion failure. - Currently, this option is not recommended for production - use, but you should have it on for development work or - when running a beta version. - + + Enables assertion checks in the server, which test for many "can't + happen" conditions. This is invaluable for code development + purposes, but the tests slow things down a little. Also, having the + tests turned on won't necessarily enhance the stability of your + server! The assertion checks are not categorized for severity, and + so what might be a relatively harmless bug will still lead to + server restarts if it triggers an assertion failure. Currently, + this option is not recommended for production use, but you should + have it on for development work or when running a beta version. + --enable-depend - Enables automatic dependency tracking. With this option, - the makefiles are set up so that all affected object - files will be rebuilt when any header file is changed. - This is useful if you are doing development work, but is - just wasted overhead if you intend only to compile once - and install. At present, this option will work only if - you use GCC. - - If you prefer a C compiler different from the one "configure" - picks then you can set the environment variable CC to the program - of your choice. By default, "configure" will pick "gcc" unless - this is inappropriate for the platform. Similarly, you can - override the default compiler flags with the CFLAGS variable. - You can specify environment variables on the "configure" command - line, for example: -./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe' - 2. Build - To start the build, type -gmake - (Remember to use GNU make.) The build may take anywhere from 5 - minutes to half an hour depending on your hardware. The last line - displayed should be -All of PostgreSQL is successfully made. Ready to install. - 3. Regression Tests - If you want to test the newly built server before you install it, - you can run the regression tests at this point. The regression - tests are a test suite to verify that PostgreSQL runs on your - machine in the way the developers expected it to. Type -gmake check - (This won't work as root; do it as an unprivileged user.) It is - possible that some tests fail, due to differences in error message - wording or floating point results. The file - "src/test/regress/README" and the documentation contain detailed - information about interpreting the test results. You can repeat - this test at any later time by issuing the same command. - 4. Installing The Files - - Note: If you are upgrading an existing system and are going to - install the new files over the old ones, then you should have - backed up your data and shut down the old server by now, as - explained in the section called If You Are Upgrading above. - To install PostgreSQL enter -gmake install - This will install files into the directories that were specified - in step 1. Make sure that you have appropriate permissions to - write into that area. Normally you need to do this step as root. - Alternatively, you could create the target directories in advance - and arrange for appropriate permissions to be granted. - You can use gmake install-strip instead of gmake install to strip - the executable files and libraries as they are installed. This - will save some space. If you built with debugging support, - stripping will effectively remove the debugging support, so it - should only be done if debugging is no longer needed. - install-strip tries to do a reasonable job saving space, but it - does not have perfect knowledge of how to strip every unneeded - byte from an executable file, so if you want to save all the disk - space you possibly can, you will have to do manual work. - The standard installation provides only the header files needed - for client application development. If you plan to do any - server-side program development (such as custom functions or data - types written in C), then you may want to install the entire - PostgreSQL include tree into your target include directory. To do - that, enter -gmake install-all-headers - This adds a megabyte or two to the installation footprint, and is - only useful if you don't plan to keep the whole source tree around - for reference. (If you do, you can just use the source's include - directory when building server-side software.) - Client-only installation: If you want to install only the client - applications and interface libraries, then you can use these - commands: -gmake -C src/bin install -gmake -C src/include install -gmake -C src/interfaces install -gmake -C doc install - - Uninstallation: To undo the installation use the command "gmake - uninstall". However, this will not remove any created directories. - - Cleaning: After the installation you can make room by removing the - built files from the source tree with the command "gmake clean". This - will preserve the files made by the "configure" program, so that you - can rebuild everything with "gmake" later on. To reset the source tree - to the state in which it was distributed, use "gmake distclean". If - you are going to build for several platforms from the same source tree - you must do this and re-configure for each build. - - If you perform a build and then discover that your "configure" options - were wrong, or if you change anything that "configure" investigates - (for example, software upgrades), then it's a good idea to do "gmake - distclean" before reconfiguring and rebuilding. Without this, your - changes in configuration choices may not propagate everywhere they - need to. - _________________________________________________________________ - - Post-Installation Setup - - Tuning - - By default, PostgreSQL is configured to run on minimal hardware. This - allows it to start up with almost any hardware configuration. However, - the default configuration is not designed for optimum performance. To - achieve optimum performance, several server variables must be - adjusted, the two most common being shared_buffers and sort_mem - mentioned in the documentation . Other parameters in the documentation - also affect performance. - _________________________________________________________________ - - Shared Libraries - - On some systems that have shared libraries (which most systems do) you - need to tell your system how to find the newly installed shared - libraries. The systems on which this is *not* necessary include - BSD/OS, FreeBSD, HP-UX, IRIX, Linux, NetBSD, OpenBSD, Tru64 UNIX - (formerly Digital UNIX), and Solaris. - - The method to set the shared library search path varies between - platforms, but the most widely usable method is to set the environment - variable LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", - "bash", "zsh") -LD_LIBRARY_PATH=/usr/local/pgsql/lib -export LD_LIBRARY_PATH - or in "csh" or "tcsh" -setenv LD_LIBRARY_PATH /usr/local/pgsql/lib + Enables automatic dependency tracking. With this option, the + makefiles are set up so that all affected object files will be + rebuilt when any header file is changed. This is useful if you are + doing development work, but is just wasted overhead if you intend + only to compile once and install. At present, this option will work + only if you use GCC. - Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in - step 1. You should put these commands into a shell start-up file such - as "/etc/profile" or "~/.bash_profile". Some good information about - the caveats associated with this method can be found at - http://www.visi.com/~barr/ldpath.html. - - On some systems it might be preferable to set the environment variable - LD_RUN_PATH *before* building. - - On Cygwin, put the library directory in the PATH or move the ".dll" - files into the "bin" directory. - - If in doubt, refer to the manual pages of your system (perhaps "ld.so" - or "rld"). If you later on get a message like -psql: error in loading shared libraries -libpq.so.2.1: cannot open shared object file: No such file or directory + If you prefer a C compiler different from the one "configure" picks then + you can set the environment variable CC to the program of your choice. By + default, "configure" will pick "gcc" unless this is inappropriate for the + platform. Similarly, you can override the default compiler flags with the + CFLAGS variable. - then this step was necessary. Simply take care of it then. - - If you are on BSD/OS, Linux, or SunOS 4 and you have root access you - can run -/sbin/ldconfig /usr/local/pgsql/lib + You can specify environment variables on the "configure" command line, + for example: - (or equivalent directory) after installation to enable the run-time - linker to find the shared libraries faster. Refer to the manual page - of "ldconfig" for more information. On FreeBSD, NetBSD, and OpenBSD - the command is -/sbin/ldconfig -m /usr/local/pgsql/lib + ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe' - instead. Other systems are not known to have an equivalent command. - _________________________________________________________________ - - Environment Variables - - If you installed into "/usr/local/pgsql" or some other location that - is not searched for programs by default, you should add - "/usr/local/pgsql/bin" (or whatever you set "--bindir" to in step 1) - into your PATH. Strictly speaking, this is not necessary, but it will - make the use of PostgreSQL much more convenient. - - To do this, add the following to your shell start-up file, such as - "~/.bash_profile" (or "/etc/profile", if you want it to affect every - user): -PATH=/usr/local/pgsql/bin:$PATH -export PATH + 2. Build + To start the build, type - If you are using "csh" or "tcsh", then use this command: -set path = ( /usr/local/pgsql/bin $path ) + gmake - To enable your system to find the man documentation, you need to add - lines like the following to a shell start-up file unless you installed - into a location that is searched by default. -MANPATH=/usr/local/pgsql/man:$MANPATH -export MANPATH + (Remember to use GNU make.) The build may take anywhere from 5 minutes to + half an hour depending on your hardware. The last line displayed should + be - The environment variables PGHOST and PGPORT specify to client - applications the host and port of the database server, overriding the - compiled-in defaults. If you are going to run client applications - remotely then it is convenient if every user that plans to use the - database sets PGHOST. This is not required, however: the settings can - be communicated via command line options to most client programs. - _________________________________________________________________ - - Getting Started - - The following is a quick summary of how to get PostgreSQL up and - running once installed. The main documentation contains more - information. - 1. Create a user account for the PostgreSQL server. This is the user - the server will run as. For production use you should create a - separate, unprivileged account ("postgres" is commonly used). If - you do not have root access or just want to play around, your own - user account is enough, but running the server as root is a - security risk and will not work. -adduser postgres - 2. Create a database installation with the "initdb" command. To run - "initdb" you must be logged in to your PostgreSQL server account. - It will not work as root. -root# mkdir /usr/local/pgsql/data -root# chown postgres /usr/local/pgsql/data -root# su - postgres -postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data - The "-D" option specifies the location where the data will be - stored. You can use any path you want, it does not have to be - under the installation directory. Just make sure that the server - account can write to the directory (or create it, if it doesn't - already exist) before starting "initdb", as illustrated here. - 3. The previous step should have told you how to start up the - database server. Do so now. The command should look something like -/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data - This will start the server in the foreground. To put the server in - the background use something like -nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \ - >server.log 2>&1 or - , not to the people listed here. - - OS Processor Version Reported Remarks - AIX RS6000 7.3 2002-11-12, Andreas Zeugswetter - () see also doc/FAQ_AIX - BSD/OS x86 7.3 2002-10-25, Bruce Momjian () - 4.2 - FreeBSD Alpha 7.3 2002-11-13, Chris Kings-Lynne - () - FreeBSD x86 7.3 2002-10-29, 3.3, Nigel J. Andrews - (), 4.7, Larry Rosenman - (), 5.0, Sean Chittenden () - HP-UX PA-RISC 7.3 2002-10-28, 10.20 Tom Lane (), - 11.00, 11.11, 32 and 64 bit, Giles Lean () gcc - and cc; see also doc/FAQ_HPUX - IRIX MIPS 7.3 2002-10-27, Ian Barwick () Irix64 Komma - 6.5 - Linux Alpha 7.3 2002-10-28, Magnus Naeslund () - 2.4.19-pre6 - Linux armv4l 7.2 2001-12-10, Mark Knox () 2.2.x - Linux MIPS 7.2 2001-11-15, Hisao Shibuya () - 2.0.x; Cobalt Qube2 - Linux PlayStation 2 7.3 2002-11-19, Permaine Cheung - ) #undef HAS_TEST_AND_SET, remove slock_t typedef - Linux PPC74xx 7.3 2002-10-26, Tom Lane () bye - 2.2.18; Apple G3 - Linux S/390 7.3 2002-11-22, Permaine Cheung ) both - s390 and s390x (32 and 64 bit) - Linux Sparc 7.3 2002-10-26, Doug McNaught () 3.0 - Linux x86 7.3 2002-10-26, Alvaro Herrera () - 2.4 - MacOS X PPC 7.3 2002-10-28, 10.1, Tom Lane (), - 10.2.1, Adam Witney () - NetBSD Alpha 7.2 2001-11-20, Thomas Thai () 1.5W - NetBSD arm32 7.3 2002-11-19, Patrick Welche () - 1.6 - NetBSD m68k 7.0 2000-04-10, Henry B. Hotz () Mac - 8xx - NetBSD MIPS 7.2.1 2002-06-13, Warwick Hunter () - 1.5.3 - NetBSD PPC 7.2 2001-11-28, Bill Studenmund () 1.5 - NetBSD Sparc 7.2 2001-12-03, Matthew Green () 32- - and 64-bit builds - NetBSD VAX 7.1 2001-03-30, Tom I. Helbekkmo () 1.5 - NetBSD x86 7.3 2002-11-14, Patrick Welche () 1.6 - OpenBSD Sparc 7.3 2002-11-17, Christopher Kings-Lynne - () 3.2 - OpenBSD x86 7.3 2002-11-14, 3.1 Magnus Naeslund (), 3.2 - Christopher Kings-Lynne () - SCO OpenServer 5 x86 7.3.1 2002-12-11, Shibashish Satpathy - () 5.0.4, gcc; see also doc/FAQ_SCO - Solaris Sparc 7.3 2002-10-28, Andrew Sullivan - () Solaris 7 and 8; see also doc/FAQ_Solaris - Solaris x86 7.3 2002-11-20, Martin Renters () 5.8; - see also doc/FAQ_Solaris - SunOS 4 Sparc 7.2 2001-12-04, Tatsuo Ishii () - Tru64 UNIX Alpha 7.3 2002-11-05, Alessio Bragadini - () - UnixWare x86 7.3 2002-11-01, 7.1.3 Larry Rosenman (), - 7.1.1 and 7.1.2(8.0.0) Olivier Prenant () see also - doc/FAQ_SCO - Windows x86 7.3 2002-10-29, Dave Page (), - Jason Tishler () with Cygwin; see doc/FAQ_MSWIN - Windows x86 7.3 2002-11-05, Dave Page () - native is client-side only; see documentation - - Unsupported Platforms: The following platforms are either known not to - work, or they used to work in a previous release and we did not - receive explicit confirmation of a successful test with version 7.4 at - the time this list was compiled. We include these here to let you know - that these platforms *could* be supported if given some attention. - - OS Processor Version Reported Remarks - BeOS x86 7.2 2001-11-29, Cyril Velter () - needs updates to semaphore code - DG/UX 5.4R4.11 m88k 6.3 1998-03-01, Brian E Gallew () - no recent reports - MkLinux DR1 PPC750 7.0 2001-04-03, Tatsuo Ishii () - 7.1 needs OS update? - NeXTSTEP x86 6.x 1998-03-01, David Wetzel () bit rot - suspected - QNX 4 RTOS x86 7.2 2001-12-10, Bernd Tegge () - needs updates to semaphore code; see also doc/FAQ_QNX4 - QNX RTOS v6 x86 7.2 2001-11-20, Igor Kovalenko - () patches available in archives, but too - late for 7.2 - System V R4 m88k 6.2.1 1998-03-01, Doug Winterburn - () needs new TAS spinlock code - System V R4 MIPS 6.4 1998-10-28, Frank Ridderbusch - () no recent reports - Ultrix MIPS 7.1 2001-03-26 TAS spinlock code not detected - Ultrix VAX 6.x 1998-03-01 + All of PostgreSQL is successfully made. Ready to install. + + 3. Regression Tests + If you want to test the newly built server before you install it, you can + run the regression tests at this point. The regression tests are a test + suite to verify that PostgreSQL runs on your machine in the way the + developers expected it to. Type + + gmake check + + (This won't work as root; do it as an unprivileged user.) The file "src/ + test/regress/README" and the documentation contain detailed information + about interpreting the test results. You can repeat this test at any + later time by issuing the same command. + + 4. Installing The Files + Note: If you are upgrading an existing system and are going to + install the new files over the old ones, then you should have + backed up your data and shut down the old server by now, as + explained in + the Section called If You Are Upgrading + above. + To install PostgreSQL enter + + gmake install + + This will install files into the directories that were specified in step + 1. Make sure that you have appropriate permissions to write into that + area. Normally you need to do this step as root. Alternatively, you could + create the target directories in advance and arrange for appropriate + permissions to be granted. + You can use gmake install-strip instead of gmake install to strip the + executable files and libraries as they are installed. This will save some + space. If you built with debugging support, stripping will effectively + remove the debugging support, so it should only be done if debugging is + no longer needed. install-strip tries to do a reasonable job saving + space, but it does not have perfect knowledge of how to strip every + unneeded byte from an executable file, so if you want to save all the + disk space you possibly can, you will have to do manual work. + The standard installation provides only the header files needed for + client application development. If you plan to do any server-side program + development (such as custom functions or data types written in C), then + you may want to install the entire PostgreSQL include tree into your + target include directory. To do that, enter + + gmake install-all-headers + + This adds a megabyte or two to the installation footprint, and is only + useful if you don't plan to keep the whole source tree around for + reference. (If you do, you can just use the source's include directory + when building server-side software.) + Client-only installation: If you want to install only the client + applications and interface libraries, then you can use these commands: + + gmake -C src/bin install + gmake -C src/include install + gmake -C src/interfaces install + gmake -C doc install + +Uninstallation: To undo the installation use the command "gmake uninstall". +However, this will not remove any created directories. +Cleaning: After the installation you can make room by removing the built files +from the source tree with the command "gmake clean". This will preserve the +files made by the "configure" program, so that you can rebuild everything with +"gmake" later on. To reset the source tree to the state in which it was +distributed, use "gmake distclean". If you are going to build for several +platforms from the same source tree you must do this and re-configure for each +build. +If you perform a build and then discover that your "configure" options were +wrong, or if you change anything that "configure" investigates (for example, +software upgrades), then it's a good idea to do "gmake distclean" before +reconfiguring and rebuilding. Without this, your changes in configuration +choices may not propagate everywhere they need to. + +------------------------------------------------------------------------------- + +Post-Installation Setup + +Shared Libraries + +On some systems that have shared libraries (which most systems do) you need to +tell your system how to find the newly installed shared libraries. The systems +on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux, +NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris. +The method to set the shared library search path varies between platforms, but +the most widely usable method is to set the environment variable +LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh") + + LD_LIBRARY_PATH=/usr/local/pgsql/lib + export LD_LIBRARY_PATH + +or in "csh" or "tcsh" + + setenv LD_LIBRARY_PATH /usr/local/pgsql/lib + +Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You +should put these commands into a shell start-up file such as "/etc/profile" or +"~/.bash_profile". Some good information about the caveats associated with this +method can be found at http://www.visi.com/~barr/ldpath.html. +On some systems it might be preferable to set the environment variable +LD_RUN_PATH *before* building. +On Cygwin, put the library directory in the PATH or move the ".dll" files into +the "bin" directory. +If in doubt, refer to the manual pages of your system (perhaps "ld.so" or +"rld"). If you later on get a message like + + psql: error in loading shared libraries + libpq.so.2.1: cannot open shared object file: No such file or directory + +then this step was necessary. Simply take care of it then. +If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run + + /sbin/ldconfig /usr/local/pgsql/lib + +(or equivalent directory) after installation to enable the run-time linker to +find the shared libraries faster. Refer to the manual page of "ldconfig" for +more information. On FreeBSD, NetBSD, and OpenBSD the command is + + /sbin/ldconfig -m /usr/local/pgsql/lib + +instead. Other systems are not known to have an equivalent command. + +------------------------------------------------------------------------------- + +Environment Variables + +If you installed into "/usr/local/pgsql" or some other location that is not +searched for programs by default, you should add "/usr/local/pgsql/bin" (or +whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking, +this is not necessary, but it will make the use of PostgreSQL much more +convenient. +To do this, add the following to your shell start-up file, such as +"~/.bash_profile" (or "/etc/profile", if you want it to affect every user): + + PATH=/usr/local/pgsql/bin:$PATH + export PATH + +If you are using "csh" or "tcsh", then use this command: + + set path = ( /usr/local/pgsql/bin $path ) + +To enable your system to find the man documentation, you need to add lines like +the following to a shell start-up file unless you installed into a location +that is searched by default. + + MANPATH=/usr/local/pgsql/man:$MANPATH + export MANPATH + +The environment variables PGHOST and PGPORT specify to client applications the +host and port of the database server, overriding the compiled-in defaults. If +you are going to run client applications remotely then it is convenient if +every user that plans to use the database sets PGHOST. This is not required, +however: the settings can be communicated via command line options to most +client programs. + +------------------------------------------------------------------------------- + +Getting Started + +The following is a quick summary of how to get PostgreSQL up and running once +installed. The main documentation contains more information. + + 1. Create a user account for the PostgreSQL server. This is the user the + server will run as. For production use you should create a separate, + unprivileged account ("postgres" is commonly used). If you do not have + root access or just want to play around, your own user account is enough, + but running the server as root is a security risk and will not work. + + adduser postgres + + 2. Create a database installation with the "initdb" command. To run "initdb" + you must be logged in to your PostgreSQL server account. It will not work + as root. + + root# mkdir /usr/local/pgsql/data + root# chown postgres /usr/local/pgsql/data + root# su - postgres + postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data + + The "-D" option specifies the location where the data will be stored. You + can use any path you want, it does not have to be under the installation + directory. Just make sure that the server account can write to the + directory (or create it, if it doesn't already exist) before starting + "initdb", as illustrated here. + + 3. The previous step should have told you how to start up the database + server. Do so now. The command should look something like + + /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data + + This will start the server in the foreground. To put the server in the + background use something like + + nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \ + >server.log 2>&1 or , not to the people listed here. + _____________________________________________________________________________ +|OS__________|Processor|Version|Reported______________________|Remarks________| +|AIX |RS6000 |7.4 |2003-10-25, Hans-Jürgen |see also doc/ | +|____________|_________|_______|Schönig_()____|FAQ_AIX________| +|BSD/OS |x86 |7.4 |2003-10-24, Bruce Momjian |4.3 | +|____________|_________|_______|()____|_______________| +|FreeBSD |Alpha |7.4 |2003-10-25, Peter Eisentraut |4.8 | +|____________|_________|_______|()___________|_______________| +|FreeBSD |x86 |7.4 |2003-10-24, Peter Eisentraut |4.9 | +|____________|_________|_______|()___________|_______________| +|HP-UX |PA-RISC |7.4 |2003-10-31, 10.20, Tom Lane |gcc and cc; see| +| | | |(); 2003- |also doc/ | +| | | |11-04, 11.00, Peter Eisentraut|FAQ_HPUX | +|____________|_________|_______|()___________|_______________| +|IRIX |MIPS |7.4 |2003-11-12, Robert E. |6.5.20, cc only| +| | | |Bruccoleri | | +|____________|_________|_______|()|_______________| +|Linux |Alpha |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |arm41 |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |Itanium |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |m68k |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |MIPS |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |Opteron |7.4 |2003-11-01, Jani Averbach |2.6 | +|____________|_________|_______|()_____________|_______________| +|Linux |PPC |7.4 |2003-10-25, Noèl Köthe | | +|____________|_________|_______|()___________|_______________| +|Linux |S/390 |7.4 |2003-10-25, Noèl Köthe |2.4 | +|____________|_________|_______|()___________|_______________| +|Linux |Sparc |7.4 |2003-10-24, Peter Eisentraut |2.4, 32-bit | +|____________|_________|_______|()___________|_______________| +|Linux |x86 |7.4 |2003-10-24, Peter Eisentraut |2.4 | +|____________|_________|_______|()___________|_______________| +|MacOS X |PPC |7.4 |2003-10-24, 10.2.8, Adam | | +| | | |Witney | | +| | | |(), 10.3,| | +| | | |Marko Karppinen | | +|____________|_________|_______|()________|_______________| +|NetBSD |arm32 |7.4 |2003-11-12, Patrick Welche |1.6ZE/acorn32 | +|____________|_________|_______|()______|_______________| +|NetBSD |x86 |7.4 |2003-10-24, Peter Eisentraut |1.6 | +|____________|_________|_______|()___________|_______________| +|OpenBSD |Sparc |7.4 |2003-11-01, Peter Eisentraut |3.4 | +|____________|_________|_______|()___________|_______________| +|OpenBSD |x86 |7.4 |2003-10-24, Peter Eisentraut |3.2 | +|____________|_________|_______|()___________|_______________| +|Solaris |Sparc |7.4 |2003-10-26, Christopher Browne|2.8; see also | +|____________|_________|_______|()__|doc/FAQ_Solaris| +|Solaris |x86 |7.4 |2003-10-26, Kurt Roeckx |2.6 see also | +|____________|_________|_______|()_________________|doc/FAQ_Solaris| +|Tru64 UNIX |Alpha |7.4 |2003-10-25, 5.1b, Peter | | +| | | |Eisentraut | | +| | | |(); 2003-10- | | +| | | |29, 4.0g, Alessio Bragadini | | +|____________|_________|_______|()______|_______________| +|UnixWare |x86 |7.4 |2003-11-03, Larry Rosenman |7.1.3; join | +| | | |() |test may fail, | +| | | | |see also doc/ | +|____________|_________|_______|______________________________|FAQ_SCO________| +|Windows with|x86 |7.4 |2003-10-24, Peter Eisentraut |see doc/ | +|Cygwin______|_________|_______|()___________|FAQ_MSWIN______| +|Windows |x86 |7.4 |2003-10-27, Dave Page |native is | +| | | |() |client-side | +| | | | |only, see | +|____________|_________|_______|______________________________|documentation__| + +Unsupported Platforms: The following platforms are either known not to work, or +they used to work in a previous release and we did not receive explicit +confirmation of a successful test with version 7.4 at the time this list was +compiled. We include these here to let you know that these platforms *could* be +supported if given some attention. + ________________________________________________________________________________ +|OS________|Processor__|Version|Reported_______________________|Remarks__________| +|BeOS |x86 |7.2 |2001-11-29, Cyril Velter |needs updates to | +|__________|___________|_______|()|semaphore_code___| +|Linux |PlayStation|7.4 |2003-11-02, Peter Eisentraut |needs new | +| |2 | |() |config.guess, -- | +| | | | |disable- | +| | | | |spinlocks, #undef| +| | | | |HAS_TEST_AND_SET,| +| | | | |disable tas_dummy| +|__________|___________|_______|_______________________________|()_______________| +|Linux |PA-RISC |7.4 |2003-10-25, Noèl Köthe |needs --disable- | +| | | |() |spinlocks, | +|__________|___________|_______|_______________________________|otherwise_OK_____| +|NetBSD |Alpha |7.2 |2001-11-20, Thomas Thai |1.5W | +|__________|___________|_______|()__________|_________________| +|NetBSD |MIPS |7.2.1 |2002-06-13, Warwick Hunter |1.5.3 | +|__________|___________|_______|()___________|_________________| +|NetBSD |PPC |7.2 |2001-11-28, Bill Studenmund |1.5 | +|__________|___________|_______|()________|_________________| +|NetBSD |Sparc |7.2 |2001-12-03, Matthew Green |32- and 64-bit | +|__________|___________|_______|()__________|builds___________| +|NetBSD |VAX |7.1 |2001-03-30, Tom I. Helbekkmo |1.5 | +|__________|___________|_______|()____________|_________________| +|QNX 4 RTOS|x86 |7.2 |2001-12-10, Bernd Tegge |needs updates to | +| | | |() |semaphore code; | +| | | | |see also doc/ | +|__________|___________|_______|_______________________________|FAQ_QNX4_________| +|QNX RTOS |x86 |7.2 |2001-11-20, Igor Kovalenko |patches available| +|v6 | | |()|in archives, but | +|__________|___________|_______|_______________________________|too_late_for_7.2_| +|SCO |x86 |7.3.1 |2002-12-11, Shibashish Satpathy|5.0.4, gcc; see | +|OpenServer|___________|_______|()__________|also_doc/FAQ_SCO_| +|SunOS 4 |Sparc |7.2 |2001-12-04, Tatsuo Ishii ()______________|_________________| diff --git a/src/test/regress/README b/src/test/regress/README index 86311be898..2bebafa3d1 100644 --- a/src/test/regress/README +++ b/src/test/regress/README @@ -1,243 +1,280 @@ -Regression Tests - -Introduction + Regression Tests The regression tests are a comprehensive set of tests for the SQL -implementation in PostgreSQL. They test standard SQL operations as well as -the extended capabilities of PostgreSQL. The test suite was originally -developed by Jolly Chen and Andrew Yu, and was extensively revised and -repackaged by Marc Fournier and Thomas Lockhart. From PostgreSQL 6.1 onward -the regression tests are current for every official release. +implementation in PostgreSQL. They test standard SQL operations as well as the +extended capabilities of PostgreSQL. From PostgreSQL 6.1 onward, the regression +tests are current for every official release. - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Running the Tests -The regression test can be run against an already installed and running -server, or using a temporary installation within the build tree. -Furthermore, there is a "parallel" and a "sequential" mode for running the -tests. 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. For historical reasons, the -sequential test is usually run against an existing installation and the -parallel method against a temporary installation, but there are no technical -reasons for this. +The regression test can be run against an already installed and running server, +or using a temporary installation within the build tree. Furthermore, there is +a "parallel" and a "sequential" mode for running the tests. 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. For historical reasons, the sequential test is usually run against +an existing installation and the parallel method against a temporary +installation, but there are no technical reasons for this. To run the regression tests after building but before installation, type -$ gmake check + gmake check -in the top-level directory. (Or you can change to src/test/regress and run -the command there.) This will first build several auxiliary files, such as -platform-dependent "expected" files and some sample user-defined trigger -functions, and then run the test driver script. At the end you should see -something like +in the top-level directory. (Or you can change to "src/test/regress" and run +the command there.) This will first build several auxiliary files, such as some +sample user-defined trigger functions, and then run the test driver script. At +the end you should see something like -====================== - All 77 tests passed. -====================== + ====================== + All 93 tests passed. + ====================== -or otherwise a note about what tests failed. See the Section called Test +or otherwise a note about which tests failed. See the Section called Test Evaluation below for more. - Note: Because this test method runs a temporary server, it will - not work when you are the root user (the server will not start as - root). If you already did the build as root, you do not have to - start all over. Instead, make the regression test directory - writable by some other user, log in as that user, and restart the - tests. For example, +Because this test method runs a temporary server, it will not work when you are +the root user (since the server will not start as root). If you already did the +build as root, you do not have to start all over. Instead, make the regression +test directory writable by some other user, log in as that user, and restart +the tests. For example - root# chmod -R a+w src/test/regress - root# chmod -R a+w contrib/spi - root# su - joeuser - joeuser$ cd - joeuser$ gmake check + root# chmod -R a+w src/test/regress + root# chmod -R a+w contrib/spi + root# su - joeuser + joeuser$ cd top-level build directory + joeuser$ gmake check - (The only possible "security risk" here is that other users might - be able to alter the regression test results behind your back. Use - common sense when managing user permissions.) +(The only possible "security risk" here is that other users might be able to +alter the regression test results behind your back. Use common sense when +managing user permissions.) - Alternatively, run the tests after installation. +Alternatively, run the tests after installation. - Tip: On some systems, the default Bourne-compatible shell - (/bin/sh) gets confused when it has to manage too many child - processes in parallel. This may cause the parallel test run to - lock up or fail. In such cases, specify a different - Bourne-compatible shell on the command line, for example: +The parallel regression test starts quite a few processes under your user ID. +Presently, the maximum concurrency is twenty parallel test scripts, which means +sixty processes: there's a server process, a psql, and usually a shell parent +process for the psql for each test script. So if your system enforces a per- +user limit on the number of processes, make sure this limit is at least +seventy-five or so, else you may get random-seeming failures in the parallel +test. If you are not in a position to raise the limit, you can cut down the +degree of parallelism by setting the MAX_CONNECTIONS parameter. For example, - $ gmake SHELL=/bin/ksh check + gmake MAX_CONNECTIONS=10 check + +runs no more than ten tests concurrently. + +On some systems, the default Bourne-compatible shell ("/bin/sh") gets confused +when it has to manage too many child processes in parallel. This may cause the +parallel test run to lock up or fail. In such cases, specify a different +Bourne-compatible shell on the command line, for example: + + gmake SHELL=/bin/ksh check + +If no non-broken shell is available, you may be able to work around the problem +by limiting the number of connections, as shown above. To run the tests after installation, initialize a data area and start the server, then type -$ gmake installcheck + gmake installcheck -The tests will expect to contact the server at the local host and the -default port number, unless directed otherwise by PGHOST and PGPORT -environment variables. +The tests will expect to contact the server at the local host and the default +port number, unless directed otherwise by PGHOST and PGPORT environment +variables. - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Test Evaluation Some properly installed and fully functional PostgreSQL installations can -"fail" some of these regression tests due to platform-specific artifacts -such as varying 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. Nonetheless, we still strive -to maintain accurate reference files across all supported platforms, so it -can be expected that all tests pass. +"fail" some of these regression tests due to platform-specific artifacts such +as varying 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. Nonetheless, we still strive to maintain +accurate reference files across all supported platforms, so it can be expected +that all tests pass. -The actual outputs of the regression tests are in files in the -src/test/regress/results directory. The test script uses diff to compare -each output file against the reference outputs stored in the -src/test/regress/expected directory. Any differences are saved for your -inspection in src/test/regress/regression.diffs. (Or you can run diff -yourself, if you prefer.) +The actual outputs of the regression tests are in files in the "src/test/ +regress/results" directory. The test script uses "diff" to compare each output +file against the reference outputs stored in the "src/test/regress/expected" +directory. Any differences are saved for your inspection in "src/test/regress/ +regression.diffs". (Or you can run "diff" yourself, if you prefer.) - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Error message differences Some of the regression tests involve intentional invalid input values. Error messages can come from either the PostgreSQL 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 that can be validated by -inspection. +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 that can be validated by inspection. - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Locale differences -The tests expect to run in plain "C" locale. This should not cause any -problems when you run the tests against a temporary installation, since the -regression test driver takes care to start the server in C locale. However, -if you run the tests against an already-installed server that is using non-C -locale settings, you may see differences caused by varying rules for string -sort order, formatting of numeric and monetary values, and so forth. +If you run the tests against an already-installed server that was initialized +with a collation-order locale other than C, then there may be differences due +to sort order and follow-up failures. The regression test suite is set up to +handle this problem by providing alternative result files that together are +known to handle a large number of locales. For example, for the char test, the +expected file "char.out" handles the C and POSIX locales, and the file +"char_1.out" handles many other locales. The regression test driver will +automatically pick the best file to match against when checking for success and +for computing failure differences. (This means that the regression tests cannot +detect whether the results are appropriate for the configured locale. The tests +will simply pick the one result file that works best.) -In some locales the resulting differences are small and easily checked by -inspection. However, in a locale that changes the rules for formatting of -numeric values (typically by swapping the usage of commas and decimal -points), entry of some data values will fail, resulting in extensive -differences later in the tests where the missing data values are supposed to -be used. +If for some reason the existing expected files do not cover some locale, you +can add a new file. The naming scheme is testname_digit.out. The actual digit +is not significant. Remember that the regression test driver will consider all +such files to be equally valid test results. If the test results are platform- +specific, the technique described in the Section called Platform-specific +comparison files should be used instead. - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Date and time differences -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. +A few of the queries in the "horology" test will fail if you run the test on +the day of a daylight-saving time changeover, or the day after one. These +queries expect that the intervals between midnight yesterday, midnight today +and midnight tomorrow are exactly twenty-four hours --- which is wrong if +daylight-saving time went into or out of effect meanwhile. -Most of the date and time results are dependent on the time zone -environment. The reference files are generated for time zone PST8PDT -(Berkeley, California) and there will be apparent failures if the tests are -not run with that time zone setting. The regression test driver sets -environment variable PGTZ to PST8PDT, which normally ensures proper results. -However, your system must provide library support for the PST8PDT time zone, -or the time zone-dependent tests will fail. To verify that your machine does -have this support, type the following: + Note: Because USA daylight-saving time rules are used, this problem + always occurs on the first Sunday of April, the last Sunday of + October, and their following Mondays, regardless of when daylight- + saving time is in effect where you live. Also note that the problem + appears or disappears at midnight Pacific time (UTC-7 or UTC-8), not + midnight your local time. Thus the failure may appear late on + Saturday or persist through much of Tuesday, depending on where you + live. -$ env TZ=PST8PDT date +Most of the date and time results are dependent on the time zone environment. +The reference files are generated for time zone PST8PDT (Berkeley, California), +and there will be apparent failures if the tests are not run with that time +zone setting. The regression test driver sets environment variable PGTZ to +PST8PDT, which normally ensures proper results. However, your operating system +must provide support for the PST8PDT time zone, or the time zone-dependent +tests will fail. To verify that your machine does have this support, type the +following: -The 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: + env TZ=PST8PDT date -PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ +The command above should have returned the current system time in the PST8PDT +time zone. If the PST8PDT time zone is not available, then your system may have +returned the time in UTC. If the PST8PDT time zone is missing, you can set the +time zone rules explicitly: -There appear to be some systems that 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. + PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ -Some systems using older time zone libraries fail to apply daylight-savings -corrections to dates before 1970, causing pre-1970 PDT times to be displayed -in PST instead. This will result in localized differences in the test -results. +There appear to be some systems that 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 time-zone libraries fail to apply daylight-saving +corrections to dates before 1970, 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 (double precision) numbers from -table columns. Differences in results involving mathematical functions of -double precision columns have been observed. The float8 and geometry tests -are particularly prone to small differences across platforms, or even with -different compiler optimization options. 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. +Floating-point differences -Some systems signal errors from pow() and exp() differently from the -mechanism expected by the current PostgreSQL code. +Some of the tests involve computing 64-bit floating-point numbers (double +precision) from table columns. Differences in results involving mathematical +functions of double precision columns have been observed. The float8 and +geometry tests are particularly prone to small differences across platforms, or +even with different compiler optimization options. 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 display minus zero as -0, while others just show 0. -Polygon differences +Some systems signal errors from pow() and exp() differently from the mechanism +expected by the current PostgreSQL code. -Several of the tests involve operations on geographic data about the -Oakland/Berkeley, California street map. The map data is expressed as -polygons whose vertices are represented as pairs of double precision numbers -(decimal latitude and longitude). Initially, some tables are created and -loaded with geographic data, then some views are created that 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: - -SELECT * from street; -SELECT * from iexit; - - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- Row ordering differences You might see differences in which the same rows are output in a different order than what appears in the expected file. In most cases this is not, strictly speaking, a bug. Most of the regression test scripts are not so -pedantic as to use an ORDER BY for every single SELECT, and so their result -row orderings are not well-defined according to the letter of the SQL +pedantic as to use an ORDER BY for every single SELECT, and so their result row +orderings are not well-defined according to the letter of the SQL specification. In practice, since we are looking at the same queries being -executed on the same data by the same software, we usually get the same -result ordering on all platforms, and so the lack of ORDER BY isn't a -problem. Some queries do exhibit cross-platform ordering differences, -however. (Ordering differences can also be triggered by non-C locale -settings.) +executed on the same data by the same software, we usually get the same result +ordering on all platforms, and so the lack of ORDER BY isn't a problem. Some +queries do exhibit cross-platform ordering differences, however. (Ordering +differences can also be triggered by non-C locale settings.) Therefore, if you see an ordering difference, it's not something to worry about, unless the query does have an ORDER BY that your result is violating. -But please report it anyway, so that we can add an ORDER BY to that -particular query and thereby eliminate the bogus "failure" in future -releases. +But please report it anyway, so that we can add an ORDER BY to that particular +query and thereby eliminate the bogus "failure" in future releases. -You might wonder why we don't order all the regress test queries explicitly -to get rid of this issue once and for all. The reason is that that would -make the regression tests less useful, not more, since they'd tend to -exercise query plan types that produce ordered results to the exclusion of -those that don't. +You might wonder why we don't order all the regression test queries explicitly +to get rid of this issue once and for all. The reason is that that would make +the regression tests less useful, not more, since they'd tend to exercise query +plan types that produce ordered results to the exclusion of those that don't. - ------------------------------------------------------------------------ +------------------------------------------------------------------------------- The "random" test -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 +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 + 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 regression tests, you probably should 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 +regression tests, you probably *should* worry.) + +------------------------------------------------------------------------------- + +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 "src/test/regress/resultmap". + +Each line in the mapping file is of the form + + testname/platformpattern=comparisonfilename + +The test name is just the name of the particular regression test module. The +platform pattern is a pattern in the style of the Unix tool "expr" (that is, a +regular expression with an implicit ^ anchor at the start). It is matched +against the platform name as printed by "config.guess" followed by :gcc or :cc, +depending on whether you use the GNU compiler or the system's native compiler +(on systems where there is a difference). The comparison file name is the name +of the substitute result comparison file. + +For example: some systems using older time zone libraries fail to apply +daylight-saving corrections to dates before 1970, causing pre-1970 PDT times to +be displayed in PST instead. This causes a few differences in the "horology" +regression test. Therefore, we provide a variant comparison file, "horology-no- +DST-before-1970.out", which includes the results to be expected on these +systems. To silence the bogus "failure" message on HPUX platforms, "resultmap" +includes + + horology/.*-hpux=horology-no-DST-before-1970 + +which will trigger on any machine for which the output of "config.guess" +includes -hpux. Other lines in "resultmap" select the variant comparison file +for other platforms where it's appropriate.