From 8dd88a40385e9c326a65be931c0f5b3fb85cbc6b Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Sat, 31 Oct 1998 09:31:58 +0000 Subject: [PATCH] Generate from installation.sgml -> installation.rtf -> ApplixWare -> INSTALL with some cleanup in vi. --- INSTALL | 2240 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 1546 insertions(+), 694 deletions(-) diff --git a/INSTALL b/INSTALL index 9371c9f1c5..d6f756f82f 100644 --- a/INSTALL +++ b/INSTALL @@ -1,697 +1,1549 @@ -POSTGRESQL INSTALLATION INSTRUCTIONS -Copyright (c) 1997 Regents of the University of California - -This is file /usr/src/pgsql/INSTALL. It contains notes on how to install -PostgreSQL v6.4. Up to date information on PostgreSQL may be found at -http://www.postgresql.org. - -PostgreSQL is an RDBMS database server. It is not completely ANSI SQL -compliant, but with each release it gets closer. - -PostgreSQL, formerly called Postgres95, is a derivative of Postgres 4.2 -(the last release of the UC Berkeley research project). For copyright -terms for PostgreSQL, please see the file named COPYRIGHT. This version -was developed by a team of developers on the Postgres developers mailing -list. Version 1 (through 1.01) was developed by Jolly Chen and Andrew Yu. - -The installation notes below assume the following (except where noted): - - Commands are Unix-compatible. See note below. - - Defaults are used except where noted. - - User postgres is the Postgres superuser. - - The source path is /usr/src/pgsql (other paths are possible). - - The runtime path is /usr/local/pgsql (other paths are possible). - -Commands were tested on RedHat Linux version 4.0 using the bash shell. -Except where noted, they will probably work on most systems. Commands -like ps and tar vary wildly on what options you should use on each -platform. USE COMMON SENSE before typing in these commands. - -Our Makefiles require GNU make (called gmake in this document) and -also assume that "install" accepts BSD options. The INSTALL -variable in the Makefiles is set to the BSD-compatible version of -install. On some systems, you will have to find a BSD-compatible -install command (eg. bsdinst, which comes with the MIT X Window System -distribution) - - -REQUIREMENTS TO RUN POSTGRESQL ------------------------------- - -PostgreSQL has been tested on the following platforms: - - aix IBM on AIX 3.2.5 or 4.x - alpha DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0 - BSD44_derived OSs derived from 4.4-lite BSD (NetBSD, FreeBSD) - bsdi BSD/OS 2.0, 2.01, 2.1, 3.0 - dgux DG/UX 5.4R4.11 - hpux HP PA-RISC on HP-UX 9.0, 10 - i386_solaris i386 Solaris - irix5 SGI MIPS on IRIX 5.3 - linux Intel x86 on Linux 2.0 and Linux ELF - SPARC on Linux ELF - PPC on Linux ELF - (For non-ELF Linux, see LINUX_ELF below). - sco SCO 3.2v5 - sparc_solaris SUN SPARC on Solaris 2.4, 2.5, 2.5.1 - sunos4 SUN SPARC on SunOS 4.1.3 - svr4 Intel x86 on Intel SVR4 and MIPS - ultrix4 DEC MIPS on Ultrix 4.4 - -PostgreSQL has known problems/bugs on the following platforms: - - nextstep Motorola MC68K or Intel x86 on NeXTSTEP 3.2 - -PostgreSQL is also known to work on a number of other platforms that the -authors have not personally tested. - -You should have at least 8 MB of memory and at least 45 MB of disk space -to hold the source, binaries, and user databases. After installation -you may reduce this to about 3 Mbytes plus space for user databases. - -To those upgrading from PostgreSQL 6.3.*: ----------------------------------------- - -A dump/restore is required for those running 6.3.*, or you can use the -new pg_upgrade command to upgrade your data files without -dumping/loading them. See the new pg_upgrade manual page. - -To those doing a fresh install or upgrading from previous releases of -PostgreSQL: ----------------------------------------------- - - 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 PostgreSQL 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 account postgres if it does not already exist. - - 3) Log into account postgres. - - 3a) Check that you have sufficient disk space. You will need about - 17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql - (excluding your database) and 1 Mbyte for an empty database. - For the regression tests, you will need an extra 20 Mbytes. - 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 5 MB - 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 command "df -k". - - 4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-6.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. 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. - - To install it, type the following: - cd - gunzip -c flex-2.5.4.tar.gz | tar xvf - - cd flex-2.5.4 - configure --prefix=/usr - make - make check - # You must be root when typing the next line. - make install - cd - 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 link - /usr/bin/flex++ which points to flex. - - 6) 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. Type (with the gunzip line and the following line typed as one - line): - cd - gunzip -c postgresql-6.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 > 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, 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, use "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 appropriate files pgsql/migration/*. - - 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 "???" replaced by the process id for process - "postmaster". (Do not use the id for process "grep postmaster".) Type - kill ??? - with "???" modified as indicated. - - 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; be consistant with your configuration - in step (11). - 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-6.4.tar.gz | tar xvf - - - 11) Configure the source code for your system. It is this step at which - you can specify your actual source path and installation paths for - the build process (see the --prefix option below). Type - cd /usr/src/pgsql/src - ./configure - - The configure program will list the template files available and - ask you to choose one. A lot of times, an appropriate template - file is chosen for you, and you can just press Enter to accept the - default. If the default is not appropriate, then type in the - appropriate template file and press Enter. (If you do this, then - send email to scrappy@hub.org stating the output of the program - './config.guess' and what the template file should be.) - - Once you have entered the template file, you will be asked a - number of questions about your particular configuration. These - can be skipped by adding parameters to the configure command above. - The following parameters can be tagged onto the end of the configure - command: - - --prefix=BASEDIR Selects a different base directory for the - installation of the PostgreSQL configuration. - The default is /usr/local/pgsql. - - --enable-hba Enables Host Based Authentication (DEFAULT) - - --enable-locale Enables USE_LOCALE - - --enable-cassert Enables ASSERT_CHECKING - - --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. - (If the configure script cannot find the - specified template file, it will ask you for - one). - - --with-pgport=PORT Sets the port that the postmaster process - listens for incoming connections on. The - default for this is port 5432. - - --with-tcl Enables programs requiring Tcl/Tk and X11, - including pgtclsh and libpgtcl. - - --with-perl Enables the perl interface. - - --with-includes=DIRS - Include DIRS in list of directories searched - for header files. (Typical use will need - --with-includes=/usr/local/include) - - --with-libs=DIRS - --with-libraries=DIRS - Include DIRS in list of directories searched - for archive libraries. (Typical use will need - --with-libraries=/usr/local/lib) - - --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. - - As an example, here is the configure script I use on a Sparc - Solaris 2.5 system with /opt/postgres being the install base. - - % ./configure --prefix=/opt/postgres - --with-template=sparc_solaris-gcc --with-pgport=5432 - --enable-hba - - Of course, in a real shell, you would type these three lines all - on the same line. - - 12) 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.) - - If your computer does not have gmake (GNU make) then try running - make instead throughout the rest of these notes. - - Please note that 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 an error 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. - - 13) 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. - - 14) If necessary, tell UNIX how to find your shared libraries. You can - do ONE of the following, preferably the first: - - a) As root, edit file /etc/ld.so.conf. Add 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. - - 15) If it has not already been done, then prepare account postgres - for using PostgreSQL. Any account that will use PostgreSQL must - be similarily prepared. (The following instructions are for a - bash shell. Adapt accordingly for other shells.) - - Add the following lines to your login 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 - - 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 - - 16) Create the database. DO NOT DO THE FOLLOWING AS ROOT! This would - be a major security hole. Type - initdb - - 17) 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 finsihed. - - If you are upgrading, you can NOT copy file pg_hba.conf from your - old database on top of the one in your new database. You will - have to re-do your changes. - - - 18) If you wish to skip the regression tests then skip to step 21. - - The file /usr/src/pgsql/src/test/regress/README has detailed - instructions for running and interpreting the regression tests. - A short version follows here: - - Start the postmaster in preparation for the regression tests. First, - set the timezone for Berkeley, California. On some systems you may do - this by setting environment variable TZ. I.e., using bash, type - export TZ=PST8PDT - - Now start the postmaster daemon running in the background by typing - cd - nohup postmaster > regress.log 2>&1 & - - Run postmaster from your Postgres super user account (typically - account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT. - - 19) Run the regression tests. Type - - cd /usr/src/pgsql/src/test/regress - gmake clean - gmake all runtest - - You do not need to type "gmake clean" if this is the first time you - are running the tests. - - You should get on the screen (and also written to file ./regress.out) - a series of statements stating which tests passed and which tests - failed. Please note that it can be normal for some of the tests to - "fail". For the failed tests, use diff to compare the files in - directories ./results and ./expected. If float8 failed, type - something like: - cd /usr/src/pgsql/src/test/regress - diff -w expected/float8.out results - - "Failed" tests may have failed due to slightly different error messages, - output formatting, failure to set the timezone correctly for your - platform, etc. "Failures" of this type do not indicate a problem with - PostgreSQL. - - For a i686/Linux-ELF platform, no tests failed since this is the - v6.4 regression testing reference platform. - - For the SPARC/Linux-ELF platform, using the 970525 beta version of - PostgreSQL v6.2 the following tests "failed": - float8 and geometry "failed" due to minor precision differences in - floating point numbers. select_views produces massively different output, - but the differences are due to minor floating point differences. - - Conclusion? If you do see failures, try to understand the nature of - the differences and then decide if those differences will affect your - intended use of PostgreSQL. However, keep in mind that this is likely - to be the most solid release of PostgreSQL to date, incorporating many - bug fixes from v6.2.1, and that previous versions of PostgreSQL have been - in use successfully for some time now. - - After running the tests, type - destroydb regression - cd /usr/src/pgsql/src/test/regress - gmake clean - - 20) Stop the postmaster as described in step 7. Then restore the - timezone to it's normal setting. If you changed the timezone by - modifying environment variable TZ then one way to do this is to - log out of, then back into, account postgres. - - 21) Start the postmaster daemon running. Type - cd - nohup postmaster > server.log 2>&1 & - Run postmaster from your Postgres super user account (typically - account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT. - - 22) If you haven't already done so, this would be a good time to modify - your computer so that it will automatically start postmaster whenever - you boot your computer. - - Here are some suggestions on how to do this, contributed by various - users. - - Whatever you do, postmaster must be run by user 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. - - a) 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" - - b) 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 postgres -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. Note: Unlike most - other examples, this one has been tested. - - c) In RedHat v4.0 Linux edit file /etc/inittab to contain the - following 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" >/dev/null - (The author of this example says this example will revive the - postmaster if it dies, but he doesn't know if there are other side - effects.) - - d) The contrib/linux area of the PostgreSQL distribution has an example - init.d script compatible with and tested using recent RedHat packages. - - 22a) If you haven't already done so, this would be a good time to modify - your computer to do regular maintainence. The following should be - done at regular intervals: - - a) Run the SQL command vacuum. This will clean up your database. - b) Back up your system. (You should probably keep the last few - backups on hand.) Ideally, no one else should be using the - system at the time. - - Ideally, the above tasks should be done by a shell script that is - run nightly or weekly by cron. Look at the man page for crontab - for a starting point on how to do this. (If you do it, please - e-mail us a copy of your shell script. We would like to set up - our own systems to do this too.) - - 23) If you are upgrading an existing system then reload your old database. - Type - cd - psql -e template1 < db.out - - If your pre-v6.2 database uses either path or polygon geometric data types, - then you will need to upgrade any columns containing those types. To - do so, type (from within psql) - update YourTable set PathCol = UpgradePath(PathCol); - update YourTable set PolyCol = UpgradePoly(PolyCol); - ... - vacuum; - - UpgradePath() checks to see that a path value is consistant with the - old syntax, and will not update a column which fails that examination. - UpgradePoly() cannot verify that a polygon is in fact from an old - syntax, but RevertPoly() is provided to reverse the effects of a - mis-applied upgrade. - - 24) If you are a new user, you may wish to play with Postgres as described - below. - - 25) Clean up after yourself. Type - rm -rf /usr/src/pgsql_6_0 - rm -rf /usr/local/pgsql_6_0 - # Also delete old database directory tree if it is not in - # /usr/local/pgsql_6_0/data - rm ~/postgresql-6.4.tar.gz - - 26) You will probably want to print out the documentation. Here is how - you might do it if you have Ghostscript on your system and are - writing to a laserjet printer. - alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' - export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts - # Print out the man pages. - man -a -t /usr/local/pgsql/man/*/* > manpage.ps - gshp -sOUTPUTFILE=manpage.hp manpage.ps - rm manpage.ps - lpr -l -s -r manpage.hp - # Print out the Postgres95 User Manual, version 1.0, - # Sept. 5, 1996. - cd /usr/src/pgsql/doc - gshp -sOUTPUTFILE=userguide.hp userguide.ps - lpr -l -s -r userguide.hp - - If you are a developer, you will probably want to also print out - the Postgres Implemention Guide, version 1.0, October 1, 1995. - This is a WWW document located at - http://www.postgresql.org/docs/impguide. - - 27) The Postgres team wants to keep PostgreSQL working on all of the - supported platforms. We therefore ask you to let us know if you did - or did not get PostgreSQL to work on you system. Please send a - mail message to pgsql-ports@postgresql.org telling us the following: - - The version of PostgreSQL (6.4, 6.3.2, beta 970703, etc.). - - Your operating system (i.e. RedHat v4.0 Linux v2.0.26). - - Your hardware (SPARC, i486, etc.). - - Did you compile, install and run the regression tests cleanly? - If not, what source code did you change (i.e. patches you - applied, changes you made, etc.), what tests failed, etc. - It is normal to get many warning when you compile. You do - not need to report these. - - 28) Now create, access and manipulate databases as desired. Write client - programs to access the database server. In other words, ENJOY! - - -PLAYING WITH POSTGRESQL ------------------------ - -After PostgreSQL is installed, a database system is created, a postmaster -daemon is running, and the regression tests have passed, you'll want to -see PostgreSQL do something. That's easy. Invoke the interactive interface -to PostgreSQL, psql, and start typing SQL: - - $ psql template1 - -(psql has to open a particular database, but at this point the only one -that exists is the template1 database, which always exists. We will connect -to it only long enough to create another one and switch to it). - -The response from psql is: - - type \? for help on slash commands - type \q to quit - type \g or terminate with semicolon to execute query -You are currently connected to the database: template1 - -template1=> - -Create the database foo: - -template1=> CREATE DATABASE FOO; -INSERT 773248 - -(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.) - -template1=> \c foo -closing connection to database: template1 -connecting to new database: foo - -(\ commands aren't SQL, so no semicolon. Use \? to see all the \ commands.) - -foo=> CREATE TABLE bar (column1 int4, column2 char16); -CREATE - -foo=> \d bar - -... - -You get the idea. - - -QUESTIONS? BUGS? FEEDBACK? ----------------------------- - -First, read the files in directory /usr/src/pgsql/doc. The FAQ in -this directory may be particularly useful. - -If PostgreSQL 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. - -Mail questions to pgsql-questions@postgresql.org. For more information -on the various mailing lists, see http://www.postgresql.org under mailing -lists. - - ----------------------------------------------------------------------- - -Porting Notes (these notes may be out of date): -------------- - -Ultrix4.x: - 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: - A linux-2.0.30/libc-5.3.12/RedHat-4.2 running on a dual processor - i686 is the regression testing reference machine. - The linux-elf port installs cleanly. If you are using an - i486 processor or higher, you can edit template/linux-elf - to include "-m486" as a compiler option. configure does not - detect that sigsetjmp() is available, but you can edit - include/config.h after running configure and before running - make to include "#define HAVE_SIGSETJMP 1". Note that I have - not seen any difference in PostgreSQL behavior either way. - (Thomas G. Lockhart - 97/10/14) - 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 - 5/11/95) - -BSD/OS: - For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library. - -NeXT: - The NeXT port 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 PostgreSQL for NEXTSTEP will be made available to - the general public. Contact Info@RnA.nl for information. +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 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. Install the man page documentation. Type + $ cd /usr/src/pgsql/doc + $ gmake man + + 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) -- 2.40.0