diff options
| author | Peter Eisentraut <peter_e@gmx.net> | 2000-01-20 21:51:09 +0000 |
|---|---|---|
| committer | Peter Eisentraut <peter_e@gmx.net> | 2000-01-20 21:51:09 +0000 |
| commit | 13f88750178ced2b948a3d2b8370f5231534577d (patch) | |
| tree | e9f1abb294831f1bea568ad35ba0b0817031c445 | |
| parent | a959e3f7c04d2f8cca3e7895c3bb460d40de2280 (diff) | |
| download | postgresql-13f88750178ced2b948a3d2b8370f5231534577d.tar.gz postgresql-13f88750178ced2b948a3d2b8370f5231534577d.zip | |
Added new pg_id to fix initdb problems
New INSTALL file
Fixed a copyright notice
| -rw-r--r-- | INSTALL | 1979 | ||||
| -rw-r--r-- | doc/src/sgml/install.sgml | 1313 | ||||
| -rw-r--r-- | doc/src/sgml/ref/initdb.sgml | 17 | ||||
| -rw-r--r-- | src/GNUmakefile.in | 7 | ||||
| -rw-r--r-- | src/backend/access/heap/tuptoaster.c | 4 | ||||
| -rw-r--r-- | src/bin/Makefile | 4 | ||||
| -rw-r--r-- | src/bin/initdb/initdb.sh | 65 | ||||
| -rw-r--r-- | src/bin/pg_id/Makefile | 33 | ||||
| -rw-r--r-- | src/bin/pg_id/pg_id.c | 91 | ||||
| -rw-r--r-- | src/bin/psql/copy.c | 5 | ||||
| -rwxr-xr-x | src/mkinstalldirs | 36 |
11 files changed, 835 insertions, 2719 deletions
@@ -1,1647 +1,344 @@ + Installation instructions for PostgreSQL 7.0.0. + +Commands were tested on RedHat Linux version 5.2 using the bash 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. + +If you haven't gotten the PostgreSQL distribution, get it from +ftp.postgresql.org, then unpack it: + +$ gunzip postgresql-7.0.0.tar.gz +$ tar -xf postgresql-7.0.0.tar +$ mv postgresql-7.0.0 /usr/src + +Again, these commands might differ on your system. + +Before you start + +Building PostgreSQL requires GNU make. It will not work with other make +programs. On GNU/Linux systems GNU make is the default tool, on other +systems you may find that GNU make is installed under the name "gmake". We +will use that name from now on to indicate GNU make, no matter what name it +has on your system. To test for GNU make enter + +$ gmake --version + +If you need to get GNU make, you can find it at ftp://ftp.gnu.org. + +Up to date information on supported platforms is at +http://www.postgresql.org/docs/admin/ports.htm. In general, most +Unix-compatible platforms with modern libraries should be able to run +PostgreSQL. In the doc subdirectory of the distribution are several +platform-specific FAQ and README documents you might wish to consult if you +are having trouble. + +Although the minimum required memory for running PostgreSQL can be as little +as 8MB, there are noticable speed improvements when expanding memory up to +96MB or beyond. The rule is you can never have too much memory. + +Check that you have sufficient disk space. You will need about 30 Mbytes for +the source tree during compilation and about 5 Mbytes for the installation +directory. An empty database takes about 1 Mbyte, otherwise they take about +five times the amount of space that a flat text file with the same data +would take. If you run the regression tests you will temporarily need an +extra 20MB. + +To check for disk space, use + +$ df -k + +Considering today's prices for hard disks, getting a large and fast hard +disk should probably be in your plans before putting a database into +production use. -PostgreSQL Installation Guide -by The PostgreSQL Development Team - -PostgreSQL is © 1998-9 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 - 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.5.1 - Migration to v6.5.1 - Detailed Change List - Release 6.5 - Migration to v6.5 - Multi-Version Concurrency Control - Detailed Change List - -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.5.1 of Postgres. The - Postgres developer community has compiled and tested - Postgres on a number of platforms. Check the web site - (http://www.postgresql.org/docs/admin/ports.htm) for - the latest information. - -Currently Supported Platforms - - At the time of publication, the following platforms - have been tested: - - Table 2-1. Supported Platforms - OS Processor Version Reported Remarks - AIX 4.3.2 RS6000 v6.5 1999-05-26 (Andreas Zeugswetter - (mailto:Andreas.Zeugswetter@telecom.at)) - BSDI x86 v6.5 1999-05-25 (Bruce Momjian - (mailto:maillist@candle.pha.pa.us) - FreeBSD x86 v6.5 1999-05-25 (Tatsuo Ishii - 2.2.x-4.0 (mailto:t-ishii@sra.co.jp), - Marc Fournier - (mailto:scrappy@hub.org)) - DGUX m88k v6.3 1998-03-01 v6.4 probably OK. - 5.4R4.11 Needs new maintainer. - (Brian E Gallew - (mailto:geek+@cmu.edu)) - Digital Alpha v6.4 1998-10-29 Minor patchable problems - Unix 4.0 (Pedro J. Lobo - (mailto:pjlobo@euitt.upm.es)) - HPUX PA-RISC v6.4 1998-10-25 Both 9.0x and 10.20 - (Tom Lane (mailto:tgl@sss.pgh.pa.us), - Stan Brown (mailto:stanb@awod.com)) - IRIX 6.5 MIPS v6.4 1998-12-29 IRIX 5.x is different - (Mark Dalphin (mdalphin@amgen.com)) - linux Alpha v6.3.2 1998-04-16 Mostly successful. Needs - 2.0.x work for v6.4. - (Ryan Kirkpatrick - (mailto:rkirkpat@nag.cs.colorado.edu)) - linux x86 v6.4 1998-10-27 (Thomas Lockhart - 2.0.x/libc5 (mailto:lockhart@alumni.caltech.edu)) - linux x86 v6.4 1999-05-24 (Thomas Lockhart - 2.0.x/glibc2 (mailto:lockhart@alumni.caltech.edu)) - linux MIPS v6.4 1998-12-16 Cobalt Qube (Tatsuo Ishii - 2.0.x (mailto:t-ishii@sra.co.jp)) - linux Sparc v6.4 1998-10-25 (Tom Szybist - 2.0.x (mailto:szybist@boxhill.com)) - linuxPPC PPC603e v6.4 1998-10-26 Powerbook 2400c - 2.1.24 (Tatsuo Ishii - (mailto:t-ishii@sra.co.jp)) - mklinux PPC750 v6.4 1998-09-16 PowerMac 7600 - DR3 (Tatsuo Ishii - (mailto:t-ishii@sra.co.jp)) - NetBSD arm32 v6.5 1999-04-14 (Andrew McMurry - (mailto:a.mcmurry1@physics.oxford.ac.uk)) - NetBSD/i3- x86 v6.4 1998-10-25 (Brook Milligan - 86 1.3.2 (mailto:brook@trillium.NMSU.Edu)) - NetBSD m68k v6.4.2 1998-12-28 Mac SE/30 (Mr. Mutsuki - Nakajima, Tatsuo Ishii - (mailto:t-ishii@sra.co.jp)) - NetBSD- NS32532 v6.4 1998-10-27 small problems - current in date/time math (Jon Buller - (mailto:jonb@metronet.com)) - NetBSD/sp- Sparc v6.4 1998-10-27 (Tom I Helbekkmo - arc 1.3H (mailto:tih@hamartun.priv.no)) - NetBSD 1.3 VAX v6.3 1998-03-01 (Tom I Helbekkmo - (mailto:tih@hamartun.priv.no)) - SCO x86 v6.5 1999-05-25 (Andrew Merrill - OpenServer 5 (mailto:andrew@compclass.com)) - SCO x86 v6.5 1999-05-25 (Andrew Merrill - UnixWare 7 (mailto:andrew@compclass.com)) - Solaris x86 v6.4 1998-10-28 (Marc Fournier - (mailto:scrappy@hub.org)) - Solaris Sparc v6.4 1998-10-28 (Tom Szybist - 2.6-2.7 (mailto:szybist@boxhill.com), - Frank Ridderbusch - (mailto:ridderbusch.pad@sni.de)) - SunOS Sparc v6.3 1998-03-01 Patches submitted - 4.1.4 (Tatsuo Ishii - (mailto:t-ishii@sra.co.jp)) - SVR4 MIPS v6.4 1998-10-28 No 64-bit int compiler - support (Frank Ridderbusch - (mailto:ridderbusch.pad@sni.de)) - Windows x86 v6.4 1999-01-06 Client-side libraries - or ODBC/JDBC. No server yet. - (Magnus Hagander - (mha@sollentuna.net) - Windows NT x86 v6.5 1999-05-26 Working with the Cygwin - library. (Daniel Horak - (mailto:Dan.Horak@email.cz)) - - - - Platforms listed for v6.3.x and v6.4.x should also - work with v6.5.1, but we did not receive explicit - confirmation of such at the time this list was - compiled. - - Note: For Windows NT, the server-side port of - Postgres has recently been accomplished. The - Cygnus library is required to compile it. - -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 - NextStep x86 v6.x 1998-03-01 Client-only support; - v1.0.9 worked with patches - (David Wetzel - (mailto:dave@turbocat.de)) - SVR4 4.4 m88k v6.2.1 1998-03-01 Confirmed - with patching; - v6.4.x will need TAS - spinlock code (Doug - Winterburn - (mailto:dlw@seavme.xroads.com)) - Ultrix MIPS,VAX? v6.x 1998-03-01 No recent reports; - obsolete? - - -Chapter 3. Installation - - Complete installation instructions for Postgres - v6.5.1. - - Before installing Postgres, you may wish to visit - www.postgresql.org (http://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 5.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 - (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 - 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.5.1.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 from 6.5, you - do not need to dump/reload or initdb. Simply - compile the source code, stop the postmaster, do a - "make install", and restart the postmaster. - If you are upgrading from 6.4.* or earlier, - 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 > 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.5.1.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 (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 consistent 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 - gmake 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.5.1.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 (mailto: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 for the - installation of the - Postgres configuration. - 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. 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. - Remember, ?gmake? may be called ?make? on your system. - 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 - $ gmake 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. - 14. 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. Remember, ?gmake? may - be called ?make? on your system. - 15. 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. - 16. 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 - - - 17. 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 fail 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 - - - 18. 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 - 19. 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. - 20. 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 - $ nohup postmaster -i > pgserver.log 2>&1 & - 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 - 21. 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 - </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.) - 22. Run the regression tests. The file - /usr/src/pgsql/src/test/regress/README has - detailed instructions for running and interpreting - the regression tests. A short version follows - here: - a. 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 tests to "fail" on some - platforms. The script says a test has failed - if there is any difference at all between the - actual output of the test and the expected - output. Thus, tests may "fail" due to minor - differences in wording of error messages, - small differences in floating-point roundoff, - etc, between your system and the regression - test reference platform. "Failures" of this - type do not indicate a problem with Postgres. - The file ./regression.diffs contains the - textual differences between the actual test - output on your machine and the "expected" - output (which is simply what the reference - system produced). You should carefully - examine each difference listed to see whether - it appears to be a significant issue. - For example, - o For a i686/Linux-ELF platform, no tests - failed since this is the v6.5 regression - testing reference platform. - Even if a test result clearly indicates a - real failure, it may be a localized problem - that will not affect you. An example is that - the int8 test will fail, producing obviously - incorrect output, if your machine and C - compiler do not provide a 64-bit integer data - type (or if they do but configure didn't - discover it). This is not something to worry - about unless you need to store 64-bit - integers. - 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 Postgres. The regression - tests are a helpful tool, but they may - require some study to be useful. - After running the regression tests, type - $ destroydb regression - $ cd /usr/src/pgsql/src/test/regress - $ gmake clean - to recover the disk space used for the - tests. (You may want to save the - regression.diffs file in another place before - doing this.) - 23. 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: - - Minimal Backup Procedure - 1. Run the SQL command VACUUM. This will clean - up your database. - 2. Back up your system. (You should probably - keep the last few backups on hand.) Preferably, - 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.) - 24. If you are upgrading an existing system then - reinstall 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 FirstTable SET PathCol = - UpgradePath(PathCol); - UPDATE SecondTable SET PathCol = - UpgradePath(PathCol); - ... - 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. - 25. If you are a new user, you may wish to play - with Postgres as described below. - 26. Clean up after yourself. Type - $ rm -rf /usr/src/pgsql_6_5 - $ rm -rf /usr/local/pgsql_6_5 - # Also delete old database directory tree if it is - not in - # /usr/local/pgsql_6_5/data - $ rm ~/postgresql-v6.5.1.tar.gz - 27. You will probably want to print out the - documentation. If you have a Postscript printer, - or have your machine already set up to accept - Postscript files using a print filter, then to - print the User's Guide simply type - $ cd /usr/local/pgsql/doc - $ gunzip user.ps.tz | lpr - Here is how you might do it if you have - Ghostscript on your system and are writing to a - laserjet printer. - $ alias gshp='gs -sDEVICE=laserjet -r300 - -dNOPAUSE' - $ export - GS_LIB=/usr/share/ghostscript:/usr/share/ghostscr- - ipt/fonts - $ gunzip user.ps.gz - $ gshp -sOUTPUTFILE=user.hp user.ps - $ gzip user.ps - $ lpr -l -s -r manpage.hp - 28. The Postgres team wants to keep Postgres - working on all of the supported platforms. We - therefore ask you to let us know if you did or did - not get Postgres to work on you system. Please - send a mail message to pgsql-ports@postgresql.org - (mailto:pgsql-ports@postgresql.org) telling us the - following: - o The version of Postgres (v6.5.1, 6.5, beta - 990318, etc.). - o Your operating system (i.e. RedHat v5.2 Linux - v2.0.36). - o Your hardware (SPARC, i486, etc.). - o 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. - 29. Now create, access and manipulate databases - as desired. Write client programs to access the - database server. In other words, enjoy! - -Playing with Postgres - - After Postgres is installed, a database system is - created, a postmaster daemon is running, and the - regression tests have passed, you'll want to see - Postgres do something. That's easy. Invoke the - interactive interface to Postgres, psql: - - % 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: - - Welcome to the POSTGRESQL interactive sql monitor: - Please read the file COPYRIGHT for copyright terms - of POSTGRESQL - - 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; - 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 - - Check for any platform-specific FAQs in the doc/ - directory of the source distribution. - -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-maxbackends=n set default maximum number of - server processes - --with-tcl build Tcl interfaces and - pgtclsh - --with-tclconfig=tcldir tclConfig.sh and - tkConfig.sh are in DIR - --with-perl build Perl interface - --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 prevent building C++ code - - - - Some systems may have trouble building a specific - feature of Postgres. For example, systems with a - damaged C++ compiler may need to specify - --without-CXX to instruct the build procedure to skip - construction of libpq++. - -Parameters for Building (make) - - Many installation-related parameters can be set in - the building stage of Postgres installation. - In most cases, these parameters should be placed in - a file, Makefile.custom, intended just for that - purpose. The default distribution does not contain - this optional file, so you will create it using a - text editor of your choice. When upgrading - installations, you can simply copy your old - Makefile.custom to the new installation before doing - the build. - - 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 - USE_TCL= true - TCL_LIB= -ltcl - X_LIBS= -L/usr/X11/lib - TK_LIB= -ltk - - # documentation - - HSTYLE= /home/tgl/SGML/db118.d/docbook/html - PSTYLE= /home/tgl/SGML/db118.d/docbook/print - - - - -Locale Support - - - - Note: Written by Oleg Bartunov. See Oleg's web - page (http://www.sai.msu.su/~megera/postgres/) for - additional information on locale and Russian - language support. - - While doing a project for a company in Moscow, - Russia, I encountered the problem that postgresql had - no support of national alphabets. After looking for - possible workarounds I decided to develop support of - locale myself. I'm not a C-programer but already had - some experience with locale programming when I work - with perl (debugging) and glimpse. After several days - of digging through the Postgres source tree I made - very minor corections to - src/backend/utils/adt/varlena.c and - src/backend/main/main.c and got what I needed! I did - support only for LC_CTYPE and LC_COLLATE, but later - LC_MONETARY was added by others. I got many messages - from people about this patch so I decided to send it - to developers and (to my surprise) it was - incorporated into the Postgres distribution. - People often complain that locale doesn't work for - them. There are several common mistakes: - o Didn't properly configure postgresql before - compilation. You must run configure with - --enable-locale option to enable locale support. - Didn't setup environment correctly when starting - postmaster. You must define environment variables - LC_CTYPE and LC_COLLATE before running postmaster - because backend gets information about locale from - environment. I use following shell script - (runpostgres): - #!/bin/sh - - export LC_CTYPE=koi8-r - export LC_COLLATE=koi8-r - postmaster -B 1024 -S - -D/usr/local/pgsql/data/ -o '-Fe' - - and run it from rc.local as - /bin/su - postgres -c - "/home/postgres/runpostgres" - - - o Broken locale support in OS (for example, locale - support in libc under Linux several times has - changed and this caused a lot of problems). Latest - perl has also support of locale and if locale is - broken perl -v will complain something like: - 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE - not_exist - 8:18[mira]:~/WWW/postgres>perl -v - perl: warning: Setting locale failed. - perl: warning: Please check that your locale - settings: - LC_ALL = (unset), - LC_CTYPE = "not_exist", - LANG = (unset) - are supported and installed on your system. - perl: warning: Falling back to the standard - locale ("C"). - - - o Wrong location of locale files! Possible locations - include: /usr/lib/locale (Linux, Solaris), - /usr/share/locale (Linux), /usr/lib/nls/loc (DUX - 4.0). Check man locale to find the correct - location. Under Linux I did a symbolic link between - /usr/lib/locale and /usr/share/locale to be sure - that the next libc will not break my locale. - - -What are the Benefits? - - You can use ~* and order by operators for strings - contain characters from national alphabets. - Non-english users definitely need that. If you won't - use locale stuff just undefine the USE_LOCALE - variable. - -What are the Drawbacks? - - There is one evident drawback of using locale - its - speed! So, use locale only if you really need it. - -Kerberos Authentication - - Kerberos is an industry-standard secure - authentication system suitable for distributed - computing over a public network. - -Availability - - The Kerberos authentication system is not - distributed with Postgres. Versions of Kerberos are - typically available as optional software from - operating system vendors. In addition, a source code - distribution may be obtained through MIT Project - Athena (ftp://athena-dist.mit.edu). - - Note: You may wish to obtain the MIT version even - if your vendor provides a version, since some - vendor ports have been deliberately crippled or - rendered non-interoperable with the MIT version. - - Users located outside the United States of America - and Canada are warned that distribution of the actual - encryption code in Kerberos is restricted by U. S. - Government export regulations. - Inquiries regarding your Kerberos should be directed - to your vendor or MIT Project Athena - (info-kerberos@athena.mit.edu). Note that FAQLs - (Frequently-Asked Questions Lists) are periodically - posted to the Kerberos mailing list - (mailto:kerberos@ATHENA.MIT.EDU) (send mail to - subscribe (mailto:kerberos-request@ATHENA.MIT.EDU)), - and USENET news group (news:comp.protocols.kerberos). - -Installation - - Installation of Kerberos itself is covered in detail - in the Kerberos Installation Notes . Make sure that - the server key file (the srvtab or keytab) is somehow - readable by the Postgres account. - Postgres and its clients can be compiled to use - either Version 4 or Version 5 of the MIT Kerberos - protocols by setting the KRBVERS variable in the file - src/Makefile.global to the appropriate value. You can - also change the location where Postgres expects to - find the associated libraries, header files and its - own server key file. - After compilation is complete, Postgres must be - registered as a Kerberos service. See the Kerberos - Operations Notes and related manual pages for more - details on registering services. - -Operation - - After initial installation, Postgres should operate - in all ways as a normal Kerberos service. For details - on the use of authentication, see the PostgreSQL - User's Guide reference sections for postmaster and - psql. - In the Kerberos Version 5 hooks, the following - assumptions are made about user and service naming: - o User principal names (anames) are assumed to - contain the actual Unix/Postgres user name in the - first component. - o The Postgres service is assumed to be have two - components, the service name and a hostname, - canonicalized as in Version 4 (i.e., with all - domain suffixes removed). - - - - Table 4-1. Kerberos Parameter Examples - Parameter Example - 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.5 - - This release marks a major step in the development - team's mastery of the source code we inherited from - Berkeley. You will see we are now easily adding major - features, thanks to the increasing size and - experience of our world-wide development team. - Here is a brief summary of some of the more - noticable changes: - - Multi-version concurrency control(MVCC) - This removes our old table-level locking, and - replaces it with a locking system that is superior - to most commercial database systems. In a - traditional system, each row that is modified is - locked until committed, preventing reads by other - users. MVCC uses the natural multi-version nature - of PostgreSQL to allow readers to continue reading - consistent data during writer activity. Writers - continue to use the compact pg_log transaction - system. This is all performed without having to - allocate a lock for every row like traditional - database systems. So, basically, we no longer are - restricted by simple table-level locking; we have - something better than row-level locking. - - Numeric data type - We now have a true numeric data type, with - user-specified precision. - - Temporary tables - Temporary tables are guaranteed to have unique - names within a database session, and are destroyed - on session exit. - - New SQL features - We now have CASE, INTERSECT, and EXCEPT statement - support. We have new LIMIT/OFFSET, SET TRANSACTION - ISOLATION LEVEL, SELECT ... FOR UPDATE, and an - improved LOCK command. - - Speedups - We continue to speed up PostgreSQL, thanks to the - variety of talents within our team. We have sped - up memory allocation, optimization, table joins, - and row transfer routines. - - Ports - We continue to expand our port list, this time - including WinNT/ix86 and NetBSD/arm32. - - Interfaces - Most interfaces have new versions, and existing - functionality has been improved. - - -Migration to v6.5 - - A dump/restore using pg_dump or pg_dumpall is - required for those wishing to migrate data from any - previous release of Postgres. - The new Multi-Version Concurrency Control (MVCC) - features can give somewhat different behaviors in - multi-user environments. Read and understand the - following section to ensure that your existing - applications will give you the behavior you need. - - Multi-Version Concurrency Control - Because readers in 6.5 don't lock data, regardless - of transaction isolation level, data read by one - transaction can be overwritten by another. In the - other words, if a row is returned by SELECT it - doesn't mean that this row really exists at the time - it is returned (i.e. sometime after the statement or - transaction began) nor that the row is protected from - deletion or updation by concurrent transactions - before the current transaction does a commit or - rollback. - To ensure the actual existance of a row and protect - it against concurrent updates one must use SELECT FOR - UPDATE or an appropriate LOCK TABLE statement. This - should be taken into account when porting - applications from previous releases of Postgres and - other environments. - Keep above in mind if you are using contrib/refint.* - triggers for referential integrity. Additional - technics are required now. One way is to use LOCK - parent_table IN SHARE ROW EXCLUSIVE MODE command if a - transaction is going to update/delete a primary key - and use LOCK parent_table IN SHARE MODE command if a - transaction is going to update/insert a foreign key. - - Note: Note that if you run a transaction in - SERIALIZABLE mode then you must execute LOCK - commands above before execution of any DML - statement - (SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO) in the - transaction. - - - These inconveniences will disappear in the future - when the ability to read dirty (uncommitted) data - (regardless of isolation level) and true referential - integrity will be implemented. - -Detailed Change List - - - - Bug Fixes - --------- - Fix text<->float8 and text<->float4 conversion - functions(Thomas) - Fix for creating tables with mixed-case - constraints(Billy) - Change exp()/pow() behavior to generate error on - underflow/overflow(Jan) - Fix bug in pg_dump -z - Memory overrun cleanups(Tatsuo) - Fix for lo_import crash(Tatsuo) - Adjust handling of data type names to suppress double - quotes(Thomas) - Use type coersion for matching columns and - DEFAULT(Thomas) - Fix deadlock so it only checks once after one second - of sleep(Bruce) - Fixes for aggregates and PL/pgsql(Hiroshi) - Fix for subquery crash(Vadim) - Fix for libpq function PQfnumber and case-insensitive - names(Bahman Rafatjoo) - Fix for large object write-in-middle, no extra block, - memory consumption(Tatsuo) - Fix for pg_dump -d or -D and quote special - characters in INSERT - Repair serious problems with dynahash(Tom) - Fix INET/CIDR portability problems - Fix problem with selectivity error in ALTER TABLE ADD - COLUMN(Bruce) - Fix executor so mergejoin of different column types - works(Tom) - Fix for Alpha OR selectivity bug - Fix OR index selectivity problem(Bruce) - Fix so \d shows proper length for - char()/varchar()(Ryan) - Fix tutorial code(Clark) - Improve destroyuser checking(Oliver) - Fix for Kerberos(Rodney McDuff) - Fix for dropping database while dirty buffers(Bruce) - Fix so sequence nextval() can be - case-sensitive(Bruce) - Fix !!= operator - Drop buffers before destroying database files(Bruce) - Fix case where executor evaluates functions - twice(Tatsuo) - Allow sequence nextval actions to be - case-sensitive(Bruce) - Fix optimizer indexing not working for negative - numbers(Bruce) - Fix for memory leak in executor with fjIsNull - Fix for aggregate memory leaks(Erik Riedel) - Allow username containing a dash GRANT permissions - Cleanup of NULL in inet types - Clean up system table bugs(Tom) - Fix problems of PAGER and \? command(Masaaki Sakaida) - Reduce default multi-segment file size limit to - 1GB(Peter) - Fix for dumping of CREATE OPERATOR(Tom) - Fix for backward scanning of cursors(Hiroshi Inoue) - Fix for COPY FROM STDIN when using \i(Tom) - Fix for subselect is compared inside an - expression(Jan) - Fix handling of error reporting while returning - rows(Tom) - Fix problems with reference to array types(Tom,Jan) - Prevent UPDATE SET oid(Jan) - Fix pg_dump so -t option can handle case-sensitive - tablenames - Fixes for GROUP BY in special cases(Tom, Jan) - Fix for memory leak in failed queries(Tom) - DEFAULT now supports mixed-case identifiers(Tom) - Fix for multi-segment uses of DROP/RENAME table, - indexes(Ole Gjerde) - - Enhancements - ------------ - Add "vacuumdb" utility - Speed up libpq by allocating memory better(Tom) - EXPLAIN all indices used(Tom) - Implement CASE, COALESCE, NULLIF expression(Thomas) - New pg_dump table output format(Constantin) - Add string min()/max() functions(Thomas) - Extend new type coersion techniques to - aggregates(Thomas) - New moddatetime contrib(Terry) - Update to pgaccess 0.96(Constantin) - Add routines for single-byte "char" type(Thomas) - Improved substr() function(Thomas) - Improved multi-byte handling(Tatsuo) - Multi-version concurrency control/MVCC(Vadim) - New Serialized mode(Vadim) - Fix for tables over 2gigs(Peter) - New SET TRANSACTION ISOLATION LEVEL(Vadim) - New LOCK TABLE IN ... MODE(Vadim) - Update ODBC driver(Byron) - New NUMERIC data type(Jan) - New SELECT FOR UPDATE(Vadim) - Handle "NaN" and "Infinity" for input values(Jan) - Improved date/year handling(Thomas) - Improved handling of backend connections(Magnus) - New options ELOG_TIMESTAMPS and USE_SYSLOG options - for log files(Massimo) - New TCL_ARRAYS option(Massimo) - New INTERSECT and EXCEPT(Stefan) - New pg_index.indisprimary for primary key - tracking(D'Arcy) - New pg_dump option to allow dropping of tables before - creation(Brook) - Speedup of row output routines(Tom) - New READ COMMITTED isolation level(Vadim) - New TEMP tables/indexes(Bruce) - Prevent sorting if result is already sorted(Jan) - New memory allocation optimization(Jan) - Allow psql to do \p\g(Bruce) - Allow multiple rule actions(Jan) - Added LIMIT/OFFSET functionality(Jan) - Improve optimizer when joining a large number of - tables(Bruce) - New intro to SQL from S. Simkovics' Master's Thesis - (Stefan, Thomas) - New intro to backend processing from S. Simkovics' - Master's Thesis (Stefan) - Improved int8 support(Ryan Bradetich, Thomas, Tom) - New routines to convert between int8 and text/varchar - types(Thomas) - New bushy plans, where meta-tables are joined(Bruce) - Enable right-hand queries by default(Bruce) - Allow reliable maximum number of backends to be set - at configure time - (--with-maxbackends and postmaster switch (-N - backends))(Tom) - GEQO default now 10 tables because of optimizer - speedups(Tom) - Allow NULL=Var for MS-SQL portability(Michael, Bruce) - Modify contrib check_primary_key() so either - "automatic" or "dependent"(Anand) - Allow psql \d on a view show query(Ryan) - Speedup for LIKE(Bruce) - Ecpg fixes/features, see - src/interfaces/ecpg/ChangeLog file(Michael) - JDBC fixes/features, see - src/interfaces/jdbc/CHANGELOG(Peter) - Make % operator have precedence like /(Bruce) - Add new postgres -O option to allow system table - structure changes(Bruce) - Update contrib/pginterface/findoidjoins script(Tom) - Major speedup in vacuum of deleted rows with - indexes(Vadim) - Allow non-SQL functions to run different versions - based on arguments(Tom) - Add -E option that shows actual queries sent by \dt - and friends(Masaaki Sakaida) - Add version number in startup banners for - psql(Masaaki Sakaida) - New contrib/vacuumlo removes large objects not - referenced(Peter) - New initialization for table sizes so non-vacuumed - tables perform better(Tom) - Improve error messages when a connection is - rejected(Tom) - Support for arrays of char() and varchar() - fields(Massimo) - Overhaul of hash code to increase reliability and - performance(Tom) - Update to PyGreSQL 2.4(D'Arcy) - Changed debug options so -d4 and -d5 produce - different node displays(Jan) - New pg_options: pretty_plan, pretty_parse, - pretty_rewritten(Jan) - Better optimization statistics for system table - access(Tom) - Better handling of non-default block sizes(Massimo) - Improve GEQO optimizer memory consumption(Tom) - UNION now suppports ORDER BY of columns not in target - list(Jan) - Major libpq++ improvements(Vince Vielhaber) - - Source Tree Changes - ------------------- - Improve port matching(Tom) - Portability fixes for SunOS - Add NT/Win32 backend port and enable dynamic - loading(Magnus and Daniel Horak) - New port to Cobalt Qube(Mips) running Linux(Tatsuo) - Port to NetBSD/m68k(Mr. Mutsuki Nakajima) - Port to NetBSD/sun3(Mr. Mutsuki Nakajima) - Port to NetBSD/macppc(Toshimi Aoki) - Fix for tcl/tk configuration(Vince) - Removed CURRENT keyword for rule queries(Jan) - NT dynamic loading now works(Daniel Horak) - Add ARM32 support(Andrew McMurry) - Better support for HPUX 11 and Unixware - Improve file handling to be more uniform, prevent - file descriptor leak(Tom) - New install commands for plpgsql(Jan) - +PostgreSQL Installation + +For a fresh install or upgrading from previous releases of PostgreSQL: + + 1. Create the PostgreSQL superuser account. This is the user the server + will run as. For production use you should create a separate, + unprivileged account (postgres is commonly used). If you do not have + root access or just want to play around, your own user account is + enough. + + Running PostgreSQL as root, bin, or any other account with special + access rights is a security risk and therefore won't be allowed. + + You need not do the building and installation itself under this account + (although you can). You will be told when you need to login as the + database superuser. + + 2. If you are not upgrading an existing system then skip to step 4. + + You now need to back up your existing database. To dump your fairly + recent post-6.0 database installation, type + + $ pg_dumpall > db.out + + If you wish to preserve object id's (oids), then use the -o option when + running pg_dumpall. However, unless you have a special reason for doing + this (such as using OIDs as keys in tables), don't do it. + + Make sure to use the pg_dumpall command from the version you are + currently running. However, do not use the pg_dumpall script from 6.0 + or everything will be owned by the PostgreSQL super user. In that case + you should grab pg_dumpall from a later 6.x.x release. 7.0's pg_dumpall + will not work on older databases. If you are upgrading from a version + prior to Postgres95 v1.09 then you must back up your database, install + Postgres95 v1.09, restore your database, then back it up again. + + Caution + You must make sure that your database is not updated in the middle of your + backup. If necessary, bring down postmaster, edit the permissions in file + /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring + postmaster back up. + + 3. If you are upgrading an existing system then kill the database server + now. Type + + $ ps ax | grep postmaster + + This should list the process numbers for a number of processes, similar + to this: + + 263 ? SW 0:00 (postmaster) + 777 p1 S 0:00 grep postmaster + + Type the following line, with pid replaced by the process id for + process postmaster (263 in the above case). (Do not use the id for the + process "grep postmaster".) + + $ kill pid + + Tip: On systems which have PostgreSQL started at boot time, + there is probably a startup file which will accomplish the + same thing. For example, on a Redhat Linux system one might + find that + + $ /etc/rc.d/init.d/postgres.init stop + + works. + + Also move the old directories out of the way. Type the following: + + $ mv /usr/local/pgsql /usr/local/pgsql.old + + or replace your particular paths. + + 4. Configure the source code for your system. It is this step at which you + can specify your actual installation path for the build process and + make choices about what gets installed. Change into the src + subdirectory and type: + + $ ./configure [ options ] + + For a complete list of options, type: + + ./configure --help + + Some of the more commonly used ones are: + + --prefix=BASEDIR + + Selects a different base directory for the installation of + PostgreSQL. The default is /usr/local/pgsql. + + --enable-locale + + If you want to use locales. + + --enable-multibyte + + Allows the use of multibyte character encodings. This is primarily + for languages like Japanese, Korean, or Chinese. + + --with-perl + + Builds the Perl interface. Please note that the Perl interface + will be installed into the usual place for Perl modules (typically + under /usr/lib/perl), so you must have root access to use this + option successfully. + + --with-odbc + + Builds the ODBC driver package. + + --with-tcl + + Builds interface libraries and programs requiring Tcl/Tk, + including libpgtcl, pgtclsh, and pgtksh. + + 5. Compile the program. Type + + $ gmake + + The compilation process can take anywhere from 10 minutes to an hour. + Your milage will most certainly vary. + + The last line displayed will hopefully be + + All of PostgreSQL is successfully made. Ready to install. + + Remember, "gmake" may be called "make" on your system. + + 6. Install the program. Type + + $ gmake install + + 7. Tell your system how to find the new shared libraries. How to do this + varies between platforms. What tends to work everywhere is to set the + environment variable LD_LIBRARY_PATH: + + $ LD_LIBRARY_PATH=/usr/local/pgsql/lib + $ export LD_LIBRARY_PATH + + You might want to put this into a shell startup file such as + ~/.bash_profile. + + On some systems the following is the preferred method, but you must + have root access. Edit file /etc/ld.so.conf to add a line + + /usr/local/pgsql/lib + + Then run command /sbin/ldconfig. + + If in doubt, refer to the manual pages of your system. If you later on + get a message like + + ./psql: error in loading shared libraries + libpq.so.2.1: cannot open shared object file: No such file or directory + + then the above was necessary. Simply do this step then. + + 8. Create the database installation. To do this you must log in to your + PostgreSQL superuser account. It will not work as root. + + $ mkdir /usr/local/pgsql/data + $ chown postgres /usr/local/pgsql/data + $ su - postgres + $ /usr/local/pgsql/initdb -D /usr/local/pgsql/data + + The -D option specifies the location where the data will be stored. You + can use any path you want, it does not have to be under the + installation directory. Just make sure that the superuser account can + write to it (or create it) before starting initdb. + + 9. The previous step should have told you how to start up the database + server. Do so now. + + $ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data + + This will start the server in the foreground. To make it detach to the + background, use the -S. + + 10. If you are upgrading from an existing installation, dump your data back + in: + + $ /usr/local/pgsql/bin/psql < db.out + + You also might want to copy over the old pg_hba.conf file and any other + files you might have had set up for authentication, such as password + files. + +This concludes the installation proper. To make your life more productive +and enjoyable you should look at the following optional steps and +suggestions. + + * Life will be more convenient if you set up some enviroment variables. + First of all you probably want to include /usr/local/pgsql/bin (or + equivalent) into your PATH. To do this, add the following to your shell + startup file, such as ~/.bash_profile (or /etc/profile, if you want it + to affect every user): + + PATH=$PATH:/usr/local/pgsql/bin + + Furthermore, if you set PGDATA in the environment of the PostgreSQL + superuser, you can omit the -D for postmaster and initdb. + + * You probably want to install the man and HTML documentation. Type + + $ cd /usr/src/pgsql/postgresql-7.0.0/doc + $ gmake install + + This will install files under /usr/local/pgsql/doc. + + The documentation is also available in Postscript format. If you have a + Postscript printer, or have your machine already set up to accept + Postscript files using a print filter, then to print the User's Guide + simply type + + $ cd /usr/local/pgsql/doc + $ gunzip -c user.ps.tz | lpr + + Here is how you might do it if you have Ghostscript on your system and + are writing to a laserjet printer. + + $ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' + $ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts + $ gunzip user.ps.gz + $ gshp -sOUTPUTFILE=user.hp user.ps + $ gzip user.ps + $ lpr -l -s -r manpage.hp + + If in doubt, confer your manuals or your local expert. + + The Adminstrator's Guide should probably be your first reading if you + are completely new to PostgreSQL, as it contains information about how + to set up database users and authentication. + + * Usually, you will want to modify your computer so that it will + automatically start the database server whenever it boots. This is not + required; the PostgreSQL server can be run successfully from + non-privileged accounts without root intervention. + + Different systems have different conventions for starting up daemons at + boot time, so you are advised to familiarize yourself with them. Most + systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost + certainly no bad place to put such a command. Whatever you do, + postmaster must be run by the PostgreSQL superuser (postgres) and not + by root or any other user. Therefore you probably always want to form + your command lines along the lines of su -c '...' postgres. + + It might be advisable to keep a log of the server output. To start the + server that way try: + + nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & + + Here are a few more operating system specific suggestions. + + o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1 + to contain the following single line: + + su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" + + o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to + contain the following lines and make it chmod 755 and chown + root:bin. + + #!/bin/sh + [ -x /usr/local/pgsql/bin/postmaster ] && { + su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster + -D/usr/local/pgsql/data + -S -o -F > /usr/local/pgsql/errlog' & + echo -n ' pgsql' + } + + You may put the line breaks as shown above. The shell is smart + enough to keep parsing beyond end-of-line if there is an + expression unfinished. The exec saves one layer of shell under the + postmaster process so the parent is init. + o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is + based on the example in contrib/linux/. Then make a softlink to + this file from /etc/rc.d/rc5.d/S98postgres.init. + * Run the regression tests. The regression tests are a test suite to + verify that PostgreSQL runs on your machine in the way the developers + expected it to. You should definitely do this before putting a server + into production use. The file + /usr/src/pgsql/postgresql-7.0.0/src/test/regress/README has detailed + instructions for running and interpreting the regression tests. diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml index dafc3d1f798..05127939fb9 100644 --- a/doc/src/sgml/install.sgml +++ b/doc/src/sgml/install.sgml @@ -3,52 +3,13 @@ <Abstract> <Para> - Complete installation instructions for - <ProductName>Postgres</ProductName> 6.5.3. + Installation instructions for + <ProductName>PostgreSQL</ProductName> 7.0.0. </Para> </Abstract> <Para> - Before installing <ProductName>Postgres</ProductName>, you may wish to visit - <ULink url="http://www.postgresql.org">www.postgresql.org</ULink> - for up to date information, patches, etc. - </Para> - - <Para> - These installation instructions assume: - - <ItemizedList Mark="bullet" Spacing="compact"> - <ListItem> - <Para> - Commands are Unix-compatible. See note below. - </Para> - </ListItem> - <ListItem> - <Para> - Defaults are used except where noted. - </Para> - </ListItem> - <ListItem> - <Para> - User <literal>postgres</literal> is the - <ProductName>Postgres</ProductName> superuser. - </Para> - </ListItem> - <ListItem> - <Para> - The source path is <filename>/usr/src/pgsql</filename> (other paths are possible). - </Para> - </ListItem> - <ListItem> - <Para> - The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible). - </Para> - </ListItem> - </ItemizedList> - </para> - - <Para> - Commands were tested on RedHat Linux version 5.2 using the tcsh shell. + Commands were tested on RedHat Linux version 5.2 using the bash shell. Except where noted, they will probably work on most systems. Commands like <command>ps</command> and <command>tar</command> may vary wildly between platforms on what options you should use. @@ -56,60 +17,70 @@ </Para> <Para> - Our Makefiles require GNU <Application>make</Application> (called - <Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis> - work with non-GNU <Application>make</Application> programs. If you - have GNU <Application>make</Application> installed under the name - <Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the - command <command>make</command> instead. That's OK, but - you need to have the GNU form of <Application>make</Application> to succeed with - an installation. + If you haven't gotten the <ProductName>PostgreSQL</ProductName> distribution, + get it from <ULink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ULink>, + then unpack it: +<ProgramListing> +$ gunzip postgresql-7.0.0.tar.gz +$ tar -xf postgresql-7.0.0.tar +$ mv postgresql-7.0.0 /usr/src +</ProgramListing> + Again, these commands might differ on your system. </Para> <Sect1> - <Title>Requirements to Run <ProductName>Postgres</ProductName></Title> + <Title>Before you start</Title> + + <Para> + Building <Productname>PostgreSQL</Productname> requires <acronym>GNU</acronym> + <Application>make</Application>. It will <Emphasis>not</Emphasis> + work with other <Application>make</Application> programs. On GNU/Linux systems + GNU make is the default tool, on other systems you may find that + GNU <Application>make</Application> is installed under the name <Quote>gmake</Quote>. + We will use that name from now on to indicate <acronym>GNU</acronym> + <Application>make</Application>, no matter what name it has on your system. + To test for <acronym>GNU</acronym> <Application>make</Application> enter +<programlisting> +$ <userinput>gmake --version</userinput> +</programlisting> + If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can + find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>. + </Para> <Para> Up to date information on supported platforms is at - <ulink url="http://www.postgresql.org/docs/admin/install.htm"> - http://www.postgresql.org/docs/admin/install.htm</ulink>. - - In general, most Unix-compatible - platforms with modern libraries should be able to run - <ProductName>Postgres</ProductName>. + <ulink url="http://www.postgresql.org/docs/admin/ports.htm"> + http://www.postgresql.org/docs/admin/ports.htm</ulink>. + In general, most Unix-compatible platforms with modern libraries should be able to run + <ProductName>PostgreSQL</ProductName>. In the <filename>doc</filename> subdirectory + of the distribution are several platform-specific FAQ and README documents you + might wish to consult if you are having trouble. </para> + <para> - Although the minimum required memory for running <ProductName>Postgres</ProductName> - 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. + Although the minimum required memory for running <ProductName>PostgreSQL</ProductName> + can be as little as 8MB, there are noticable speed improvements when expanding memory + up to 96MB or beyond. The rule is you can never have too much memory. </para> <Para> Check that you have sufficient disk space. You will need about - 30 Mbytes for <filename>/usr/src/pgsql</filename>, - about 5 Mbytes for <filename>/usr/local/pgsql</filename> - (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. - </Para> - - <Para> - We therefore recommend that during installation and testing you - have well over 20 Mbytes free under <filename>/usr/local</filename> 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 <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty - database, plus about five times the space you would require to - store your database data in a flat file. + 30 Mbytes for the source tree during compilation and about 5 Mbytes for + the installation directory. An empty database takes about 1 Mbyte, otherwise + they take about five times the amount of space that a flat text file with the + same data would take. If you run the regression tests you will temporarily need + an extra 20MB. </Para> <Para> To check for disk space, use - <programlisting> +<programlisting> $ df -k - </programlisting> +</programlisting> + </para> + + <para> + Considering today's prices for hard disks, getting a large and fast hard disk should + probably be in your plans before putting a database into production use. </para> </Sect1> @@ -117,112 +88,45 @@ $ df -k <Title>Installation Procedure</Title> <Procedure> -<Title><ProductName>Postgres</ProductName> Installation</Title> +<Title><ProductName>PostgreSQL</ProductName> Installation</Title> <Para> For a fresh install or upgrading from previous releases of -<ProductName>Postgres</ProductName>: +<ProductName>PostgreSQL</ProductName>: </Para> -<Step Performance="required"> -<Para> -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 <FileName>/usr/src/pgsql/postgresql-6.5.3/doc</FileName>, including files FAQ-Irix - and FAQ-Linux. Also look in directory -<ULink url="ftp://ftp.postgresql.org/pub">ftp://ftp.postgresql.org/pub</ULink>. - If there is a file called INSTALL in this directory then this - file will contain the latest installation information. -</Para> - -<Para> - 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 <ProductName>Postgres</ProductName> 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 -<ULink url="ftp://ftp.postgresql.org/pub/INSTALL">ftp://ftp.postgresql.org/pub/INSTALL</ULink>. -</Para> -</Step> - <Step Performance="optional"> <Para> -Create the <ProductName>Postgres</ProductName> superuser account -(<literal>postgres</literal> is commonly used) if it does not already exist. +Create the <ProductName>PostgreSQL</ProductName> superuser account. +This is the user the server will run as. For production use you +should create a separate, unprivileged account (<literal>postgres</literal> is +commonly used). If you do not have root access or just want to play around, +your own user account is enough. </para> <para> -The owner of the Postgres files can be any unprivileged user account. -It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>, -or any other account with special access rights, as that would create a security risk. +Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>, +or any other account with special access rights is a security risk and therefore +won't be allowed. </para> -</Step> - -<Step Performance="required"> -<Para> -Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the -remaining steps in the installation will happen in this account. -</para> -</step> -<Step Performance="required"> <Para> -Ftp file -<ulink url="ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz"> - <filename>ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz</filename></ulink> - from the Internet. Store it in your home directory. +You need not do the building and installation itself under this account +(although you can). You will be told when you need to login as the +database superuser. </Para> </Step> <Step Performance="required"> <Para> If you are not upgrading an existing system then skip to -<xref linkend="newdirs">. -If you are upgrading from 6.5, you do not need to dump/reload or initdb. -Simply compile the source code, stop the postmaster, do a "make install", and -restart the postmaster. - -If you are upgrading from 6.4.* or earlier, 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. -</para> -<tip> -<para> -Do not use the <application>pg_dumpall</application> -script from 6.0 or everything - will be owned by the <ProductName>Postgres</ProductName> super user. -</para> -</tip> +<xref linkend="continue">. +</Para> -<para> +<Para> +You now need to back up your existing database. To dump your fairly recent post-6.0 database installation, type - <programlisting> $ pg_dumpall > db.out </programlisting> -</para> -<para> -To use the latest <application>pg_dumpall</application> script on your -existing older database before upgrading <productname>Postgres</productname>, -pull the most recent version of <application>pg_dumpall</application> -from the new distribution: - -<ProgramListing> -$ cd -$ gunzip -c postgresql-6.5.3.tar.gz \ - | tar xvf - postgresql-6.5.3/src/bin/pg_dump/pg_dumpall -$ chmod a+x postgresql-6.5.3/src/bin/pg_dump/pg_dumpall -$ postgresql-6.5.3/src/bin/pg_dump/pg_dumpall > db.out -$ rm -rf postgresql-6.5.3 -</ProgramListing> -</Para> - -<Para> If you wish to preserve object id's (oids), then use the -o option when running <application>pg_dumpall</application>. However, unless you have a @@ -231,23 +135,18 @@ in tables), don't do it. </Para> <Para> - If the <application>pg_dumpall</application> command - seems to take a long time and you think - it might have died, then, from another terminal, type -<programlisting> -$ ls -l db.out -</programlisting> - several times to see if the size of the file is growing. -</Para> - -<Para> - Please note that if you are upgrading from a version prior to - <ProductName>Postgres95</ProductName> v1.09 then you must back up your database, - install - <ProductName>Postgres95</ProductName> v1.09, restore your database, - then back it up again. - You should also read the release notes which should cover any - release-specific issues. +Make sure to use the <application>pg_dumpall</application> +command from the version you are currently running. +However, do not use the <application>pg_dumpall</application> +script from 6.0 or everything will be owned by the +<ProductName>PostgreSQL</ProductName> super user. In that case +you should grab <application>pg_dumpall</application> from a later +6.x.x release. 7.0's <application>pg_dumpall</application> +will not work on older databases. +If you are upgrading from a version prior to +<ProductName>Postgres95</ProductName> v1.09 then you must back up your database, +install <ProductName>Postgres95</ProductName> v1.09, restore your database, +then back it up again. </Para> <caution> @@ -259,572 +158,330 @@ $ ls -l db.out bring <application>postmaster</application> back up. </Para> </caution> - </Step> <Step Performance="required"> <Para> -If you are upgrading an existing system then kill the postmaster. Type +If you are upgrading an existing system then kill the database server now. Type <ProgramListing> -$ ps -ax | grep postmaster +$ ps ax | grep postmaster </ProgramListing> - - This should list the process numbers for a number of processes. Type - the following line, with <replaceable>pid</replaceable> - replaced by the process id for process - <literal>postmaster</literal>. -(Do not use the id for process "grep postmaster".) Type +This should list the process numbers for a number of processes, similar +to this: +<ProgramListing> + 263 ? SW 0:00 (postmaster) + 777 p1 S 0:00 grep postmaster +</ProgramListing> +Type the following line, with <replaceable>pid</replaceable> +replaced by the process id for process <literal>postmaster</literal> +(263 in the above case). (Do not use the id for the process "grep postmaster".) <programlisting> $ kill <replaceable>pid</replaceable> </programlisting> -to actually stop the process. +</Para> <tip> <para> -On systems which have <productname>Postgres</productname> 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 +On systems which have <productname>PostgreSQL</productname> started at boot time, there +is probably a startup file which will accomplish the same thing. For example, on a +Redhat Linux system one might find that <programlisting> $ /etc/rc.d/init.d/postgres.init stop </programlisting> -to halt <productname>Postgres</productname>. +works. </para> </tip> -</Para> -</Step> -<Step Performance="required"> <Para> -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 <filename>/usr/local/pgsql/data</filename> directory tree. At a - minimum, save file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. -</Para> - -<Para> - Type the following: +Also move the old directories out of the way. Type the following: <programlisting> -$ su - -$ cd /usr/src -$ mv pgsql pgsql.old -$ cd /usr/local -$ mv pgsql pgsql.old -$ exit +$ mv /usr/local/pgsql /usr/local/pgsql.old </programlisting> +or replace your particular paths. </Para> -<Para> - If you are not using <filename>/usr/local/pgsql/data</filename> - 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. -</Para> -</Step> - -<Step Performance="required" id="newdirs"> -<Para> - Make new source and install directories. The actual paths can be - different for your installation but you must be consistent throughout this procedure. -</para> -<note> -<para> -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 <command>gmake install</command> stage -of installation. -</para> -</note> - -<para> - Type -<ProgramListing> -$ su -$ cd /usr/src -$ mkdir pgsql -$ chown postgres:postgres pgsql -$ cd /usr/local -$ mkdir pgsql -$ chown postgres:postgres pgsql -$ exit -</ProgramListing> -</Para> -</Step> - -<Step Performance="required"> -<Para> - Unzip and untar the new source file. Type -<ProgramListing> -$ cd /usr/src/pgsql -$ gunzip -c ~/postgresql-6.5.3.tar.gz | tar xvf - -</ProgramListing> -</Para> </Step> -<Step Performance="required"> +<Step Performance="required" id="continue"> <Para> - 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 +Configure the source code for your system. It is this step at which +you can specify your actual installation path for the build process +and make choices about what gets installed. Change into the <filename>src</filename> +subdirectory and type: <ProgramListing> -$ cd /usr/src/pgsql/postgresql-6.5.3/src $ ./configure [ <replaceable>options</replaceable> ] </ProgramListing> -</Para> - -<substeps> - -<Step Performance="optional"> -<Para> - 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 -<option>--with-template=TEMPLATE</option> option to - make the right file be chosen. - -<note> -<title>Please Report Problems</title> - -<para> -If your system is not automatically recognized by configure and you have to do this, please - send email to -<ulink url="mailto:scrappy@hub.org">scrappy@hub.org</ulink> with the output of the program - <application>./config.guess</application>. Indicate what the template file should be. -</para> -</note> - -</Para> -</step> -<Step Performance="optional"> -<Para> -Choose configuration options. Check <xref linkend="config" endterm="install-config"> -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 +For a complete list of options, type: <ProgramListing> ./configure --help </ProgramListing> Some of the more commonly used ones are: -<ProgramListing> - --prefix=BASEDIR Selects a different base directory for the - installation of the <ProductName>Postgres</ProductName> configuration. - 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.) -</ProgramListing> -</Para> -</step> -<Step Performance="required"> -<Para> -Here is the configure script used on a Sparc Solaris 2.5 system - with <filename>/opt/postgres</filename> specified as - the installation base directory: +<VariableList> + <varlistentry> + <term>--prefix=BASEDIR</term> + <listitem> + <para> + Selects a different base directory for the installation of + <ProductName>PostgreSQL</ProductName>. The default is <filename>/usr/local/pgsql</filename>. + </para> + </listitem> + </varlistentry> -<ProgramListing> -$ ./configure --prefix=/opt/postgres \ - --with-template=sparc_solaris-gcc --with-pgport=5432 \ - --enable-hba --disable-locale -</ProgramListing> + <varlistentry> + <term>--enable-locale</term> + <listitem> + <para> + If you want to use locales. + </para> + </listitem> + </varlistentry> -<tip> -<para> - Of course, you may type these three lines all - on the same line. -</para> -</tip> + <varlistentry> + <term>--enable-multibyte</term> + <listitem> + <para> + Allows the use of multibyte character encodings. This is primarily for + languages like Japanese, Korean, or Chinese. + </para> + </listitem> + </varlistentry> -</Para> -</Step> + <varlistentry> + <term>--with-perl</term> + <listitem> + <para> + Builds the Perl interface. Please note that the Perl interface will be + installed into the usual place for Perl modules (typically under + <filename>/usr/lib/perl</filename>), so you must have root access to use + this option successfully. + </para> + </listitem> + </varlistentry> -</substeps> -</step> -<Step Performance="required"> -<Para> -Install the <application>man</application> and -<acronym>HTML</acronym> documentation. Type + <varlistentry> + <term>--with-odbc</term> + <listitem> + <para> + Builds the ODBC driver package. + </para> + </listitem> + </varlistentry> -<ProgramListing> -$ cd /usr/src/pgsql/postgresql-6.5.3/doc -$ gmake install -</ProgramListing> -</para> -<para> -The documentation is also available in Postscript format. Look for files -ending with <filename>.ps.gz</filename> in the same directory. -</para> + <varlistentry> + <term>--with-tcl</term> + <listitem> + <para> + Builds interface libraries and programs requiring + Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. + </para> + </listitem> + </varlistentry> +</VariableList> + +</Para> </step> + <Step Performance="required"> <Para> Compile the program. Type - <ProgramListing> -$ cd /usr/src/pgsql/postgresql-6.5.3/src -$ gmake all > make.log 2>&1 & -$ tail -f make.log +$ gmake </ProgramListing> +The compilation process can take anywhere from 10 minutes to an hour. +Your milage will most certainly vary. </Para> <Para> - The last line displayed will hopefully be +The last line displayed will hopefully be <programlisting> All of PostgreSQL is successfully made. Ready to install. </programlisting> Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> on your system. - - 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> -<para> -You will probably find a number of warning - messages in make.log. Unless you have problems later on, these - messages may be safely ignored. -</para> -</note> -</para> -<Para> - If the compiler fails with a message stating that -the <application>flex</application> command - cannot be found then install <application>flex</application> as described earlier. - Next, - change directory back to this directory, type -<programlisting> -$ gmake clean -</programlisting> -then recompile again. </Para> +</Step> +<Step Performance="required"> <Para> - Compiler options, such as optimization and debugging, may - be specified on the command line using the COPT variable. - For example, typing +Install the program. Type <ProgramListing> -$ gmake COPT="-g" all > make.log 2>&1 & +$ gmake install </ProgramListing> - would invoke your compiler's <option>-g</option> option in all steps of the - build. See <filename>src/Makefile.global.in</filename> for further details. </Para> </Step> <Step Performance="required"> <Para> - Install the program. Type -<ProgramListing> -$ cd /usr/src/pgsql/postgresql-6.5.3/src -$ gmake install > make.install.log 2>&1 & -$ tail -f make.install.log -</ProgramListing> +Tell your system how to find the new shared libraries. How to do this varies between +platforms. What tends to work everywhere is to set the environment variable +<envar>LD_LIBRARY_PATH</envar>: +<programlisting> +$ LD_LIBRARY_PATH=/usr/local/pgsql/lib +$ export LD_LIBRARY_PATH +</programlisting> +You might want to put this into a shell startup file such as +<filename>~/.bash_profile</filename>. </Para> <Para> - The last line displayed will be +On some systems the following is the preferred method, but you must have root +access. Edit file <filename>/etc/ld.so.conf</filename> to add a line <programlisting> -Thank you for choosing PostgreSQL, the most advanced open source -database engine. +<FileName>/usr/local/pgsql/lib</FileName> </programlisting> -At this point, or earlier if you wish, - type control-C to get out of tail. -Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> on -your system. +Then run command <Command>/sbin/ldconfig</Command>. </Para> -</Step> -<Step Performance="required"> -<Para> -If necessary, tell your system how to find the new shared libraries. You can -do <emphasis>one</emphasis> of the following, preferably the first: -</para> -<SubSteps> -<Step Performance="optional"> <Para> - As root, edit file <filename>/etc/ld.so.conf</filename>. Add a line +If in doubt, refer to the manual pages of your system. If you later on get +a message like <programlisting> -<FileName>/usr/local/pgsql/lib</FileName> +./psql: error in loading shared libraries +libpq.so.2.1: cannot open shared object file: No such file or directory </programlisting> -to the file. Then run command <Command>/sbin/ldconfig</Command>. +then the above was necessary. Simply do this step then. </Para> </Step> -<Step Performance="optional"> +<Step Performance="required"> <Para> - In a bash shell, type +Create the database installation. To do this you must log in to your +<ProductName>PostgreSQL</ProductName> superuser account. It will not +work as root. <ProgramListing> - export LD_LIBRARY_PATH=/usr/local/pgsql/lib +$ mkdir /usr/local/pgsql/data +$ chown postgres /usr/local/pgsql/data +$ su - postgres +$ /usr/local/pgsql/initdb -D /usr/local/pgsql/data </ProgramListing> </Para> -</Step> -<Step Performance="optional"> <Para> - In a csh shell, type -<ProgramListing> - setenv LD_LIBRARY_PATH /usr/local/pgsql/lib -</ProgramListing> -</para> +The <option>-D</option> option specifies the location where the data will be +stored. You can use any path you want, it does not have to be under +the installation directory. Just make sure that the superuser account +can write to it (or create it) before starting <command>initdb</command>. +</Para> </Step> -</SubSteps> +<Step Performance="required"> <Para> - 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. +The previous step should have told you how to start up the database server. +Do so now. +<programlisting> +$ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data +</programlisting> +This will start the server in the foreground. To make it detach to +the background, use the <option>-S</option>. </Para> +</Step> -<Para> - If, when you create the database, you get the message +<Step Performance="optional"> +<para> +If you are upgrading from an existing installation, dump your data back in: <programlisting> -pg_id: can't load library 'libpq.so' +$ /usr/local/pgsql/bin/psql < db.out </programlisting> - then the above step was necessary. Simply - do this step, then try to create the database again. +You also might want to copy over the old <filename>pg_hba.conf</filename> +file and any other files you might have had set up for authentication, such +as password files. </Para> </Step> +</Procedure> - <Step Performance="optional"> - <Para> - If you used the <option>--with-perl</option> 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 <command>su</command>) and doing - <ProgramListing> - $ cd /usr/src/pgsql/postgresql-6.5.3/src/interfaces/perl5 - $ gmake install - </ProgramListing> - </Para> - </Step> - - <Step Performance="required"> - <Para> - If it has not already been done, then prepare account <literal>postgres</literal> - for using <ProductName>Postgres</ProductName>. - Any account that will use <ProductName>Postgres</ProductName> must - be similarly prepared. - </para> - <para> - There are several ways to influence the runtime environment of the - <ProductName>Postgres</ProductName> - server. Refer to the <citetitle>Administrator's Guide</citetitle> - for more information. - <note> - <para> - The following instructions are for a - bash/sh shell. Adapt accordingly for other shells. - </para> - </note> - </Para> - - <substeps> - - <Step Performance="required"> - <Para> - Add the following lines to your login environment: - - shell, <filename>~/.bash_profile</filename>: - <ProgramListing> - 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 - </ProgramListing> - </Para> - </step> - <Step Performance="required"> - <para> - Several regression tests could fail if the user's locale collation - scheme is different from that of the standard <literal>C</literal> locale. - </para> - <para> - If you configure and compile <ProductName>Postgres</ProductName> - with <option>--enable-locale</option> then you should - set the locale environment to <quote><literal>C</literal></quote> - (or unset all <quote>LC_*</quote> variables) - by putting these additional lines to your login environment - before starting <application>postmaster</application>: - - <ProgramListing> - LC_COLLATE=C - LC_CTYPE=C - export LC_COLLATE LC_CTYPE - </ProgramListing> - - <ProgramListing> - - </ProgramListing> - </para> - </step> - - <Step Performance="required"> - <Para> - Make sure that you have defined these variables before continuing - with the remaining steps. The easiest way to do this is to type: - <ProgramListing> - $ source ~/.bash_profile - </ProgramListing> - </Para> - </Step> - - </substeps> - </step> +<para> +This concludes the installation proper. To make your life more productive and enjoyable +you should look at the following optional steps and suggestions. +</para> -<Step Performance="required"> +<itemizedlist> +<listitem> <Para> - Create the database installation from your <ProductName>Postgres</ProductName> -superuser account (typically account <literal>postgres</literal>). - -<Emphasis>Do not do the following as root!</Emphasis> -This would be a major security hole. Type -<ProgramListing> -$ initdb -</ProgramListing> +Life will be more convenient if you set up some enviroment variables. First of all +you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent) +into your <envar>PATH</envar>. To do this, add the following to your shell startup +file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>, +if you want it to affect every user): +<programlisting> +PATH=$PATH:/usr/local/pgsql/bin +</programlisting> </Para> -</Step> - -<Step Performance="required"> <Para> - Set up permissions to access the database system. Do this by editing - file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. The instructions are - included in the file. (If your database is not located in the - default location, i.e. if <envar>PGDATA</envar> 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 6.0 or later you can copy file <filename>pg_hba.conf</filename> from - your old database on top of the one in your new database, rather than - redoing the file from scratch. +Furthermore, if you set <envar>PGDATA</envar> in the environment of the PostgreSQL +superuser, you can omit the <option>-D</option> for <filename>postmaster</filename> +and <filename>initdb</filename>. </Para> -</Step> - -<Step Performance="required"> -<para> -Briefly test that the backend will start and run by running it from -the command line. -</para> -<substeps> +</listitem> -<Step Performance="required"> -<para> - Start the postmaster daemon running in the background by typing +<listitem> +<Para> +You probably want to install the <application>man</application> and +<acronym>HTML</acronym> documentation. Type <ProgramListing> -$ cd -$ nohup postmaster -i > pgserver.log 2>&1 & +$ cd /usr/src/pgsql/postgresql-7.0.0/doc +$ gmake install </ProgramListing> -</Para> -</Step> +This will install files under <filename>/usr/local/pgsql/doc</filename>. +</para> -<Step Performance="required"> <para> -Create a database by typing -<ProgramListing> -$ createdb test -</ProgramListing> +The documentation is also available in Postscript format. If you have +a Postscript printer, or have your machine already set up to accept +Postscript files using a print filter, then to print the User's Guide +simply type +<programlisting> +$ cd /usr/local/pgsql/doc +$ gunzip -c user.ps.tz | lpr +</programlisting> +Here is how you might do it if you have Ghostscript on your system and are +writing to a laserjet printer. +<programlisting> +$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' +$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts +$ gunzip user.ps.gz +$ gshp -sOUTPUTFILE=user.hp user.ps +$ gzip user.ps +$ lpr -l -s -r manpage.hp +</programlisting> +If in doubt, confer your manuals or your local expert. </para> -</step> -<Step Performance="required"> + <para> -Connect to the new database: -<ProgramListing> -$ psql test -</ProgramListing> +The Adminstrator's Guide should probably be your first reading if you +are completely new to <productname>PostgreSQL</productname>, as it contains +information about how to set up database users and authentication. </para> -</step> -<Step Performance="required"> -<para> -And run a sample query: -<ProgramListing> -postgres=> SELECT datetime 'now'; -</ProgramListing> +</listitem> + +<listitem> +<Para> +Usually, you will want to modify your computer so that it will automatically +start the database server whenever it boots. +This is not required; the <ProductName>PostgreSQL</ProductName> server can +be run successfully from non-privileged accounts without root intervention. </para> -</step> -<Step Performance="required"> <para> -Exit <application>psql</application>: -<ProgramListing> -postgres=> \q -</ProgramListing> +Different systems have different conventions for starting up daemons at boot time, +so you are advised to familiarize yourself with them. +Most systems have a file <filename>/etc/rc.local</filename> or +<filename>/etc/rc.d/rc.local</filename> which is almost certainly no bad place +to put such a command. +Whatever you do, postmaster must be run by the <ProductName>PostgreSQL</ProductName> +superuser (<literal>postgres</literal>) <emphasis>and not by root</emphasis> or +any other user. Therefore you probably always want to form your command lines +along the lines of <literal>su -c '...' postgres</literal>. </para> -</step> -<Step Performance="required"> <para> -Remove the test database (unless you will want to use it later for other tests): +It might be advisable to keep a log of the server output. To start the server that way +try: <ProgramListing> -$ dropdb test +nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres & </ProgramListing> </para> -</step> -</substeps> -</step> -<Step Performance="required"> -<Para> - Run postmaster in the background from your <ProductName>Postgres</ProductName> -superuser account (typically account <literal>postgres</literal>). -<emphasis>Do not run <application>postmaster</application> -from the root account!</emphasis> -</para> -<Para> -Usually, you will want to modify - your computer so that it will automatically start postmaster whenever - it boots. It is not required; the <ProductName>Postgres</ProductName> -server can -be run successfully from non-privileged accounts without root intervention. -</para> -<para> - Here are some suggestions on how to do this, contributed by various - users. -</para> -<para> - Whatever you do, postmaster must be run by -the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?) -<emphasis>and not by root</emphasis>. -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. - -<itemizedlist mark="bullet"> -<listitem> <para> -If you are installing from a non-privileged account and have no root access, then -start the <application>postmaster</application> and send it to the background: +Here are a few more operating system specific suggestions. -<ProgramListing> -$ cd -$ nohup postmaster > regress.log 2>&1 & -</ProgramListing> -</para> -</listitem> +<itemizedlist> <listitem> <para> Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris @@ -867,399 +524,25 @@ Then make a softlink to this file from </para> </listitem> -<listitem> -<para> -In RedHat Linux edit file /etc/inittab to add the - following as a single line: - -<programlisting> -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" -</programlisting> - - (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.) -</para> -</listitem> - </itemizedlist> </Para> -</Step> - -<Step Performance="required"> -<Para> - Run the regression tests. - The file <filename>/usr/src/pgsql/postgresql-6.5.3/src/test/regress/README</filename> has detailed - instructions for running and interpreting the regression tests. - A short version follows here: -</Para> - -<substeps> - -<Step Performance="required"> -<Para> - Type -<ProgramListing> -$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress -$ gmake clean -$ gmake all runtest -</ProgramListing> -</Para> - -<Para> - You do not need to type <command>gmake clean</command> - if this is the first time you - are running the tests. -</Para> - -<Para> - You should get on the screen (and also written to file <filename>./regress.out</filename>) - a series of statements stating which tests passed and which tests - failed. Please note that it can be normal for some tests to - "fail" on some platforms. -The script says a test has failed if there is any difference - at all between the actual output of the test and the expected output. - Thus, tests may "fail" due to minor differences in wording of error - messages, small differences in floating-point roundoff, etc, between - your system and the regression test reference platform. - "Failures" of this type do not indicate a problem with - <ProductName>Postgres</ProductName>. - The file <filename>./regression.diffs</filename> contains the textual differences between - the actual test output on your machine and the "expected" output - (which is simply what the reference system produced). You should - carefully examine each difference listed to see whether it appears to - be a significant issue. -</Para> - -<para> -For example, - -<itemizedlist> -<listitem> -<Para> - For a i686/Linux-ELF platform, no tests failed since this is the - 6.5.3 regression testing reference platform. -</Para> </listitem> -</itemizedlist> -</para> -<Para> - Even if a test result clearly indicates a real failure, it may be a - localized problem that will not affect you. An example is that the - <type>int8</type> test will fail, producing obviously incorrect output, if your - machine and C compiler do not provide a 64-bit integer data type - (or if they do but configure didn't discover it). This is not - something to worry about unless you need to store 64-bit integers. -</Para> - -<Para> - 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 <ProductName>Postgres</ProductName>. The regression - tests are a helpful tool, but they may require some study to be useful. -</Para> - -<Para> - After running the regression tests, type - -<ProgramListing> -$ dropdb regression -$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress -$ gmake clean -</ProgramListing> - - to recover the disk space used for the tests. (You may want to save - the <filename>regression.diffs</filename> file in another place before doing this.) -</Para> -</Step> - -</substeps> -</step> -<Step Performance="required"> -<Para> - 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: -</para> -<procedure> -<title>Minimal Backup Procedure</title> - -<step performance="required"> -<para> -Run the <acronym>SQL</acronym> command <command>VACUUM</command>. -This will clean up your database. -</para> -</step> -<step performance="required"> -<para> -Back up your system. (You should probably keep the last few - backups on hand.) Preferably, no one else should be using the - system at the time. -</para> -</step> -</procedure> - -<para> - 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 <application>crontab</application> - 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.) -</Para> -</Step> - -<Step Performance="required"> -<Para> - If you are upgrading an existing system then reinstall your old database. - Type -<ProgramListing> -$ cd -$ psql -e template1 < db.out -</ProgramListing> - - If your pre-6.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) -<ProgramListing> -UPDATE <replaceable>FirstTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>); -UPDATE <replaceable>SecondTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>); -... -VACUUM; -</ProgramListing> - - 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. -</Para> -</Step> - -<Step Performance="required"> -<Para> - If you are a new user, you may wish to play with <ProductName>Postgres</ProductName> as described - below. -</Para> -</Step> - -<Step Performance="required"> +<listitem> <Para> - Clean up after yourself. Type -<ProgramListing> -$ rm -rf /usr/src/pgsql -$ rm -rf /usr/src/pgsql.old -# Also delete the old database directory tree if desired. -$ rm -rf /usr/local/pgsql.old -</ProgramListing> +Run the regression tests. The regression tests are a test suite to verify that +PostgreSQL runs on your machine in the way the developers expected it to. +You should definitely do this before putting a server into production use. +The file <filename>/usr/src/pgsql/postgresql-7.0.0/src/test/regress/README</filename> +has detailed +instructions for running and interpreting the regression tests. </Para> -</Step> - -<Step Performance="required"> -<Para> - You will probably want to print out the documentation. If you have -a Postscript printer, or have your machine already set up to accept -Postscript files using a print filter, then to print the User's Guide -simply type - -<programlisting> -$ cd /usr/local/pgsql/doc -$ gunzip user.ps.tz | lpr -</programlisting> -</para> -<para> - Here is how - you might do it if you have Ghostscript on your system and are - writing to a laserjet printer. - -<programlisting> -$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' -$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts -$ gunzip user.ps.gz -$ gshp -sOUTPUTFILE=user.hp user.ps -$ gzip user.ps -$ lpr -l -s -r manpage.hp -</programlisting> -</para> -</Step> - -<Step Performance="required"> -<Para> - The <ProductName>Postgres</ProductName> team wants - to keep <ProductName>Postgres</ProductName> working on all of the - supported platforms. We therefore ask you to let us know if you did - or did not get <ProductName>Postgres</ProductName> to work on you system. - Please send a - mail message to -<ulink url="mailto:pgsql-ports@postgresql.org">pgsql-ports@postgresql.org</ulink> - telling us the following: - -<itemizedlist> -<listitem> -<para> -The version of <ProductName>Postgres</ProductName> (6.5.3, 6.5, beta 990318, etc.). -</para> -</listitem> - -<listitem> -<para> -Your operating system (i.e. RedHat v5.1 Linux v2.0.34). -</para> -</listitem> - -<listitem> -<para> -Your hardware (SPARC, i486, etc.). -</para> -</listitem> - -<listitem> -<para> -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. -</para> </listitem> </itemizedlist> - -</Para> -</Step> - -<Step Performance="required"> -<Para> - Now create, access and manipulate databases as desired. Write client - programs to access the database server. In other words, <emphasis>enjoy</emphasis>! -</Para> -</Step> -</Procedure> -</sect1> - -<Sect1> -<Title>Playing with <ProductName>Postgres</ProductName></Title> - -<Para> -After <ProductName>Postgres</ProductName> is installed, a database system is created, a postmaster -daemon is running, and the regression tests have passed, you'll want to -see <ProductName>Postgres</ProductName> do something. That's easy. Invoke the interactive interface -to <ProductName>Postgres</ProductName>, <Application>psql</Application>: - -<ProgramListing> -% psql template1 -</ProgramListing> - -(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.) -</Para> - -<Para> -The response from psql is: - -<ProgramListing> -Welcome to the POSTGRESQL interactive sql monitor: - Please read the file COPYRIGHT for copyright terms of POSTGRESQL - - 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=> -</ProgramListing> -</Para> - -<Para> -Create the database foo: - -<ProgramListing> -template1=> create database foo; -CREATE DATABASE -</ProgramListing> - -(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.) -</Para> - -<Para> -Now connect to the new database: - -<ProgramListing> -template1=> \c foo -connecting to new database: foo -</ProgramListing> - -("slash" commands aren't SQL, so no semicolon. Use \? to see all the slash commands.) -</Para> - -<Para> -And create a table: - -<ProgramListing> -foo=> create table bar (i int4, c char(16)); -CREATE -</ProgramListing> -</Para> - -<Para> -Then inspect the new table: - -<ProgramListing> -foo=> \d bar - -Table = bar -+----------------------------------+----------------------------------+-------+ -| Field | Type | Length| -+----------------------------------+----------------------------------+-------+ -| i | int4 | 4 | -| c | (bp)char | 16 | -+----------------------------------+----------------------------------+-------+ -</ProgramListing> -</Para> - -<Para> -And so on. You get the idea. -</Para> -</Sect1> - -<Sect1> -<Title>The Next Step</Title> - -<Para> -Questions? Bugs? Feedback? -First, read the files in directory <filename>/usr/src/pgsql/postgresql-6.5.3/doc/</filename>. -The FAQ in this directory may be particularly useful. -</Para> - -<Para> -If <ProductName>Postgres</ProductName> failed to compile on your computer -then fill out the form in file <filename>/usr/src/pgsql/postgresql-6.5.3/doc/bug.template</filename> - and mail it to the location indicated at the top of the form. -</Para> - -<Para> -Check on the web site at -<ULink url="http://www.postgresql.org">http://www.postgresql.org</ULink> -For more information on the various support mailing lists. -</Para> </Sect1> - <Sect1> - <Title>Porting Notes</Title> - - <Para> - Check for any platform-specific FAQs in the <filename>doc/</filename> directory of - the source distribution. - </Para> - </sect1> - </Chapter> <!-- Keep this comment at the end of the file diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 5f3bce4f835..19e7674b4fb 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -1,5 +1,5 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.8 2000/01/18 00:03:34 petere Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.9 2000/01/20 21:50:54 petere Exp $ Postgres documentation --> @@ -28,7 +28,6 @@ initdb [ --pgdata|-D <replaceable class="parameter">dbdir</replaceable> ] [ --pwprompt|-W ] [ --encoding|-E <replaceable class="parameter">encoding</replaceable> ] [ --pglib|-L <replaceable class="parameter">libdir</replaceable> ] - [ --username|-u <replaceable class="parameter">name</replaceable> ] [ --noclean | -n ] [ --debug | -d ] [ --template | -t ] </synopsis> @@ -122,20 +121,6 @@ initdb [ --pgdata|-D <replaceable class="parameter">dbdir</replaceable> ] </varlistentry> <varlistentry> - <term>--username=<replaceable class="parameter">name</replaceable></term> - <term>-u <replaceable class="parameter">name</replaceable></term> - <listitem> - <para> - The database system will be initialized with the username that is - running initdb. That is a requirement. If for some unimaginable - reason initdb cannot find out what the current user's name is, - you have to use this option. Normally, this will not be necessary - and initdb will tell you when it is. - </para> - </listitem> - </varlistentry> - - <varlistentry> <term>--template</term> <term>-t</term> <listitem> diff --git a/src/GNUmakefile.in b/src/GNUmakefile.in index 95a28c11142..ea65315199c 100644 --- a/src/GNUmakefile.in +++ b/src/GNUmakefile.in @@ -7,7 +7,7 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.48 2000/01/16 20:04:51 petere Exp $ +# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.49 2000/01/20 21:50:56 petere Exp $ # #------------------------------------------------------------------------- @@ -33,7 +33,7 @@ all: echo All of PostgreSQL is successfully made. Ready to install. ;\ fi -install: +install: installdirs $(MAKE) -C utils install $(MAKE) -C backend install $(MAKE) -C interfaces install @@ -41,6 +41,9 @@ install: $(MAKE) -C pl install cat ../register.txt +installdirs: mkinstalldirs + $(SRCDIR)/mkinstalldirs $(BINDIR) $(LIBDIR) $(INCLUDEDIR) + clean: $(MAKE) -C utils clean $(MAKE) -C backend clean diff --git a/src/backend/access/heap/tuptoaster.c b/src/backend/access/heap/tuptoaster.c index c351c4cc177..9176521a5fc 100644 --- a/src/backend/access/heap/tuptoaster.c +++ b/src/backend/access/heap/tuptoaster.c @@ -4,11 +4,11 @@ * Support routines for external and compressed storage of * variable size attributes. * - * Copyright (c) 2000, PostgreSQL Development Team + * Copyright (c) 2000, PostgreSQL Global Development Group * * * IDENTIFICATION - * $Header: /cvsroot/pgsql/src/backend/access/heap/tuptoaster.c,v 1.1 1999/12/21 00:06:40 wieck Exp $ + * $Header: /cvsroot/pgsql/src/backend/access/heap/tuptoaster.c,v 1.2 2000/01/20 21:50:59 petere Exp $ * * * INTERFACE ROUTINES diff --git a/src/bin/Makefile b/src/bin/Makefile index 451fab4bff3..9aaec450917 100644 --- a/src/bin/Makefile +++ b/src/bin/Makefile @@ -7,14 +7,14 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/src/bin/Makefile,v 1.24 2000/01/19 20:08:23 petere Exp $ +# $Header: /cvsroot/pgsql/src/bin/Makefile,v 1.25 2000/01/20 21:51:02 petere Exp $ # #------------------------------------------------------------------------- SRCDIR= .. include ../Makefile.global -DIRS = pg_version psql pg_dump pg_passwd \ +DIRS = pg_id pg_version psql pg_dump pg_passwd \ scripts initdb initlocation ipcclean \ pg_ctl diff --git a/src/bin/initdb/initdb.sh b/src/bin/initdb/initdb.sh index 6db416e1c1a..52a66507e8c 100644 --- a/src/bin/initdb/initdb.sh +++ b/src/bin/initdb/initdb.sh @@ -26,7 +26,7 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.81 2000/01/19 20:08:24 petere Exp $ +# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.82 2000/01/20 21:51:05 petere Exp $ # #------------------------------------------------------------------------- @@ -47,14 +47,7 @@ exit_nicely(){ CMDNAME=`basename $0` -if [ "$USER" = 'root' -o "$LOGNAME" = 'root' ] -then - echo "You cannot run $CMDNAME as root. Please log in (using, e.g., 'su')" - echo "as the (unprivileged) user that will own the server process." - exit 1 -fi -EffectiveUser=`id -n -u 2>/dev/null || whoami 2>/dev/null` if [ "$TMPDIR" ]; then TEMPFILE="$TMPDIR/initdb.$$" else @@ -95,7 +88,7 @@ else fi # Check if needed programs actually exist in path -for prog in postgres pg_version +for prog in postgres pg_version pg_id do if [ ! -x "$PGPATH/$prog" ] then @@ -109,6 +102,22 @@ do fi done + +# Gotta wait for pg_id existence check above +EffectiveUser=`$PGPATH/pg_id -n -u` +if [ -z "$EffectiveUser" ]; then + echo "Could not determine current user name. You are really hosed." + exit 1 +fi + +if [ `$PGPATH/pg_id -u` -eq 0 ] +then + echo "You cannot run $CMDNAME as root. Please log in (using, e.g., 'su')" + echo "as the (unprivileged) user that will own the server process." + exit 1 +fi + + # 0 is the default (non-)encoding MULTIBYTEID=0 # This is placed here by configure --enable-multibyte[=XXX]. @@ -124,12 +133,9 @@ template_only=0 # superuser be the same as the Unix user owning the server process: # The single user postgres backend will only connect as the database # user with the same name as the Unix user running it. That's -# a security measure. It might change in the future (why?), but for -# now the --username option is only a fallback if both id and whoami -# fail, and in that case the argument _must_ be the name of the effective -# user. +# a security measure. POSTGRES_SUPERUSERNAME="$EffectiveUser" -POSTGRES_SUPERUSERID="`id -u 2>/dev/null || echo 0`" +POSTGRES_SUPERUSERID=`$PGPATH/pg_id -u` while [ "$#" -gt 0 ] do @@ -150,17 +156,7 @@ do template_only=1 echo "Updating template1 database only." ;; -# The database superuser. See comments above. - --username|-u) - POSTGRES_SUPERUSERNAME="$2" - shift;; - --username=*) - POSTGRES_SUPERUSERNAME=`echo $1 | sed 's/^--username=//'` - ;; - -u*) - POSTGRES_SUPERUSERNAME=`echo $1 | sed 's/^-u//'` - ;; -# The sysid of the database superuser. See comments above. +# The sysid of the database superuser. Can be freely changed. --sysid|-i) POSTGRES_SUPERUSERID="$2" shift;; @@ -284,21 +280,6 @@ then exit 1 fi -#--------------------------------------------------------------------------- -# Figure out who the Postgres superuser for the new database system will be. -#--------------------------------------------------------------------------- - -# This means they have neither 'id' nor 'whoami'! -if [ -z "$POSTGRES_SUPERUSERNAME" ] -then - echo "$CMDNAME: Could not the determine current username. Please use the -u option." - exit 1 -fi - -echo "This database system will be initialized with username \"$POSTGRES_SUPERUSERNAME\"." -echo "This user will own all the data files and must also own the server process." -echo - #------------------------------------------------------------------------- # Find the input files @@ -355,6 +336,10 @@ fi trap 'echo "Caught signal." ; exit_nicely' 1 2 3 15 +# Let's go +echo "This database system will be initialized with username \"$POSTGRES_SUPERUSERNAME\"." +echo "This user will own all the data files and must also own the server process." +echo # ----------------------------------------------------------------------- # Create the data directory if necessary diff --git a/src/bin/pg_id/Makefile b/src/bin/pg_id/Makefile new file mode 100644 index 00000000000..1801becbe56 --- /dev/null +++ b/src/bin/pg_id/Makefile @@ -0,0 +1,33 @@ +#------------------------------------------------------------------------- +# +# Makefile +# Makefile for bin/pg_id +# +# Copyright (C) 2000 by PostgreSQL Global Development Team +# +# $Header: /cvsroot/pgsql/src/bin/pg_id/Attic/Makefile,v 1.14 2000/01/20 21:51:07 petere Exp $ +# +#------------------------------------------------------------------------- + +SRCDIR= ../.. +include ../../Makefile.global + +OBJS= pg_id.o + +all: pg_id + +pg_id: $(OBJS) + $(CC) -o pg_id $(OBJS) $(LDFLAGS) + +install: pg_id + $(INSTALL) $(INSTL_EXE_OPTS) pg_id$(X) $(BINDIR)/pg_id + +depend dep: + $(CC) -MM $(CFLAGS) *.c >depend + +clean: + rm -f pg_id $(OBJS) + +ifeq (depend,$(wildcard depend)) +include depend +endif diff --git a/src/bin/pg_id/pg_id.c b/src/bin/pg_id/pg_id.c new file mode 100644 index 00000000000..fcba3b3e3c5 --- /dev/null +++ b/src/bin/pg_id/pg_id.c @@ -0,0 +1,91 @@ +/* + * pg_id.c + * + * A crippled id utility for use in various shell scripts in use by PostgreSQL + * (in particular initdb) + * + * Copyright (C) 2000 by PostgreSQL Global Development Group + * + * $Header: /cvsroot/pgsql/src/bin/pg_id/Attic/pg_id.c,v 1.11 2000/01/20 21:51:07 petere Exp $ + */ +#include <c.h> + +#include <pwd.h> +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +#include <sys/types.h> + +int main(int argc, char * argv[]) +{ + int c; + int nameflag = 0, + realflag = 0, + userflag = 0; + const char * username = NULL; + + struct passwd * pw; + + while ((c = getopt(argc, argv, "nru")) != -1) + { + switch(c) + { + case 'n': + nameflag = 1; + break; + case 'r': + realflag = 1; + break; + case 'u': + userflag = 1; + break; + default: + fprintf(stderr, "Usage: %s [-n] [-r] [-u] [username]\n", argv[0]); + exit(1); + } + } + + if (argc - optind >= 1) + username = argv[optind]; + + if (nameflag && !userflag) + { + fprintf(stderr, "%s: -n must be used together with -u\n", argv[0]); + exit(1); + } + if (username && realflag) + { + fprintf(stderr, "%s: -r cannot be used when a user name is given\n", argv[0]); + exit(1); + } + + + if (username) + { + pw = getpwnam(username); + if (!pw) + { + fprintf(stderr, "%s: %s: no such user\n", argv[0], username); + exit(1); + } + } + else if (realflag) + pw = getpwuid(getuid()); + else + pw = getpwuid(geteuid()); + + if (!pw) + { + perror(argv[0]); + exit(1); + } + + if (!userflag) + printf("uid=%d(%s)\n", (int)pw->pw_uid, pw->pw_name); + else if (nameflag) + puts(pw->pw_name); + else + printf("%d\n", (int)pw->pw_uid); + + return 0; +} diff --git a/src/bin/psql/copy.c b/src/bin/psql/copy.c index 8f46e65b4c3..140aa983fa6 100644 --- a/src/bin/psql/copy.c +++ b/src/bin/psql/copy.c @@ -3,7 +3,7 @@ * * Copyright 2000 by PostgreSQL Global Development Team * - * $Header: /cvsroot/pgsql/src/bin/psql/copy.c,v 1.6 2000/01/18 23:30:23 petere Exp $ + * $Header: /cvsroot/pgsql/src/bin/psql/copy.c,v 1.7 2000/01/20 21:51:09 petere Exp $ */ #include <c.h> #include "copy.h" @@ -423,7 +423,10 @@ handleCopyIn(PGconn *conn, FILE *copystream, const char *prompt) if (firstload) { if (!strcmp(copybuf, "\\.")) + { copydone = true; + break; + } firstload = false; } } diff --git a/src/mkinstalldirs b/src/mkinstalldirs new file mode 100755 index 00000000000..cc8783edce3 --- /dev/null +++ b/src/mkinstalldirs @@ -0,0 +1,36 @@ +#! /bin/sh +# mkinstalldirs --- make directory hierarchy +# Author: Noah Friedman <friedman@prep.ai.mit.edu> +# Created: 1993-05-16 +# Last modified: 1994-03-25 +# Public domain + +errstatus=0 + +for file in ${1+"$@"} ; do + set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'` + shift + + pathcomp= + for d in ${1+"$@"} ; do + pathcomp="$pathcomp$d" + case "$pathcomp" in + -* ) pathcomp=./$pathcomp ;; + esac + + if test ! -d "$pathcomp"; then + echo "mkdir $pathcomp" 1>&2 + mkdir "$pathcomp" > /dev/null 2>&1 || lasterr=$? + fi + + if test ! -d "$pathcomp"; then + errstatus=$lasterr + fi + + pathcomp="$pathcomp/" + done +done + +exit $errstatus + +# mkinstalldirs ends here |