PostgreSQL Installation Guide by The PostgreSQL Development Team Edited by Thomas Lockhart PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. Table of Contents Summary 1. Introduction 2. Ports Currently Supported Platforms Unsupported Platforms 3. Installation Requirements to Run Postgres Installation Procedure Playing with Postgres The Next Step Porting Notes Ultrix4.x Linux Linux ELF Linux a.out BSD/OS NeXT 4. Configuration Options Parameters for Configuration (configure) Parameters for Building (make) Locale Support What are the Benefits? What are the Drawbacks? Kerberos Authentication Availability Installation Operation 5. Release Notes Release 6.4 Migration to v6.4 Detailed Change List List of Tables 2-1. Supported Platforms 2-2. Possibly Incompatible Platforms 4-1. Kerberos Parameter Examples Summary Postgres, developed originally in the UC Berkeley Computer Science Department, pioneered many of the object-relational concepts now becoming available in some commercial databases. It provides SQL92/SQL3 language support, transaction integrity, and type extensibility. PostgreSQL is a public-domain, open source descendant of this original Berkeley code. Chapter 1. Introduction This installation procedure makes some assumptions about the desired configuration and runtime environment for your system. This may be adequate for many installations, and is almost certainly adequate for a first installation. But you may want to do an initial installation up to the point of unpacking the source tree and installing documentation, and then print or browse the Administrator's Guide. Chapter 2. Ports This manual describes version 6.4 of Postgres. The Postgres developer community has compiled and tested Postgres on a number of platforms. Check the web site for the latest information. Currently Supported Platforms At the time of publication, the following platforms have been tested: Table 2-1. Supported Platforms OS Processor Version Reported Remarks AIX 4.2.1 RS6000 v6.4 1998-10-27 (Andreas Zeugswetter) BSDI x86 v6.4 1998-10-25 (Bruce Momjian FreeBSD x86 v6.4 1998-10-26 (Tatsuo Ishii, Marc 2.2.x-3.x Fournier) DGUX 5.4R4.11 m88k v6.3 1998-03-01 v6.4 probably OK. Needs new maintainer. (Brian E Gallew) Digital Unix Alpha v6.4 1998-10-29 Minor patchable problems 4.0 (Pedro J. Lobo) HPUX PA-RISC v6.4 1998-10-25 Both 9.0x and 10.20 (Tom Lane, Stan Brown) IRIX 6.x MIPS v6.3 1998-03-01 5.x is different (Andrew Martin) linux 2.0.x Alpha v6.3.2 1998-04-16 Mostly successful. Needs work for v6.4. (Ryan Kirkpatrick) linux 2.0.x x86 v6.4 1998-10-27 (Thomas Lockhart) linux x86 v6.4 1998-10-25 (Oliver Elphick, Taral) 2.0.x/glibc2 linux 2.0.x Sparc v6.4 1998-10-25 (Tom Szybist) linuxPPC PPC603e v6.4 1998-10-26 Powerbook 2400c (Tatsuo 2.1.24 Ishii) mklinux DR3 PPC750 v6.4 1998-09-16 PowerMac 7600 (Tatsuo Ishii) NetBSD/i386 x86 v6.4 1998-10-25 (Brook Milligan) 1.3.2 NetBSD- NS32532 v6.4 1998-10-27 (small problems in current date/time math (Jon Buller) NetBSD/sparc Sparc v6.4 1998-10-27 (Tom I Helbekkmo) 1.3H NetBSD 1.3 VAX v6.3 1998-03-01 (Tom I Helbekkmo) SCO UnixWare x86 v6.3 1998-03-01 aka UNIVEL (Billy G. 2.x Allie) SCO UnixWare x86 v6.4 1998-10-04 (Billy G. Allie) 7 Solaris x86 v6.4 1998-10-28 (Marc Fournier) Solaris Sparc v6.4 1998-10-28 (Tom Szybist, Frank 2.6-2.7 Ridderbusch) SunOS 4.1.4 Sparc v6.3 1998-03-01 patches submitted (Tatsuo Ishii) SVR4 MIPS v6.4 1998-10-28 no 64-bit int support (Frank Ridderbusch) SVR4 4.4 m88k v6.2.1 1998-03-01 confirmed with patching (Doug Winterburn) Windows NT x86 v6.4 1998-10-08 Mostly working with the Cygwin library. No DLLs yet. (Horak Daniel) Platforms listed for v6.3.x should also work with v6.4, but we did not receive confirmation of such at the time this list was compiled. Note: For Windows NT, the server-side port of Postgres has recently been accomplished. Check the Askesis Postgres Home Page for up to date information. You may also want to look for possible patches on the Postgres web site. Unsupported Platforms There are a few platforms which have been attempted and which have been reported to not work with the standard distribution. Others listed here do not provide sufficient library support for an attempt. Table 2-2. Possibly Incompatible Platforms OS Processor Version Reported Remarks MacOS all v6.3 1998-03-01 not library compatible; use ODBC/JDBC NetBSD arm32 v6.3 1998-03-01 not yet working (Dave Millen) NetBSD m68k v6.3 1998-03-01 Amiga, HP300, Mac; not yet working (Henry Hotz) NextStep x86 v6.x 1998-03-01 client-only support; v1.0.9 worked with patches (David Wetzel) Ultrix MIPS,VAX? v6.x 1998-03-01 no recent reports; obsolete? Windows x86 v6.3 1998-03-01 not library compatible; client side maybe; use ODBC/JDBC Note that Windows ports of the frontend are apparently possible using third-party Posix porting tools and libraries. Chapter 3. Installation Complete installation instructions for Postgres v6.4. Before installing Postgres, you may wish to visit www.postgresql.org for up to date information, patches, etc. These installation instructions assume: o Commands are Unix-compatible. See note below. o Defaults are used except where noted. o User postgres is the Postgres superuser. o The source path is /usr/src/pgsql (other paths are possible). o The runtime path is /usr/local/pgsql (other paths are possible). Commands were tested on RedHat Linux version 4.2 using the tcsh shell. Except where noted, they will probably work on most systems. Commands like ps and tar may vary wildly between platforms on what options you should use. Use common sense before typing in these commands. Our Makefiles require GNU make (called ?gmake? in this document). They will not work with non-GNU make programs. If you have GNU make installed under the name ?make? instead of ?gmake?, then you will use the command make instead. That's OK, but you need to have the GNU form of make to succeed with an installation. Requirements to Run Postgres Up to date information on supported platforms is at http://www.postgresql.org/docs/admin/install.htm. In general, most Unix-compatible platforms with modern libraries should be able to run Postgres. Although the minimum required memory for running Postgres is as little as 8MB, there are noticable improvements in runtimes for the regression tests when expanding memory up to 96MB on a relatively fast dual-processor system running X-Windows. The rule is you can never have too much memory. Check that you have sufficient disk space. You will need about 30 Mbytes for /usr/src/pgsql, about 5 Mbytes for /usr/local/pgsql (excluding your database) and 1 Mbyte for an empty database. The database will temporarily grow to about 20 Mbytes during the regression tests. You will also need about 3 Mbytes for the distribution tar file. We therefore recommend that during installation and testing you have well over 20 Mbytes free under /usr/local and another 25 Mbytes free on the disk partition containing your database. Once you delete the source files, tar file and regression database, you will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty database, plus about five times the space you would require to store your database data in a flat file. To check for disk space, use $ df -k Installation Procedure Procedure 3.1. Postgres Installation For a fresh install or upgrading from previous releases of Postgres: 1. Read any last minute information and platform specific porting notes. There are some platform specific notes at the end of this file for Ultrix4.x, Linux, BSD/OS and NeXT. There are other files in directory /usr/src/pgsql/doc, including files FAQ-Irix and FAQ-Linux. Also look in directory ftp://ftp.postgresql.org/pub. If there is a file called INSTALL in this directory then this file will contain the latest installation information. Please note that a "tested" platform in the list given earlier simply means that someone went to the effort at some point of making sure that a Postgres distribution would compile and run on this platform without modifying the code. Since the current developers will not have access to all of these platforms, some of them may not compile cleanly and pass the regression tests in the current release due to minor problems. Any such known problems and their solutions will be posted in ftp://ftp.postgresql.org/pub/INSTALL. 2. Create the Postgres superuser account (postgres is commonly used) if it does not already exist. The owner of the Postgres files can be any unprivileged user account. It must not be root, bin, or any other account with special access rights, as that would create a security risk. 3. Log in to the Postgres superuser account. Most of the remaining steps in the installation will happen in this account. 4. Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the Internet. Store it in your home directory. 5. Some platforms use flex. If your system uses flex then make sure you have a good version. To check, type $ flex --version If the flex command is not found then you probably do not need it. If the version is 2.5.2 or 2.5.4 or greater then you are okay. If it is 2.5.3 or before 2.5.2 then you will have to upgrade flex. You may get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz. If you need flex and don't have it or have the wrong version, then you will be told so when you attempt to compile the program. Feel free to skip this step if you aren't sure you need it. If you do need it then you will be told to install/upgrade flex when you try to compile Postgres. You may want to do the entire flex installation from the root account, though that is not absolutely necessary. Assuming that you want the installation to place files in the usual default areas, type the following: $ su - $ cd /usr/local/src ftp prep.ai.mit.edu ftp> cd /pub/gnu/ ftp> binary ftp> get flex-2.5.4.tar.gz ftp> quit $ gunzip -c flex-2.5.4.tar.gz | tar xvf - $ cd flex-2.5.4 $ configure --prefix=/usr $ gmake $ gmake check # You must be root when typing the next line: $ gmake install $ cd /usr/local/src $ rm -rf flex-2.5.4 This will update files /usr/man/man1/flex.1, /usr/bin/flex, /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add a link /usr/bin/flex++ which points to flex. 6. If you are not upgrading an existing system then skip to step 9. If you are upgrading an existing system then back up your database. For alpha- and beta-level releases, the database format is liable to change, often every few weeks, with no notice besides a quick comment in the HACKERS mailing list. Full releases always require a dump/reload from previous releases. It is therefore a bad idea to skip this step. Tip: Do not use the pg_dumpall script from v6.0 or everything will be owned by the Postgres super user. To dump your fairly recent post-v6.0 database installation, type $ pg_dumpall -z > db.out To use the latest pg_dumpall script on your existing older database before upgrading Postgres, pull the most recent version of pg_dumpall from the new distribution: $ cd $ gunzip -c postgresql-v6.4.tar.gz \ | tar xvf - src/bin/pg_dump/pg_dumpall $ chmod a+x src/bin/pg_dump/pg_dumpall $ src/bin/pg_dump/pg_dumpall -z > db.out $ rm -rf src If you wish to preserve object id's (oids), then use the -o option when running pg_dumpall. However, unless you have a special reason for doing this (such as using OIDs as keys in tables), don't do it. If the pg_dumpall command seems to take a long time and you think it might have died, then, from another terminal, type $ ls -l db.out several times to see if the size of the file is growing. Please note that if you are upgrading from a version prior to Postgres95 v1.09 then you must back up your database, install Postgres95 v1.09, restore your database, then back it up again. You should also read the release notes which should cover any release-specific issues. Caution You must make sure that your database is not updated in the middle of your backup. If necessary, bring down postmaster, edit the permissions in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring postmaster back up. 7. If you are upgrading an existing system then kill the postmaster. Type $ ps -ax | grep postmaster This should list the process numbers for a number of processes. Type the following line, with pid replaced by the process id for process postmaster. (Do not use the id for process "grep postmaster".) Type $ kill pid to actually stop the process. Tip: On systems which have Postgres started at boot time, there is probably a startup file which will accomplish the same thing. For example, on my Linux system I can type $ /etc/rc.d/init.d/postgres.init stop to halt Postgres. 8. If you are upgrading an existing system then move the old directories out of the way. If you are short of disk space then you may have to back up and delete the directories instead. If you do this, save the old database in the /usr/local/pgsql/data directory tree. At a minimum, save file /usr/local/pgsql/data/pg_hba.conf. Type the following: $ su - $ cd /usr/src $ mv pgsql pgsql_6_0 $ cd /usr/local $ mv pgsql pgsql_6_0 $ exit If you are not using /usr/local/pgsql/data as your data directory (check to see if environment variable PGDATA is set to something else) then you will also want to move this directory in the same manner. 9. Make new source and install directories. The actual paths can be different for your installation but you must be consistant throughout this procedure. Note: There are two places in this installation procedure where you will have an opportunity to specify installation locations for programs, libraries, documentation, and other files. Usually it is sufficient to specify these at the make install stage of installation. Type $ su $ cd /usr/src $ mkdir pgsql $ chown postgres:postgres pgsql $ cd /usr/local $ mkdir pgsql $ chown postgres:postgres pgsql $ exit 10. Unzip and untar the new source file. Type $ cd /usr/src/pgsql $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf - 11. Configure the source code for your system. It is this step at which you can specify your actual installation path for the build process (see the --prefix option below). Type $ cd /usr/src/pgsql/src $ ./configure [ options ] a. Among other chores, the configure script selects a system-specific "template" file from the files provided in the template subdirectory. If it cannot guess which one to use for your system, it will say so and exit. In that case you'll need to figure out which one to use and run configure again, this time giving the --with-template=TEMPLATE option to make the right file be chosen. Please Report Problems: If your system is not automatically recognized by configure and you have to do this, please send email to scrappy@hub.org with the output of the program ./config.guess. Indicate what the template file should be. b. Choose configuration options. Check Configuration Options for details. However, for a plain-vanilla first installation with no extra options like multi-byte character support or locale collation support it may be adequate to have chosen the installation areas and to run configure without extra options specified. The configure script accepts many additional options that you can use if you don't like the default configuration. To see them all, type ./configure --help Some of the more commonly used ones are: --prefix=BASEDIR Selects a different base directory The default is /usr/local/pgsql. --with-template=TEMPLATE Use template file TEMPLATE - the template files are assumed to be in the directory src/template, so look there for proper values. --with-tcl Build interface libraries and programs requiring Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. --with-perl Build the Perl interface library. --with-odbc Build the ODBC driver package. --enable-hba Enables Host Based Authentication (DEFAULT) --disable-hba Disables Host Based Authentication --enable-locale Enables USE_LOCALE --enable-cassert Enables ASSERT_CHECKING --with-CC=compiler Use a specific C compiler that the configure script cannot find. --with-CXX=compiler --without-CXX Use a specific C++ compiler that the configure script cannot find, or exclude C++ compilation altogether. (This only affects libpq++ at present.) c. Here is the configure script used on a Sparc Solaris 2.5 system with /opt/postgres specified as the installation base directory: $ ./configure --prefix=/opt/postgres \ --with-template=sparc_solaris-gcc --with-pgport=5432 \ --enable-hba --disable-locale Tip: Of course, you may type these three lines all on the same line. 12. Install the man and HTML documentation. Type $ cd /usr/src/pgsql/doc $ gmake install The documentation is also available in Postscript format. Look for files ending with .ps.gz in the same directory. 13. 14. Compile the program. Type $ cd /usr/src/pgsql/src $ gmake all >& make.log & $ tail -f make.log The last line displayed will hopefully be All of PostgreSQL is successfully made. Ready to install. At this point, or earlier if you wish, type control-C to get out of tail. (If you have problems later on you may wish to examine file make.log for warning and error messages.) Note: You will probably find a number of warning messages in make.log. Unless you have problems later on, these messages may be safely ignored. If the compiler fails with a message stating that the flex command cannot be found then install flex as described earlier. Next, change directory back to this directory, type $ make clean then recompile again. Compiler options, such as optimization and debugging, may be specified on the command line using the COPT variable. For example, typing $ gmake COPT="-g" all >& make.log & would invoke your compiler's -g option in all steps of the build. See src/Makefile.global.in for further details. 15. Install the program. Type $ cd /usr/src/pgsql/src $ gmake install >& make.install.log & $ tail -f make.install.log The last line displayed will be gmake[1]: Leaving directory `/usr/src/pgsql/src/man' At this point, or earlier if you wish, type control-C to get out of tail. 16. If necessary, tell your system how to find the new shared libraries. You can do one of the following, preferably the first: a. As root, edit file /etc/ld.so.conf. Add a line /usr/local/pgsql/lib to the file. Then run command /sbin/ldconfig. b. In a bash shell, type export LD_LIBRARY_PATH=/usr/local/pgsql/lib c. In a csh shell, type setenv LD_LIBRARY_PATH /usr/local/pgsql/lib Please note that the above commands may vary wildly for different operating systems. Check the platform specific notes, such as those for Ultrix4.x or and for non-ELF Linux. If, when you create the database, you get the message pg_id: can't load library 'libpq.so' then the above step was necessary. Simply do this step, then try to create the database again. 17. If you used the --with-perl option to configure, check the install log to see whether the Perl module was actually installed. If you've followed our advice to make the Postgres files be owned by an unprivileged userid, then the Perl module won't have been installed, for lack of write privileges on the Perl library directories. You can complete its installation, either now or later, by becoming the user that does own the Perl library (often root) (via su) and doing $ cd /usr/src/pgsql/src/interfaces/perl5 $ gmake install 18. If it has not already been done, then prepare account postgres for using Postgres. Any account that will use Postgres must be similarly prepared. There are several ways to influence the runtime environment of the Postgres server. Refer to the Administrator's Guide for more information. Note: The following instructions are for a bash/sh shell. Adapt accordingly for other shells. a. Add the following lines to your login environment: shell, ~/.bash_profile: PATH=$PATH:/usr/local/pgsql/bin MANPATH=$MANPATH:/usr/local/pgsql/man PGLIB=/usr/local/pgsql/lib PGDATA=/usr/local/pgsql/data export PATH MANPATH PGLIB PGDATA b. Several regression tests could failed if the user's locale collation scheme is different from that of standard C locale. If you configure and compile Postgres with the --enable-locale option then set locale environment to C (or unset all LC_* variables) by putting these additional lines to your login environment before starting postmaster: LC_COLLATE=C LC_CTYPE=C LC_COLLATE=C export LC_COLLATE LC_CTYPE LC_COLLATE c. Make sure that you have defined these variables before continuing with the remaining steps. The easiest way to do this is to type: $ source ~/.bash_profile 19. Create the database installation from your Postgres superuser account (typically account postgres). Do not do the following as root! This would be a major security hole. Type $ initdb 20. Set up permissions to access the database system. Do this by editing file /usr/local/pgsql/data/pg_hba.conf. The instructions are included in the file. (If your database is not located in the default location, i.e. if PGDATA is set to point elsewhere, then the location of this file will change accordingly.) This file should be made read only again once you are finished. If you are upgrading from v6.0 or later you can copy file pg_hba.conf from your old database on top of the one in your new database, rather than redoing the file from scratch. 21. Briefly test that the backend will start and run by running it from the command line. a. Start the postmaster daemon running in the background by typing $ cd $ postmaster -i b. Create a database by typing $ createdb c. Connect to the new database: $ psql d. And run a sample query: postgres=> SELECT datetime 'now'; e. Exit psql: postgres=> \q f. Remove the test database (unless you will want to use it later for other tests): $ destroydb 22. Run postmaster in the background from your Postgres superuser account (typically account postgres). Do not run postmaster from the root account! Usually, you will want to modify your computer so that it will automatically start postmaster whenever it boots. It is not required; the Postgres server can be run successfully from non-privileged accounts without root intervention. Here are some suggestions on how to do this, contributed by various users. Whatever you do, postmaster must be run by the Postgres superuser (postgres?) and not by root. This is why all of the examples below start by switching user (su) to postgres. These commands also take into account the fact that environment variables like PATH and PGDATA may not be set properly. The examples are as follows. Use them with extreme caution. o If you are installing from a non-privileged account and have no root access, then start the postmaster and send it to the background: $ cd $ nohup postmaster > regress.log 2>&1 & o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1 to contain the following single line: su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to contain the following lines and make it chmod 755 and chown root:bin. #!/bin/sh [ -x /usr/local/pgsql/bin/postmaster ] && { su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data -S -o -F > /usr/local/pgsql/errlog' & echo -n ' pgsql' } You may put the line breaks as shown above. The shell is smart enough to keep parsing beyond end-of-line if there is an expression unfinished. The exec saves one layer of shell under the postmaster process so the parent is init. o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is based on the example in contrib/linux/. Then make a softlink to this file from /etc/rc.d/rc5.d/S98postgres.init. o In RedHat Linux edit file /etc/inittab to add the following as a single line: pg:2345:respawn:/bin/su - postgres -c "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data >> /usr/local/pgsql/server.log 2>&1 Create the database foo: template1=> create database foo; CREATEDB (Get in the habit of including those SQL semicolons. Psql won't execute anything until it sees the semicolon or a "\g" and the semicolon is required to delimit multiple statements.) Now connect to the new database: template1=> \c foo connecting to new database: foo ("slash" commands aren't SQL, so no semicolon. Use \? to see all the slash commands.) And create a table: foo=> create table bar (i int4, c char(16)); CREATE Then inspect the new table: foo=> \d bar Table = bar +--------------+--------------+-------+ | Field | Type | Length| +--------------+--------------+-------+ | i | int4 | 4 | | c | (bp)char | 16 | +--------------+--------------+-------+ And so on. You get the idea. The Next Step Questions? Bugs? Feedback? First, read the files in directory /usr/src/pgsql/doc/. The FAQ in this directory may be particularly useful. If Postgres failed to compile on your computer then fill out the form in file /usr/src/pgsql/doc/bug.template and mail it to the location indicated at the top of the form. Check on the web site at http://www.postgresql.org For more information on the various support mailing lists. Porting Notes Note: Check for any platform-specific FAQs in the doc/ directory of the source distribution. For some ports, the notes below may be out of date. Ultrix4.x Note: There have been no recent reports of Ultrix usage with Postgres. You need to install the libdl-1.1 package since Ultrix 4.x doesn't have a dynamic loader. It's available in s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.- 1.tar.Z Linux Linux ELF The regression test reference machine is a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686. The linux-elf port installs cleanly. See the Linux FAQ for more details. Linux a.out For non-ELF Linux, the dld library MUST be obtained and installed on the system. It enables dynamic link loading capability to the Postgres port. The dld library can be obtained from the sunsite linux distributions. The current name is dld-3.2.5. Jalon Q. Zimmerman BSD/OS For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library. NeXT The NeXT port for v1.09 was supplied by Tom R. Hageman. It requires a SysV IPC emulation library and header files for shared libary and semaphore stuff. Tom just happens to sell such a product so contact him for information. He has also indicated that binary releases of Postgres for NEXTSTEP will be made available to the general public. Contact Info@RnA.nl for information. We have no recent reports of successful NeXT installations (as of v6.2.1). However, the client-side libraries should work even if the backend is not supported. Chapter 4. Configuration Options Parameters for Configuration (configure) The full set of parameters available in configure can be obtained by typing $ ./configure --help The following parameters may be of interest to installers: Directory and file names: --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local/pgsql] --bindir=DIR user executables in DIR [EPREFIX/bin] --libdir=DIR object code libraries in DIR [EPREFIX/lib] --includedir=DIR C header files in DIR [PREFIX/include] --mandir=DIR man documentation in DIR [PREFIX/man] Features and packages: --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE[=ARG] include FEATURE [ARG=yes] --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --enable and --with options recognized: --with-template=template use operating system template file see template directory --with-includes=incdir site header files for tk/tcl, etc in DIR --with-libs=incdir also search for libraries in DIR --with-libraries=libdir also search for libraries in DIR --enable-locale enable locale support --enable-recode enable cyrillic recode support --with-mb=encoding enable multi-byte support --with-pgport=portnum change default startup port --with-tcl use tcl --with-tclconfig=tcldir tclConfig.sh and tkConfig.sh are in DIR --with-perl use perl --with-odbc build ODBC driver package --with-odbcinst=odbcdir change default directory for odbcinst.ini --enable-cassert enable assertion checks (debugging) --with-CC=compiler use specific C compiler --with-CXX=compiler use specific C++ compiler --without-CXX do not build libpq++ Some systems may have trouble building a specific feature of Postgres. For example, systems with a damaged C++ compiler may need to specify --without-CXX to encourage the build procedure to ignore the libpq++ construction. Parameters for Building (make) Many installation-related parameters can be set in the building stage of Postgres installation. In most cases, these parameters should be place in a file, Makefile.custom, intended just for that purpose. The default distribution does not contain this optional file, so you will create it using a text editor of your choice. When upgrading installations, you can simply copy your old Makefile.custom to the new installation before doing the build. make [ variable=value [,...] ] A few of the many variables which can be specified are: POSTGRESDIR Top of the installation tree. BINDIR Location of applications and utilities. LIBDIR Location of object libraries, including shared libraries. HEADERDIR Location of include files. ODBCINST Location of installation-wide psqlODBC (ODBC) configuration file. There are other optional parameters which are not as commonly used. Many of those listed below are appropriate when doing Postgres server code development. CFLAGS Set flags for the C compiler. Should be assigned with "+=" to retain relevant default parameters. YFLAGS Set flags for the yacc/bison parser. -v might be used to help diagnose problems building a new parser. Should be assigned with "+=" to retain relevant default parameters. USE_TCL Enable Tcl interface building. HSTYLE DocBook HTML style sheets for building the documentation from scratch. Not used unless you are developing new documentation from the DocBook-compatible SGML source documents in doc/src/sgml/. PSTYLE DocBook style sheets for building printed documentation from scratch. Not used unless you are developing new documentation from the DocBook-compatible SGML source documents in doc/src/sgml/. Here is an example Makefile.custom for a PentiumPro Linux system: # Makefile.custom # Thomas Lockhart 1998-03-01 POSTGRESDIR= /opt/postgres/current CFLAGS+= -m486 # -g -O0 # documentation HSTYLE= /home/tgl/SGML/db118.d/docbook/html PSTYLE= /home/tgl/SGML/db118.d/docbook/print Locale Support Note: Written by Oleg Bartunov. See Oleg's web page for additional information on locale and Russian language support. While doing a project for a company in Moscow, Russia, I encountered the problem that postgresql had no support of national alphabets. After looking for possible workarounds I decided to develop support of locale myself. I'm not a C-programer but already had some experience with locale programming when I work with perl (debugging) and glimpse. After several days of digging through the Postgres source tree I made very minor corections to src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed! I did support only for LC_CTYPE and LC_COLLATE, but later LC_MONETARY was added by others. I got many messages from people about this patch so I decided to send it to developers and (to my surprise) it was incorporated into the Postgres distribution. People often complain that locale doesn't work for them. There are several common mistakes: o Didn't properly configure postgresql before compilation. You must run configure with --enable-locale option to enable locale support. Didn't setup environment correctly when starting postmaster. You must define environment variables LC_CTYPE and LC_COLLATE before running postmaster because backend gets information about locale from environment. I use following shell script (runpostgres): #!/bin/sh export LC_CTYPE=koi8-r export LC_COLLATE=koi8-r postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' and run it from rc.local as /bin/su - postgres -c "/home/postgres/runpostgres" o Broken locale support in OS (for example, locale support in libc under Linux several times has changed and this caused a lot of problems). Latest perl has also support of locale and if locale is broken perl -v will complain something like: 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist 8:18[mira]:~/WWW/postgres>perl -v perl: warning: Setting locale failed. perl: warning: Please check that your locale settings: LC_ALL = (unset), LC_CTYPE = "not_exist", LANG = (unset) are supported and installed on your system. perl: warning: Falling back to the standard locale ("C"). o Wrong location of locale files! Possible locations include: /usr/lib/locale (Linux, Solaris), /usr/share/locale (Linux), /usr/lib/nls/loc (DUX 4.0). Check man locale to find the correct location. Under Linux I did a symbolic link between /usr/lib/locale and /usr/share/locale to be sure that the next libc will not break my locale. What are the Benefits? You can use ~* and order by operators for strings contain characters from national alphabets. Non-english users definitely need that. If you won't use locale stuff just undefine the USE_LOCALE variable. What are the Drawbacks? There is one evident drawback of using locale - it's speed! So, use locale only if you really need it. Kerberos Authentication Kerberos is an industry-standard secure authentication system suitable for distributed computing over a public network. Availability The Kerberos authentication system is not distributed with Postgres. Versions of Kerberos are typically available as optional software from operating system vendors. In addition, a source code distribution may be obtained through MIT Project Athena. Note: You may wish to obtain the MIT version even if your vendor provides a version, since some vendor ports have been deliberately crippled or rendered non-interoperable with the MIT version. Users located outside the United States of America and Canada are warned that distribution of the actual encryption code in Kerberos is restricted by U. S. Government export regulations. Inquiries regarding your Kerberos should be directed to your vendor or MIT Project Athena. Note that FAQLs (Frequently-Asked Questions Lists) are periodically posted to the Kerberos mailing list (send mail to subscribe), and USENET news group. Installation Installation of Kerberos itself is covered in detail in the Kerberos Installation Notes . Make sure that the server key file (the srvtab or keytab) is somehow readable by the Postgres account. Postgres and its clients can be compiled to use either Version 4 or Version 5 of the MIT Kerberos protocols by setting the KRBVERS variable in the file src/Makefile.global to the appropriate value. You can also change the location where Postgres expects to find the associated libraries, header files and its own server key file. After compilation is complete, Postgres must be registered as a Kerberos service. See the Kerberos Operations Notes and related manual pages for more details on registering services. Operation After initial installation, Postgres should operate in all ways as a normal Kerberos service. For details on the use of authentication, see the PostgreSQL User's Guide reference sections for postmaster and psql. In the Kerberos Version 5 hooks, the following assumptions are made about user and service naming: o User principal names (anames) are assumed to contain the actual Unix/Postgres user name in the first component. o The Postgres service is assumed to be have two components, the service name and a hostname, canonicalized as in Version 4 (i.e., with all domain suffixes removed). Table 4-1. Kerberos Parameter Examples Param- Example eter user frew@S2K.ORG user aoki/HOST=miyu.S2K.Berkeley- .EDU@S2K.ORG host postgres_dbms/ucbvax@S2K.ORG Support for Version 4 will disappear sometime after the production release of Version 5 by MIT. Chapter 5. Release Notes Release 6.4 There are many new features and improvements in this release. Thanks to our developers and maintainers, nearly every aspect of the system has received some attention since the previous release. Here is a brief, incomplete summary: o Views and rules are now functional thanks to extensive new code in the rewrite rules system from Jan Wieck. He also wrote a chapter on it for the Programmer's Guide. o Jan also contributed a second procedural language, PL/pgSQL, to go with the original PL/pgTCL procedural language he contributed last release. o We have optional multiple-byte character set support from Tatsuo Iishi to complement our existing locale support. o Client/server communications has been cleaned up, with better support for asynchronous messages and interrupts thanks to Tom Lane. o The parser will now perform automatic type coersion to match arguments to available operators and functions, and to match columns and expressions with target columns. This uses a generic mechanism which supports the type extensibility features of Postgres. There is a new chapter in the User's Guide which covers this topic. o Three new data types have been added. Two types, inet and cidr, support various forms of IP network, subnet, and machine addressing. There is now an 8-byte integer type available on some platforms. See the chapter on data types in the User's Guide for details. A fourth type, serial, is now supported by the parser as an amalgam of the int4 type, a sequence, and a unique index. o Several more SQL92-compatible syntax features have been added, including INSERT DEFAULT VALUES o The automatic configuration and installation system has received some attention, and should be more robust for more platforms than it has ever been. Migration to v6.4 A dump/restore using pg_dump or pg_dumpall is required for those wishing to migrate data from any previous release of Postgres. Detailed Change List Bug Fixes --------- Fix for a tiny memory leak in PQsetdb/PQfinish(Bryan) Remove char2-16 data types, use char/varchar(Darren) Pqfn not handles a NOTICE message(Anders) Reduced busywaiting overhead for spinlocks with many backends (dg) Stuck spinlock detection (dg) Fix up "ISO-style" timespan decoding and encoding(Thomas) Fix problem with table drop after rollback of transaction(Vadim) Change error message and remove non-functional update message(Vadim) Fix for COPY array checking Fix for SELECT 1 UNION SELECT NULL Fix for buffer leaks in large object calls(Pascal) Change owner from oid to int4 type(Bruce) Fix a bug in the oracle compatibility functions btrim() ltrim() and rtrim() Fix for shared invalidation cache overflow(Massimo) Prevent file descriptor leaks in failed COPY's(Bruce) Fix memory leak in libpgtcl's pg_select(Constantin) Fix problems with username/passwords over 8 characters(Tom) Fix problems with handling of asynchronous NOTIFY in backend(Tom) Fix of many bad system table entries(Tom) Enhancements ------------ Upgrade ecpg and ecpglib,see src/interfaces/ecpc/ChangeLog(Michael) Show the index used in an EXPLAIN(Zeugswetter) EXPLAIN invokes rule system and shows plan(s) for rewritten queries(Jan) Multi-byte awareness of many data types and functions, via configure(Tatsuo) New configure --with-mb option(Tatsuo) New initdb --pgencoding option(Tatsuo) New createdb -E multibyte option(Tatsuo) Select version(); now returns PostgreSQL version(Jeroen) Libpq now allows asynchronous clients(Tom) Allow cancel from client of backend query(Tom) Psql now cancels query with Control-C(Tom) Libpq users need not issue dummy queries to get NOTIFY messages(Tom) NOTIFY now sends sender's PID, so you can tell whether it was your own(Tom) PGresult struct now includes associated error message, if any(Tom) Define "tz_hour" and "tz_minute" arguments to date_part()(Thomas) Add routines to convert between varchar and bpchar(Thomas) Add routines to allow sizing of varchar and bpchar into target columns(Thomas) Add bit flags to support timezonehour and minute in data retrieval(Thomas) Allow more variations on valid floating point numbers (e.g. ".1", "1e6")(Thomas) Fixes for unary minus parsing with leading spaces(Thomas) Implement TIMEZONE_HOUR, TIMEZONE_MINUTE per SQL92 specs(Thomas) Check for and properly ignore FOREIGN KEY column constraints(Thomas) Define USER as synonym for CURRENT_USER per SQL92 specs(Thomas) Enable HAVING clause but no fixes elsewhere yet. Make "char" type a synonym for "char(1)" (actually implemented as bpchar)(Thomas) Save string type if specified for DEFAULT clause handling(Thomas) Coerce operations involving different data types(Thomas) Allow some index use for columns of different types(Thomas) Add capabilities for automatic type conversion(Thomas) Cleanups for large objects, so file is truncated on open(Peter) Readline cleanups(Tom) Allow psql \f \ to make spaces as delimiter(Bruce) Pass pg_attribute.atttypmod to the frontend for column field lengths(Tom,Bruce) Msql compatibility library in /contrib(Aldrin) Remove the requirement that ORDER/GROUP BY clause identifiers be included in the target list(David) Convert columns to match columns in UNION clauses(Thomas) Remove fork()/exec() and only do fork()(Bruce) Jdbc cleanups(Peter) Show backend status on ps command line(only works on some platforms)(Bruce) Pg_hba.conf now has a sameuser option in the database field Make lo_unlink take oid param, not int4 New DISABLE_COMPLEX_MACRO for compilers that can't handle our macros(Bruce) Libpgtcl now handles NOTIFY as a Tcl event, need not send dummy queries(Tom) libpgtcl cleanups(Tom) Add -error option to libpgtcl's pg_result command(Tom) New locale patch, see docs/README/locale(Oleg) Fix for pg_dump so CONSTRAINT and CHECK syntax is correct(ccb) New contrib/lo code for large object orphan removal(Peter) New psql command "SET CLIENT_ENCODING TO 'encoding'" for multi-bytes feature, see /doc/README.mb(Tatsuo) /contrib/noupdate code to revoke update permission on a column Libpq can now be compiled on win32(Magnus) Add PQsetdbLogin() in libpq New 8-byte integer type, checked by configure for OS support(Thomas) Better support for quoted table/column names(Thomas) Surround table and column names with double-quotes in pg_dump(Thomas) PQreset() now works with passwords(Tom) Handle case of GROUP BY target list column number out of range(David) Allow UNION in subselects Add auto-size to screen to \d? commands(Bruce) Use UNION to show all \d? results in one query(Bruce) Add \d? field search feature(Bruce) Pg_dump issues fewer \connect requests(Tom) Make pg_dump -z flag work better, document it in manual page(Tom) Add HAVING clause with full support for subselects and unions(Stephan) Full text indexing routines in contrib/fulltextindex(Maarten) Transaction ids now stored in shared memory(Vadim) New PGCLIENTENCODING when issuing COPY command(Tatsuo) Support for SQL92 syntax "SET NAMES"(Tatsuo) Support for LATIN2-5(Tatsuo) Add UNICODE regression test case(Tatsuo) Lock manager cleanup, new locking modes for LLL(Vadim) Allow index use with OR clauses(Bruce) Allows "SELECT NULL ORDER BY 1;" Explain VERBOSE prints the plan, and now pretty-prints the plan to the postmaster log file(Bruce) Add Indices display to \d command(Bruce) Allow GROUP BY on functions(David) New pg_class.relkind for large objects(Bruce) New way to send libpq NOTICE messages to a different location(Tom) New \w write command to psql(Bruce) New /contrib/findoidjoins scans oid columns to find join relationships(Bruce) Allow binary-compatible indices to be considered when checking for valid indices for restriction clauses containing a constant(Thomas) New ISBN/ISSN code in /contrib/isbn_issn Allow NOT LIKE, IN, NOT IN, BETWEEN, and NOT BETWEEN constraint(Thomas) New rewrite system fixes many problems with rules and views(Jan) * Rules on relations work * Event qualifications on insert/update/delete work * New OLD variable to reference CURRENT, CURRENT will be remove in future * Update rules can reference NEW and OLD in rule qualifications/actions * Insert/update/delete rules on views work * Multiple rule actions are now supported, surrounded by parentheses * Regular users can create views/rules on tables they have RULE permits * Rules and views inherit the permissions on the creator * No rules at the column level * No UPDATE NEW/OLD rules * New pg_tables, pg_indexes, pg_rules and pg_views system views * Only a single action on SELECT rules * Total rewrite overhaul, perhaps for 6.5 * handle subselects * handle aggregates on views * handle insert into select from view works System indexes are now multi-key(Bruce) Oidint2, oidint4, and oidname types are removed(Bruce) Use system cache for more system table lookups(Bruce) New backend programming language PL/pgSQL in backend/pl(Jan) New SERIAL data type, auto-creates sequence/index(Thomas) Enable assert checking without a recompile(Massimo) User lock enhancements(Massimo) New setval() command to set sequence value(Massimo) Auto-remove unix socket file on startup if no postmaster running(Massimo) Conditional trace package(Massimo) New UNLISTEN command(Massimo) Psql and libpq now compile under win32 using win32.mak(Magnus) Lo_read no longer stores trailing NULL(Bruce) Identifiers are now truncated to 31 characters internally(Bruce) Createuser options now availble on the command line Code for 64-bit integer supported added, configure tested, int8 type(Thomas) Prevent file descriptor leaf from failed COPY(Bruce) New pg_upgrade command(Bruce) Updated /contrib directories(Massimo) New CREATE TABLE DEFAULT VALUES statement available(Thomas) New INSERT INTO TABLE DEFAULT VALUES statement available(Thomas) New DECLARE and FETCH feature(Thomas) libpq's internal structures now not exported(Tom) Allow up to 8 key indexes(Bruce) Remove ARCHIVE keyword, that is no longer used(Thomas) pg_dump -n flag to supress quotes around indentifiers disable system columns for views(Jan) new INET and CIDR types for network addresses(TomH, Paul) no more double quotes in psql output pg_dump now dumps views(Terry) new SET QUERY_LIMIT(Tatsuo,Jan) Source Tree Changes ------------------- /contrib cleanup(Jun) Inline some small functions called for every row(Bruce) Alpha/linux fixes Hp/UX cleanups(Tom) Multi-byte regression tests(Soonmyung.) Remove --disabled options from configure Define PGDOC to use POSTGRESDIR by default Make regression optional Remove extra braces code to pgindent(Bruce) Add bsdi shared library support(Bruce) New --without-CXX support configure option(Brook) New FAQ_CVS Update backend flowchart in tools/backend(Bruce) Change atttypmod from int16 to int32(Bruce, Tom) Getrusage() fix for platforms that do not have it(Tom) Add PQconnectdb, PGUSER, PGPASSWORD to libpq man page NS32K platform fixes(Phil Nelson, John Buller) Sco 7/UnixWare 2.x fixes(Billy,others) Sparc/Solaris 2.5 fixes(Ryan) Pgbuiltin.3 is obsolete, move to doc files(Thomas) Even more documention(Thomas) Nextstep support(Jacek) Aix support(David) pginterface manual page(Bruce) shared libraries all have version numbers merged all OS-specific shared library defines into one file smarter TCL/TK configuration checking(Billy) smarter perl configuration(Brook) configure uses supplied install-sh if no install script found(Tom) new Makefile.shlib for shared library configuration(Tom)