Complete installation instructions for Postgres v6.4. Before installing Postgres, you may wish to visit www.postgresql.org for up to date information, patches, etc. The installation notes below assume the following (except where noted): Commands are Unix-compatible. See note below. Defaults are used except where noted. User postgres is the Postgres superuser. The source path is /usr/src/pgsql (other paths are possible). The runtime path is /usr/local/pgsql (other paths are possible). Commands were tested on RedHat Linux version 4.2 using the tcsh shell. Except where noted, they will probably work on most systems. Commands like ps and tar vary wildly on what options you should use on each platform. Use common sense before typing in these commands. Our Makefiles require GNU make (called gmake in this document). They will not work with non-GNU make programs. If you have GNU make installed under the name make instead of gmake, that's OK, but you need to have it. Information on supported platforms is in another chapter. In general, most Unix-compatible platforms with modern libraries should be able to run Postgres. You should have at least 8 MB of memory and at least 45 MB of disk space to hold the source, binaries, and user databases. After installation you may reduce this to about 3 Mbytes plus space for user databases. For a fresh install or upgrading from previous releases of Postgres: 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. Create account postgres if it does not already exist. Log into account postgres. Check that you have sufficient disk space. You will need about 17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql (excluding your database) and 1 Mbyte for an empty database. 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. Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the Internet. Store it in your home directory. 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. To install it, type the following: cd gunzip -c flex-2.5.4.tar.gz | tar xvf - cd flex-2.5.4 configure --prefix=/usr make make check # You must be root when typing the next line. make install cd rm -rf flex-2.5.4 This will update files /usr/man/man1/flex.1, /usr/bin/flex, /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link /usr/bin/flex++ which points to flex. If you are upgrading an existing system then back up your database. For alpha- and beta-level releases, the database format is liable to change often every few weeks with no notice besides a quick comment in the HACKERS mailing list. Full releases always require a dump/reload from previous releases. It is therefore a bad idea to skip this step. Also, do not use the pg_dumpall script from v6.0 or everything will be owned by the Postgres super user. Type (with the gunzip line and the following line typed as one line): cd gunzip -c postgresql-v6.4.tar.gz | tar xvf - src/bin/pg_dump/pg_dumpall chmod a+x src/bin/pg_dump/pg_dumpall src/bin/pg_dump/pg_dumpall > db.out rm -rf src If you wish to preserve object id's (oids), then use the -o option when running pg_dumpall. However, unless you have a special reason for doing this, don't do it. If the pg_dumpall command seems to take a long time and you think it might have died, then, from another terminal, use "ls -l db.out" several times to see if the size of the file is growing. Please note that if you are upgrading from a version prior to Postgres95 v1.09 then you must back up your database, install Postgres95 v1.09, restore your database, then back it up again. You should also read files /usr/src/pgsql/migration/*. You must make sure that your database is not updated in the middle of your backup. If necessary, bring down postmaster, edit the permissions in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring postmaster back up. If you are upgrading an existing system then kill the postmaster. Type ps -ax | grep postmaster This should list the process numbers for a number of processes. Type the following line, with "???" replaced by the process id for process "postmaster". (Do not use the id for process "grep postmaster".) Type kill ??? with "???" modified as indicated. 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. Make new source and install directories. The actual paths can be different for your installation; be consistant throughout this procedure. Type su cd /usr/src mkdir pgsql chown postgres:postgres pgsql cd /usr/local mkdir pgsql chown postgres:postgres pgsql exit Unzip and untar the new source file. Type cd /usr/src/pgsql gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf - 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 as described below ] 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. (If you have to do this, please send email to scrappy@hub.org stating the output of the program './config.guess' and what the template file should be.) 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-pgport=PORT Sets the port that the postmaster process listens for incoming connections on. The default is port 5432. --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.) As an example, here is the configure script I use on a Sparc Solaris 2.5 system with /opt/postgres being the install base. ./configure --prefix=/opt/postgres \ --with-template=sparc_solaris-gcc --with-pgport=5432 \ --enable-hba --disable-locale Of course, in a real shell, you would type these three lines all on the same line. Compile the program. Type cd /usr/src/pgsql/src gmake all >& make.log & tail -f make.log The last line displayed will hopefully be "All of PostgreSQL is successfully made. Ready to install." At this point, or earlier if you wish, type control-C to get out of tail. (If you have problems later on you may wish to examine file make.log for warning and error messages.) If your computer does not have gmake (GNU make) then try running make instead throughout the rest of these notes. Please note that you will probably find a number of warning messages in make.log. Unless you have problems later on, these messages may be safely ignored. If the compiler fails with an error stating that the flex command cannot be found then install flex as described earlier. Next, change directory back to this directory, type "make clean", then recompile again. 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. Install the program. Type cd /usr/src/pgsql/src gmake install >& make.install.log & tail -f make.install.log The last line displayed will be "gmake[1]: Leaving directory `/usr/src/pgsql/src/man'". At this point, or earlier if you wish, type control-C to get out of tail. 14) If necessary, tell UNIX how to find your shared libraries. You can do ONE of the following, preferably the first: As root, edit file /etc/ld.so.conf. Add line /usr/local/pgsql/lib to the file. Then run command /sbin/ldconfig. In a bash shell, type export LD_LIBRARY_PATH=/usr/local/pgsql/lib 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. If it has not already been done, then prepare account postgres for using Postgres. Any account that will use Postgres must be similarily prepared. (The following instructions are for a bash shell. Adapt accordingly for other shells.) Add the following lines to your login shell, ~/.bash_profile: PATH=$PATH:/usr/local/pgsql/bin MANPATH=$MANPATH:/usr/local/pgsql/man PGLIB=/usr/local/pgsql/lib PGDATA=/usr/local/pgsql/data export PATH MANPATH PGLIB PGDATA Make sure that you have defined these variables before continuing with the remaining steps. The easiest way to do this is to type: source ~/.bash_profile Create the database. Do not do the following as root! This would be a major security hole. Type initdb 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. Start the postmaster daemon running. Type cd nohup postmaster > server.log 2>&1 & Run postmaster from your Postgres super user account (typically account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT. Run the regression tests. (You can skip this step if you wish, but we think skipping the tests is a BAD idea!) The file /usr/src/pgsql/src/test/regress/README has detailed instructions for running and interpreting the regression tests. A short version follows here: Type cd /usr/src/pgsql/src/test/regress gmake clean gmake all runtest You do not need to type "gmake clean" if this is the first time you are running the tests. You should get on the screen (and also written to file ./regress.out) a series of statements stating which tests passed and which tests failed. Please note that it can be normal for some of the tests to "fail". 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 a i686/Linux-ELF platform, no tests failed since this is the v6.4 regression testing reference platform. For the SPARC/Linux-ELF platform, using the 970525 beta version of Postgres v6.2 the following tests "failed": float8 and geometry "failed" due to minor precision differences in floating point numbers. select_views produces massively different output, but the differences are due to minor floating point differences. 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 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.) If you haven't already done so, this would be a good time to modify your computer so that it will automatically start postmaster whenever you boot your computer. Here are some suggestions on how to do this, contributed by various users. Whatever you do, postmaster must be run by user postgres AND NOT BY ROOT. This is why all of the examples below start by switching user (su) to postgres. These commands also take into account the fact that environment variables like PATH and PGDATA may not be set properly. The examples are as follows. Use them with extreme caution. a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1 to contain the following single line: su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" b) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to contain the following lines and make it chmod 755 and chown root:bin. #!/bin/sh [ -x /usr/local/pgsql/bin/postmaster ] && { su -l 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. Note: Unlike most other examples, this one has been tested. c) In RedHat v4.0 Linux edit file /etc/inittab to add the following single line: pg:2345:respawn:/bin/su - postgres -c "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data >> /usr/local/pgsql/server.log 2>&1 Postgres distribution has an example init.d script compatible with and tested using recent RedHat packages. If you haven't already done so, this would be a good time to modify your computer to do regular maintainence. The following should be done at regular intervals: a) Run the SQL command vacuum. This will clean up your database. b) Back up your system. (You should probably keep the last few backups on hand.) Ideally, no one else should be using the system at the time. Ideally, the above tasks should be done by a shell script that is run nightly or weekly by cron. Look at the man page for crontab for a starting point on how to do this. (If you do it, please e-mail us a copy of your shell script. We would like to set up our own systems to do this too.) 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 YourTable set PathCol = UpgradePath(PathCol); update YourTable set PolyCol = UpgradePoly(PolyCol); ... vacuum; UpgradePath() checks to see that a path value is consistant with the old syntax, and will not update a column which fails that examination. UpgradePoly() cannot verify that a polygon is in fact from an old syntax, but RevertPoly() is provided to reverse the effects of a mis-applied upgrade. If you are a new user, you may wish to play with Postgres as described below. Clean up after yourself. Type rm -rf /usr/src/pgsql_6_0 rm -rf /usr/local/pgsql_6_0 # Also delete old database directory tree if it is not in # /usr/local/pgsql_6_0/data rm ~/postgresql-v6.2.1.tar.gz You will probably want to print out the documentation. Here is how you might do it if you have Ghostscript on your system and are writing to a laserjet printer. alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts # Print out the man pages. man -a -t /usr/local/pgsql/man/*/* > manpage.ps gshp -sOUTPUTFILE=manpage.hp manpage.ps rm manpage.ps lpr -l -s -r manpage.hp # Print out the Postgres95 User Manual, version 1.0, # Sept. 5, 1996. cd /usr/src/pgsql/doc gshp -sOUTPUTFILE=userguide.hp userguide.ps lpr -l -s -r userguide.hp If you are a developer, you will probably want to also print out the Postgres Implemention Guide, version 1.0, October 1, 1995. This is a WWW document located at http://www.postgresql.org/docs/impguide. 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 telling us the following: - The version of Postgres (v6.2.1, 6.1.1, beta 970703, etc.). - Your operating system (i.e. RedHat v4.0 Linux v2.0.26). - Your hardware (SPARC, i486, etc.). - Did you compile, install and run the regression tests cleanly? If not, what source code did you change (i.e. patches you applied, changes you made, etc.), what tests failed, etc. It is normal to get many warning when you compile. You do not need to report these. Now create, access and manipulate databases as desired. Write client programs to access the database server. In other words, ENJOY! 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. 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. Mail questions to pgsql-questions@postgresql.org. For more information on the various mailing lists, see http://www.postgresql.org and look for the mailing lists. For some ports, these notes may be out of date. You need to install the libdl-1.1 package since Ultrix 4.x doesn't have a dynamic loader. It's available in s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z Thomas G. Lockhart 1998-02-19 The regression test reference machine is a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686. The linux-elf port installs cleanly. See the Linux FAQ for more details. 1995-05-11 For non-ELF Linux, the dld library MUST be obtained and installed on the system. It enables dynamic link loading capability to the Postgres port. The dld library can be obtained from the sunsite linux distributions. The current name is dld-3.2.5. Jalon Q. Zimmerman For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library. The NeXT port for v1.09 was supplied by Tom R. Hageman. It requires a SysV IPC emulation library and header files for shared libary and semaphore stuff. Tom just happens to sell such a product so contact him for information. He has also indicated that binary releases of Postgres for NEXTSTEP will be made available to the general public. Contact Info@RnA.nl for information. We have no recent reports of successful NeXT installations (for v6.2.1). However, the client-side libraries should work even if the backend is not supported.