-POSTGRESQL INSTALLATION INSTRUCTIONS
-Copyright (c) 1997 Regents of the University of California
-
-This is file /usr/src/pgsql/INSTALL. It contains notes on how to install
-PostgreSQL v6.2. Up to date information on PostgreSQL may be found at
-http://www.postgresql.org.
-
-PostgreSQL is an RDBMS database server. It is not completely ANSI SQL
-compliant, but with each release it gets closer.
-
-PostgreSQL, formerly called Postgres95, is a derivative of Postgres 4.2
-(the last release of the UC Berkeley research project). For copyright
-terms for PostgreSQL, please see the file named COPYRIGHT. This version
-was developed by a team of developers on the postgres developers mailing
-list. Version 1 (through 1.01) was developed by Jolly Chen and Andrew
-Yu.
-
-The installation notes below assume the following (except where noted):
- - Commands are Unix-compatible. See note below.
- - Defaults are used except where noted.
- - User postgres is the postgres superuser.
- - The source path is /usr/src/pgsql (other paths are possible).
- - The runtime path is /usr/local/pgsql (other paths are possible).
-
-Commands were tested on RedHat Linux version 4.0 using the bash shell.
-Except where noted, they will probably work on most systems. Commands
-like ps and tar vary wildly on what options you should use on each
-platform. USE COMMON SENSE before typing in these commands.
-
-Our Makefiles require GNU make (called gmake in this document) and
-also assume that "install" accepts BSD options. The INSTALL
-variable in the Makefiles is set to the BSD-compatible version of
-install. On some systems, you will have to find a BSD-compatible
-install command (eg. bsdinst, which comes with the MIT X Window System
-distribution)
-
-
-REQUIREMENTS TO RUN POSTGRESQL
-------------------------------
-
-PostgreSQL has been tested on the following platforms:
-
- aix IBM on AIX 3.2.5 or 4.x
- alpha DEC Alpha AXP on Digital Unix 2.0, 3.2, 4.0
- BSD44_derived OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
- bsdi BSD/OS 2.0, 2.01, 2.1, 3.0
- dgux DG/UX 5.4R4.11
- hpux HP PA-RISC on HP-UX 9.0, 10
- i386_solaris i386 Solaris
- irix5 SGI MIPS on IRIX 5.3
- linux Intel x86 on Linux 2.0 and Linux ELF
- SPARC on Linux ELF
- PPC on Linux ELF
- (For non-ELF Linux, see LINUX_ELF below).
- sco SCO 3.2v5
- sparc_solaris SUN SPARC on Solaris 2.4, 2.5, 2.5.1
- sunos4 SUN SPARC on SunOS 4.1.3
- svr4 Intel x86 on Intel SVR4 and MIPS
- ultrix4 DEC MIPS on Ultrix 4.4
-
-PostgreSQL has known problems/bugs on the following platforms:
-
- nextstep Motorola MC68K or Intel x86 on NeXTSTEP 3.2
-
-PostgreSQL is also known to work on a number of other platforms that the
-authors have not personally tested.
-
-You should have at least 8 MB of memory and at least 45 MB of disk space
-to hold the source, binaries, and user databases. After installation
-you may reduce this to about 3 Mbytes plus space for user databases.
-
-To those doing a fresh install or upgrading from previous releases of
-PostgreSQL:
-----------------------------------------------
-
- 1) Read any last minute information and platform specific porting
- notes. There are some platform specific notes at the end of this
- file for Ultrix4.x, Linux, BSD/OS and NeXT. There are other
- files in directory /usr/src/pgsql/doc, including files FAQ-Irix
- and FAQ-Linux. Also look in directory ftp://ftp.postgresql.org/pub.
- If there is a file called INSTALL in this directory then this
- file will contain the latest installation information.
-
- Please note that a "tested" platform in the list given earlier
- simply means that someone went to the effort at some point of making
- sure that a PostgreSQL distribution would compile and run on this
- platform without modifying the code. Since the current developers
- will not have access to all of these platforms, some of them may not
- compile cleanly and pass the regression tests in the current
- release due to minor problems. Any such known problems and their
- solutions will be posted in ftp://ftp.postgresql.org/pub/INSTALL.
-
- 2) Create account postgres if it does not already exist.
-
- 3) Log into account postgres.
-
- 3a) Check that you have sufficient disk space. You will need about
- 17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
- (excluding your database) and 1 Mbyte for an empty database.
- 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 command "df -k".
-
- 4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.2.tar.gz from the
- internet. Store it in your home directory.
-
- 5) Some platforms use flex. If your system uses flex then make sure
- you have a good version. Type
- flex --version
-
- If the flex command is not found then you probably do not need it.
- If the version is 2.5.2 or 2.5.4 or greater then you are okay. If it
- is 2.5.3 or before 2.5.2 then you will have to upgrade flex. You may
- get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
-
- If you need flex and don't have it or have the wrong version, then
- you will be told so when you attempt to compile the program. Feel
- free to skip this step if you aren't sure you need it. If you do
- need it then you will be told to install/upgrade flex when you try to
- compile.
-
- To install it, type the following:
- cd
- gunzip -c flex-2.5.4.tar.gz | tar xvf -
- cd flex-2.5.4
- configure --prefix=/usr
- make
- make check
- # You must be root when typing the next line.
- make install
- cd
- rm -rf flex-2.5.4
-
- This will update files /usr/man/man1/flex.1, /usr/bin/flex,
- /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
- /usr/bin/flex++ which points to flex.
-
- 6) If you are upgrading an existing system then back up your database.
- The database format is liable to change every few weeks with no
- notice besides a quick comment in the HACKERS mailing list. 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.2.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.
-
- 7) If you are upgrading an existing system then kill the postmaster. Type
- ps -ax | grep postmaster
- This should list the process numbers for a number of processes. Type
- the following line, with "???" replaced by the process id for process
- "postmaster". (Do not use the id for process "grep postmaster".) Type
- kill ???
- with "???" modified as indicated.
-
- 8) If you are upgrading an existing system then move the old directories
- out of the way. If you are short of disk space then you may have to
- back up and delete the directories instead. If you do this, save the
- old database in the /usr/local/pgsql/data directory tree. At a
- minimum, save file /usr/local/pgsql/data/pg_hba.conf.
-
- Type the following:
- su
- cd /usr/src
- mv pgsql pgsql_6_0
- cd /usr/local
- mv pgsql pgsql_6_0
- exit
-
- If you are not using /usr/local/pgsql/data as your data directory
- (check to see if environment variable PGDATA is set to something
- else) then you will also want to move this directory in the same
- manner.
-
- 9) Make new source and install directories. The actual paths can be
- different for your installation; be consistant with your configuration
- in step (11).
- Type
- su
- cd /usr/src
- mkdir pgsql
- chown postgres:postgres pgsql
- cd /usr/local
- mkdir pgsql
- chown postgres:postgres pgsql
- exit
-
- 10) Unzip and untar the new source file. Type
- cd /usr/src/pgsql
- gunzip -c ~/postgresql-v6.2.tar.gz | tar xvf -
-
- 11) Configure the source code for your system. It is this step at which
- you can specify your actual source path and installation paths for
- the build process (see the --prefix option below). Type
- cd /usr/src/pgsql/src
+
+ PostgreSQL Installation Instructions
+
+This document describes the installation of PostgreSQL from the source code
+distribution.
+
+-------------------------------------------------------------------------------
+
+ Short Version
+
+ ./configure
+ gmake
+ su
+ gmake install
+ adduser postgres
+ mkdir /usr/local/pgsql/data
+ chown postgres /usr/local/pgsql/data
+ su - postgres
+ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data >logfile 2>&1 &
+ /usr/local/pgsql/bin/createdb test
+ /usr/local/pgsql/bin/psql test
+
+The long version is the rest of this document.
+
+-------------------------------------------------------------------------------
+
+ Requirements
+
+In general, a modern Unix-compatible platform should be able to run PostgreSQL.
+The platforms that had received specific testing at the time of release are
+listed in the Section called Supported Platforms below. In the "doc"
+subdirectory of the distribution there are several platform-specific FAQ
+documents you might wish to consult if you are having trouble.
+The following software packages are required for building PostgreSQL:
+
+ * GNU make is required; other make programs will *not* work. GNU make is
+ often installed under the name "gmake"; this document will always refer
+ to it by that name. (On some systems GNU make is the default tool with
+ the name "make".) To test for GNU make enter
+
+ gmake --version
+
+ It is recommended to use version 3.76.1 or later.
+
+ * You need an ISO/ANSI C compiler. Recent versions of GCC are
+ recommendable, but PostgreSQL is known to build with a wide variety of
+ compilers from different vendors.
+
+ * gzip is needed to unpack the distribution in the first place. If you are
+ reading this, you probably already got past that hurdle.
+
+ * The GNU Readline library (for comfortable line editing and command
+ history retrieval) will be used by default. If you don't want to use it
+ then you must specify the "--without-readline" option for "configure".
+ (On NetBSD, the "libedit" library is readline-compatible and is used if
+ "libreadline" is not found.)
+
+ * To build on Windows NT or Windows 2000 you need the Cygwin and cygipc
+ packages. See the file "doc/FAQ_MSWIN" for details.
+
+The following packages are optional. They are not required in the default
+configuration, but they are needed when certain build options are enabled, as
+explained below.
+
+ * To build the server programming language PL/Perl you need a full Perl
+ installation, including the "libperl" library and the header files. Since
+ PL/Perl will be a shared library, the "libperl" library must be a shared
+ library also on most platforms. This appears to be the default in recent
+ Perl versions, but it was not in earlier versions, and in general it is
+ the choice of whomever installed Perl at your site.
+ If you don't have the shared library but you need one, a message like
+ this will appear during the build to point out this fact:
+
+ *** Cannot build PL/Perl because libperl is not a shared library.
+ *** You might have to rebuild your Perl installation. Refer to
+ *** the documentation for details.
+
+ (If you don't follow the on-screen output you will merely notice that the
+ PL/Perl library object, "plperl.so" or similar, will not be installed.)
+ If you see this, you will have to rebuild and install Perl manually to be
+ able to build PL/Perl. During the configuration process for Perl, request
+ a shared library.
+
+ * To build the Python interface module or the PL/Python server programming
+ language, you need a Python installation, including the header files.
+ Since PL/Python will be a shared library, the "libpython" library must be
+ a shared library also on most platforms. This is not the case in a
+ default Python installation.
+ If after building and installing you have a file called "plpython.so"
+ (possibly a different extension), then everything went well. Otherwise
+ you should have seen a notice like this flying by:
+
+ *** Cannot build PL/Python because libpython is not a shared library.
+ *** You might have to rebuild your Python installation. Refer to
+ *** the documentation for details.
+
+ That means you have to rebuild (part of) your Python installation to
+ supply this shared library.
+ The catch is that the Python distribution or the Python maintainers do
+ not provide any direct way to do this. The closest thing we can offer you
+ is the information in Python FAQ 3.30. On some operating systems you
+ don't really have to build a shared library, but then you will have to
+ convince the PostgreSQL build system of this. Consult the "Makefile" in
+ the "src/pl/plpython" directory for details.
+
+ * If you want to build Tcl or Tk components (clients and the PL/Tcl
+ language) you of course need a Tcl installation.
+
+ * To build the JDBC driver, you need Ant 1.5 or higher and a JDK. Ant is a
+ special tool for building Java-based packages. It can be downloaded from
+ the Ant web site.
+ If you have several Java compilers installed, it depends on the Ant
+ configuration which one gets used. Precompiled Ant distributions are
+ typically set up to read a file ".antrc" in the current user's home
+ directory for configuration. For example, to use a different JDK than the
+ default, this may work:
+
+ JAVA_HOME=/usr/local/sun-jdk1.3
+ JAVACMD=$JAVA_HOME/bin/java
+
+ Note: Do not try to build the driver by calling "ant" or even
+ "javac" directly. This will not work. Run "gmake" normally as
+ described below.
+
+ * To enable Native Language Support (NLS), that is, the ability to display
+ a program's messages in a language other than English, you need an
+ implementation of the Gettext API. Some operating systems have this
+ built-in (e.g., Linux, NetBSD, Solaris), for other systems you can
+ download an add-on package from here: http://www.postgresql.org/~petere/
+ gettext.html. If you are using the gettext implementation in the GNU C
+ library then you will additionally need the GNU Gettext package for some
+ utility programs. For any of the other implementations you will not need
+ it.
+
+ * Kerberos, OpenSSL, or PAM, if you want to support authentication using
+ these services.
+
+If you are build from a CVS tree instead of using a released source package, or
+if you want to do development, you also need the following packages:
+
+ * Flex and Bison are needed to build a CVS checkout or if you changed the
+ actual scanner and parser definition files. If you need them, be sure to
+ get Flex 2.5.4 or later and Bison 1.50 or later. Other yacc programs can
+ sometimes be used, but doing so requires extra effort and is not
+ recommended. Other lex programs will definitely not work.
+
+If you need to get a GNU package, you can find it at your local GNU mirror site
+(see http://www.gnu.org/order/ftp.html for a list) or at ftp://ftp.gnu.org/
+gnu/.
+Also check that you have sufficient disk space. You will need about 65 MB for
+the source tree during compilation and about 15 MB for the installation
+directory. An empty database cluster takes about 25 MB, databases take about
+five times the amount of space that a flat text file with the same data would
+take. If you are going to run the regression tests you will temporarily need up
+to an extra 90 MB. Use the "df" command to check for disk space.
+
+-------------------------------------------------------------------------------
+
+ If You Are Upgrading
+
+The internal data storage format changes with new releases of PostgreSQL.
+Therefore, if you are upgrading an existing installation that does not have a
+version number "7.3.x", you must back up and restore your data as shown here.
+These instructions assume that your existing installation is under the "/usr/
+local/pgsql" directory, and that the data area is in "/usr/local/pgsql/data".
+Substitute your paths appropriately.
+
+ 1. Make sure that your database is not updated during or after the backup.
+ This does not affect the integrity of the backup, but the changed data
+ would of course not be included. If necessary, edit the permissions in
+ the file "/usr/local/pgsql/data/pg_hba.conf" (or equivalent) to disallow
+ access from everyone except you.
+
+ 2. To back up your database installation, type:
+
+ pg_dumpall > outputfile
+
+ If you need to preserve OIDs (such as when using them as foreign keys),
+ then use the "-o" option when running "pg_dumpall".
+ "pg_dumpall" does not save large objects. Check the Administrator's Guide
+ if you need to do this.
+ To make the backup, you can use the "pg_dumpall" command from the version
+ you are currently running. For best results, however, try to use the
+ "pg_dumpall" command from PostgreSQL 7.3, since this version contains
+ bug fixes and improvements over older versions. While this advice might
+ seem idiosyncratic since you haven't installed the new version yet, it is
+ advisable to follow it if you plan to install the new version in parallel
+ with the old version. In that case you can complete the installation
+ normally and transfer the data later. This will also decrease the
+ downtime.
+
+ 3. If you are installing the new version at the same location as the old one
+ then shut down the old server, at the latest before you install the new
+ files:
+
+ kill -INT `cat /usr/local/pgsql/data/postmaster.pid`
+
+ Versions prior to 7.0 do not have this "postmaster.pid" file. If you are
+ using such a version you must find out the process id of the server
+ yourself, for example by typing "ps ax | grep postmaster", and supply it
+ to the "kill" command.
+ On systems that have PostgreSQL started at boot time, there is probably a
+ start-up file that will accomplish the same thing. For example, on a Red
+ Hat Linux system one might find that
+
+ /etc/rc.d/init.d/postgresql stop
+
+ works. Another possibility is "pg_ctl stop".
+
+ 4. If you are installing in the same place as the old version then it is
+ also a good idea to move the old installation out of the way, in case you
+ have trouble and need to revert to it. Use a command like this:
+
+ mv /usr/local/pgsql /usr/local/pgsql.old
+
+After you have installed PostgreSQL 7.3, create a new database directory and
+start the new server. Remember that you must execute these commands while
+logged in to the special database user account (which you already have if you
+are upgrading).
+
+ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+
+Finally, restore your data with
+
+ /usr/local/pgsql/bin/psql -d template1 -f outputfile
+
+using the *new* psql.
+These topics are discussed at length in the Administrator's Guide, which you
+are encouraged to read in any case.
+
+-------------------------------------------------------------------------------
+
+ Installation Procedure
+
+ 1. Configuration
+ The first step of the installation procedure is to configure the source
+ tree for your system and choose the options you would like. This is done
+ by running the "configure" script. For a default installation simply
+ enter
+
./configure
- The configure program will list the template files available and
- ask you to choose one. A lot of times, an appropriate template
- file is chosen for you, and you can just press Enter to accept the
- default. If the default is not appropriate, then type in the
- appropriate template file and press Enter. (If you do this, then
- send email to scrappy@hub.org stating the output of the program
- './config.guess' and what the template file should be.)
+ This script will run a number of tests to guess values for various system
+ dependent variables and detect some quirks of your operating system, and
+ finally will create several files in the build tree to record what it
+ found. (You can also run "configure" in a directory outside the source
+ tree if you want to keep the build directory separate.)
+ The default configuration will build the server and utilities, as well as
+ all client applications and interfaces that require only a C compiler.
+ All files will be installed under "/usr/local/pgsql" by default.
+ You can customize the build and installation process by supplying one or
+ more of the following command line options to "configure":
+
+ --prefix=PREFIX
+
+ Install all files under the directory "PREFIX" instead of "/usr/
+ local/pgsql". The actual files will be installed into various
+ subdirectories; no files will ever be installed directly into the
+ "PREFIX" directory.
+ If you have special needs, you can also customize the individual
+ subdirectories with the following options.
+
+ --exec-prefix=EXEC-PREFIX
+
+ You can install architecture-dependent files under a different
+ prefix, "EXEC-PREFIX", than what "PREFIX" was set to. This can be
+ useful to share architecture-independent files between hosts. If
+ you omit this, then "EXEC-PREFIX" is set equal to "PREFIX" and both
+ architecture-dependent and independent files will be installed
+ under the same tree, which is probably what you want.
+
+ --bindir=DIRECTORY
+
+ Specifies the directory for executable programs. The default is
+ "EXEC-PREFIX/bin", which normally means "/usr/local/pgsql/bin".
+
+ --datadir=DIRECTORY
+
+ Sets the directory for read-only data files used by the installed
+ programs. The default is "PREFIX/share". Note that this has nothing
+ to do with where your database files will be placed.
+
+ --sysconfdir=DIRECTORY
+
+ The directory for various configuration files, "PREFIX/etc" by
+ default.
+
+ --libdir=DIRECTORY
+
+ The location to install libraries and dynamically loadable modules.
+ The default is "EXEC-PREFIX/lib".
+
+ --includedir=DIRECTORY
+
+ The directory for installing C and C++ header files. The default is
+ "PREFIX/include".
+
+ --docdir=DIRECTORY
+
+ Documentation files, except "man" pages, will be installed into
+ this directory. The default is "PREFIX/doc".
+
+ --mandir=DIRECTORY
+
+ The man pages that come with PostgreSQL will be installed under
+ this directory, in their respective "manx" subdirectories. The
+ default is "PREFIX/man".
+ Note: Care has been taken to make it possible to install
+ PostgreSQL into shared installation locations (such as "/usr/
+ local/include") without interfering with the namespace of the
+ rest of the system. First, the string "/postgresql" is
+ automatically appended to datadir, sysconfdir, and docdir,
+ unless the fully expanded directory name already contains the
+ string "postgres" or "pgsql". For example, if you choose "/usr/
+ local" as prefix, the documentation will be installed in "/usr/
+ local/doc/postgresql", but if the prefix is "/opt/postgres",
+ then it will be in "/opt/postgres/doc". The public C header
+ files of the client interfaces are installed into includedir
+ and are namespace-clean. The internal header files and the
+ server header files are installed into private directories
+ under includedir. See the Programmer's Guide for information
+ about how to get at the header files for each interface.
+ Finally, a private subdirectory will also be created, if
+ appropriate, under libdir for dynamically loadable modules.
+
+ --with-includes=DIRECTORIES
+
+ "DIRECTORIES" is a colon-separated list of directories that will be
+ added to the list the compiler searches for header files. If you
+ have optional packages (such as GNU Readline) installed in a non-
+ standard location, you have to use this option and probably also
+ the corresponding "--with-libraries" option.
+ Example: --with-includes=/opt/gnu/include:/usr/sup/include.
+
+ --with-libraries=DIRECTORIES
+
+ "DIRECTORIES" is a colon-separated list of directories to search
+ for libraries. You will probably have to use this option (and the
+ corresponding "--with-includes" option) if you have packages
+ installed in non-standard locations.
+ Example: --with-libraries=/opt/gnu/lib:/usr/sup/lib.
+
+ --enable-recode
+
+ Enables single-byte character set recode support. See the
+ Administrator's Guide about this feature. Note that a more general
+ form of character set conversion is supported in the default
+ configuration; this feature is obsolete.
+
+ --enable-nls[=LANGUAGES]
+
+ Enables Native Language Support (NLS), that is, the ability to
+ display a program's messages in a language other than English.
+ "LANGUAGES" is a space separated list of codes of the languages
+ that you want supported, for example --enable-nls='de fr'. (The
+ intersection between your list and the set of actually provided
+ translations will be computed automatically.) If you do not specify
+ a list, then all available translations are installed.
+ To use this option, you will need an implementation of the gettext
+ API; see above.
+
+ --with-pgport=NUMBER
+
+ Set "NUMBER" as the default port number for server and clients. The
+ default is 5432. The port can always be changed later on, but if
+ you specify it here then both server and clients will have the same
+ default compiled in, which can be very convenient. Usually the only
+ good reason to select a non-default value is if you intend to run
+ multiple PostgreSQL servers on the same machine.
+
+ --with-perl
+
+ Build the PL/Perl server-side language.
+
+ --with-python
+
+ Build the Python interface module and the PL/Python server-side
+ language. You need to have root access to be able to install the
+ Python module at its default place ("/usr/lib/pythonx.y").
+
+ --with-tcl
+
+ Build components that require Tcl/Tk, which are libpgtcl, pgtclsh,
+ pgtksh, and PL/Tcl. But see below about "--without-tk".
+
+ --without-tk
+
+ If you specify "--with-tcl" and this option, then the program that
+ requires Tk (pgtksh) will be excluded.
+
+ --with-tclconfig=DIRECTORY, --with-tkconfig=DIRECTORY
+
+ Tcl/Tk installs the files "tclConfig.sh" and "tkConfig.sh", which
+ contain configuration information needed to build modules
+ interfacing to Tcl or Tk. These files are normally found
+ automatically at their well-known locations, but if you want to use
+ a different version of Tcl or Tk you can specify the directory in
+ which to find them.
+
+ --with-java
+
+ Build the JDBC driver and associated Java packages.
+
+ --with-krb4[=DIRECTORY], --with-krb5[=DIRECTORY]
+
+ Build with support for Kerberos authentication. You can use either
+ Kerberos version 4 or 5, but not both. The "DIRECTORY" argument
+ specifies the root directory of the Kerberos installation; "/usr/
+ athena" is assumed as default. If the relevant header files and
+ libraries are not under a common parent directory, then you must
+ use the "--with-includes" and "--with-libraries" options in
+ addition to this option. If, on the other hand, the required files
+ are in a location that is searched by default (e.g., "/usr/lib"),
+ then you can leave off the argument.
+ "configure" will check for the required header files and libraries
+ to make sure that your Kerberos installation is sufficient before
+ proceeding.
+
+ --with-krb-srvnam=NAME
+
+ The name of the Kerberos service principal. postgres is the
+ default. There's probably no reason to change this.
+
+ --with-openssl[=DIRECTORY]
+
+ Build with support for SSL (encrypted) connections. This requires
+ the OpenSSL package to be installed. The "DIRECTORY" argument
+ specifies the root directory of the OpenSSL installation; the
+ default is "/usr/local/ssl".
+ "configure" will check for the required header files and libraries
+ to make sure that your OpenSSL installation is sufficient before
+ proceeding.
- Once you have entered the template file, you will be asked a
- number of questions about your particular configuration. These
- can be skipped by adding parameters to the configure command above.
- The following parameters can be tagged onto the end of the configure
- command:
+ --with-pam
- --prefix=BASEDIR Selects a different base directory for the
- installation of the PostgreSQL configuration.
- The default is /usr/local/pgsql.
+ Build with PAM (Pluggable Authentication Modules) support.
+
+ --without-readline
+
+ Prevents the use of the Readline library. This disables command-
+ line editing and history in psql, so it is not recommended.
+
+ --without-zlib
+
+ Prevents the use of the Zlib library. This disables compression
+ support in pg_dump. This option is only intended for those rare
+ systems where this library is not available.
+
+ --enable-debug
+
+ Compiles all programs and libraries with debugging symbols. This
+ means that you can run the programs through a debugger to analyze
+ problems. This enlarges the size of the installed executables
+ considerably, and on non-GCC compilers it usually also disables
+ compiler optimization, causing slowdowns. However, having the
+ symbols available is extremely helpful for dealing with any
+ problems that may arise. Currently, this option is recommended for
+ production installations only if you use GCC. But you should always
+ have it on if you are doing development work or running a beta
+ version.
+
+ --enable-cassert
+
+ Enables assertion checks in the server, which test for many "can't
+ happen" conditions. This is invaluable for code development
+ purposes, but the tests slow things down a little. Also, having the
+ tests turned on won't necessarily enhance the stability of your
+ server! The assertion checks are not categorized for severity, and
+ so what might be a relatively harmless bug will still lead to
+ server restarts if it triggers an assertion failure. Currently,
+ this option is not recommended for production use, but you should
+ have it on for development work or when running a beta version.
+
+ --enable-depend
+
+ Enables automatic dependency tracking. With this option, the
+ makefiles are set up so that all affected object files will be
+ rebuilt when any header file is changed. This is useful if you are
+ doing development work, but is just wasted overhead if you intend
+ only to compile once and install. At present, this option will work
+ only if you use GCC.
+
+ If you prefer a C compiler different from the one "configure" picks then
+ you can set the environment variable CC to the program of your choice. By
+ default, "configure" will pick "gcc" unless this is inappropriate for the
+ platform. Similarly, you can override the default compiler flags with the
+ CFLAGS variable.
+
+ You can specify environment variables on the "configure" command line,
+ for example:
+
+ ./configure CC=/opt/bin/gcc CFLAGS='-O2 -pipe'
+
+ 2. Build
+ To start the build, type
+
+ gmake
+
+ (Remember to use GNU make.) The build may take anywhere from 5 minutes to
+ half an hour depending on your hardware. The last line displayed should
+ be
+
+ All of PostgreSQL is successfully made. Ready to install.
+
+ 3. Regression Tests
+ If you want to test the newly built server before you install it, you can
+ run the regression tests at this point. The regression tests are a test
+ suite to verify that PostgreSQL runs on your machine in the way the
+ developers expected it to. Type
+
+ gmake check
+
+ (This won't work as root; do it as an unprivileged user.) It is possible
+ that some tests fail, due to differences in error message wording or
+ floating point results. The file "src/test/regress/README" and the
+ Administrator's Guide contain detailed information about interpreting the
+ test results. You can repeat this test at any later time by issuing the
+ same command.
+
+ 4. Installing The Files
+ Note: If you are upgrading an existing system and are going to
+ install the new files over the old ones, then you should have
+ backed up your data and shut down the old server by now, as
+ explained in the Section called If You Are Upgrading above.
+ To install PostgreSQL enter
+
+ gmake install
+
+ This will install files into the directories that were specified in step
+ 1. Make sure that you have appropriate permissions to write into that
+ area. Normally you need to do this step as root. Alternatively, you could
+ create the target directories in advance and arrange for appropriate
+ permissions to be granted.
+ You can use gmake install-strip instead of gmake install to strip the
+ executable files and libraries as they are installed. This will save some
+ space. If you built with debugging support, stripping will effectively
+ remove the debugging support, so it should only be done if debugging is
+ no longer needed. install-strip tries to do a reasonable job saving
+ space, but it does not have perfect knowledge of how to strip every
+ unneeded byte from an executable file, so if you want to save all the
+ disk space you possibly can, you will have to do manual work.
+ If you built the Python interfaces and you were not the root user when
+ you executed the above command then that part of the installation
+ probably failed. In that case you should become the root user and then do
+
+ gmake -C src/interfaces/python install
+
+ If you do not have superuser access you are on your own: you can still
+ take the required files and place them in other directories where Python
+ can find them, but how to do that is left as an exercise.
+ The standard installation provides only the header files needed for
+ client application development. If you plan to do any server-side program
+ development (such as custom functions or data types written in C), then
+ you may want to install the entire PostgreSQL include tree into your
+ target include directory. To do that, enter
+
+ gmake install-all-headers
+
+ This adds a megabyte or two to the installation footprint, and is only
+ useful if you don't plan to keep the whole source tree around for
+ reference. (If you do, you can just use the source's include directory
+ when building server-side software.)
+ Client-only installation: If you want to install only the client
+ applications and interface libraries, then you can use these commands:
+
+ gmake -C src/bin install
+ gmake -C src/include install
+ gmake -C src/interfaces install
+ gmake -C doc install
+
+Uninstallation: To undo the installation use the command "gmake uninstall".
+However, this will not remove any created directories.
+Cleaning: After the installation you can make room by removing the built files
+from the source tree with the command "gmake clean". This will preserve the
+files made by the configure program, so that you can rebuild everything with
+"gmake" later on. To reset the source tree to the state in which it was
+distributed, use "gmake distclean". If you are going to build for several
+platforms from the same source tree you must do this and re-configure for each
+build.
+If you perform a build and then discover that your configure options were
+wrong, or if you change anything that configure investigates (for example,
+software upgrades), then it's a good idea to do "gmake distclean" before
+reconfiguring and rebuilding. Without this, your changes in configuration
+choices may not propagate everywhere they need to.
+
+-------------------------------------------------------------------------------
+
+ Post-Installation Setup
+
+Shared Libraries
+
+On some systems that have shared libraries (which most systems do) you need to
+tell your system how to find the newly installed shared libraries. The systems
+on which this is *not* necessary include BSD/OS, FreeBSD, HP-UX, IRIX, Linux,
+NetBSD, OpenBSD, Tru64 UNIX (formerly Digital UNIX), and Solaris.
+The method to set the shared library search path varies between platforms, but
+the most widely usable method is to set the environment variable
+LD_LIBRARY_PATH like so: In Bourne shells ("sh", "ksh", "bash", "zsh")
+
+ LD_LIBRARY_PATH=/usr/local/pgsql/lib
+ export LD_LIBRARY_PATH
+
+or in "csh" or "tcsh"
+
+ setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
+
+Replace /usr/local/pgsql/lib with whatever you set "--libdir" to in step 1. You
+should put these commands into a shell start-up file such as "/etc/profile" or
+"~/.bash_profile". Some good information about the caveats associated with this
+method can be found at http://www.visi.com/~barr/ldpath.html.
+On some systems it might be preferable to set the environment variable
+LD_RUN_PATH *before* building.
+On Cygwin, put the library directory in the PATH or move the ".dll" files into
+the "bin/" directory.
+If in doubt, refer to the manual pages of your system (perhaps "ld.so" or
+"rld"). If you later on get a message like
+
+ psql: error in loading shared libraries
+ libpq.so.2.1: cannot open shared object file: No such file or directory
- --enable-hba Enables Host Based Authentication (DEFAULT)
+then this step was necessary. Simply take care of it then.
+If you are on BSD/OS, Linux, or SunOS 4 and you have root access you can run
- --disable-hba Disables Host Based Authentication
+ /sbin/ldconfig /usr/local/pgsql/lib
- --enable-locale Enables USE_LOCALE
+(or equivalent directory) after installation to enable the run-time linker to
+find the shared libraries faster. Refer to the manual page of "ldconfig" for
+more information. On FreeBSD, NetBSD, and OpenBSD the command is
- --disable-locale Disables USE_LOCALE (DEFAULT)
+ /sbin/ldconfig -m /usr/local/pgsql/lib
- --enable-cassert Enables ASSERT_CHECKING
+instead. Other systems are not known to have an equivalent command.
- --disable-cassert Disables ASSERT_CHECKING (DEFAULT)
+-------------------------------------------------------------------------------
- --with-template=TEMPLATE
- Use template file TEMPLATE - the template
- files are assumed to be in the directory
- src/template, so look there for proper values.
- (If the configure script cannot find the
- specified template file, it will ask you for
- one).
+Environment Variables
- --with-pgport=PORT Sets the port that the postmaster process
- listens for incoming connections on. The
- default for this is port 5432.
+If you installed into "/usr/local/pgsql" or some other location that is not
+searched for programs by default, you should add "/usr/local/pgsql/bin" (or
+whatever you set "--bindir" to in step 1) into your PATH. Strictly speaking,
+this is not necessary, but it will make the use of PostgreSQL much more
+convenient.
+To do this, add the following to your shell start-up file, such as
+"~/.bash_profile" (or "/etc/profile", if you want it to affect every user):
- As an example, here is the configure script I use on a Sparc
- Solaris 2.5 system with /opt/postgres being the install base.
+ PATH=/usr/local/pgsql/bin:$PATH
+ export PATH
- % ./configure --prefix=/opt/postgres
- --with-template=sparc_solaris-gcc --with-pgport=5432
- --enable-hba --disable-locale
+If you are using "csh" or "tcsh", then use this command:
- Of course, in a real shell, you would type these three lines all
- on the same line.
+ set path = ( /usr/local/pgsql/bin $path )
- 12) Compile the program. Type
- cd /usr/src/pgsql/src
- gmake all >& make.log &
- tail -f make.log
+To enable your system to find the man documentation, you need to add a line
+like the following to a shell start-up file unless you installed into a
+location that is searched by default.
- 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.)
+ MANPATH=/usr/local/pgsql/man:$MANPATH
+ export MANPATH
- If your computer does not have gmake (GNU make) then try running
- make instead throughout the rest of these notes.
+The environment variables PGHOST and PGPORT specify to client applications the
+host and port of the database server, overriding the compiled-in defaults. If
+you are going to run client applications remotely then it is convenient if
+every user that plans to use the database sets PGHOST. This is not required,
+however: the settings can be communicated via command line options to most
+client programs.
- Please note that you will probably find a number of warning
- messages in make.log. Unless you have problems later on, these
- messages may be safely ignored.
+-------------------------------------------------------------------------------
- If the compiler fails with an error stating that the flex command
- cannot be found then install flex as described earlier. Next,
- change directory back to this directory, type "make clean", then
- recompile again.
-
- 13) Install the program. Type
- cd /usr/src/pgsql/src
- gmake install >& make.install.log &
- tail -f make.install.log
-
- The last line displayed will be "gmake[1]: Leaving directory
- `/usr/src/pgsql/src/man'". At this point, or earlier if you wish,
- type control-C to get out of tail.
-
- 14) If necessary, tell UNIX how to find your shared libraries. If you
- are using Linux-ELF do ONE of the following, preferably the first:
-
- a) As root, edit file /etc/ld.so.conf. Add line
- /usr/local/pgsql/lib
- to the file. Then run command /sbin/ldconfig.
-
- b) In a bash shell, type
- export LD_LIBRARY_PATH=/usr/local/pgsql/lib
-
- c) In a csh shell, type
- setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
-
- Please note that the above commands may vary wildly for different
- operating systems. Check the platform specific notes, such as
- those for Ultrix4.x or and for non-ELF Linux.
-
- If, when you create the database, you get the message "pg_id: can't
- load library 'libpq.so'" then the above step was necessary. Simply
- do this step, then try to create the database again.
-
- 15) If it has not already been done, then prepare account postgres
- for using PostgreSQL. Any account that will use PostgreSQL must
- be similarily prepared. (The following instructions are for a
- bash shell. Adapt accordingly for other shells.)
-
- Add the following lines to your login shell, ~/.bash_profile:
- PATH=$PATH:/usr/local/pgsql/bin
- MANPATH=$MANPATH:/usr/local/pgsql/man
- PGLIB=/usr/local/pgsql/lib
- PGDATA=/usr/local/pgsql/data
- export PATH MANPATH PGLIB PGDATA
-
- Make sure that you have defined these variables before continuing
- with the remaining steps. The easiest way to do this is to type:
- source ~/.bash_profile
-
- 16) Create the database. DO NOT DO THE FOLLOWING AS ROOT! This would
- be a major security hole. Type
- initdb
-
- 17) Set up permissions to access the database system. Do this by editing
- file /usr/local/pgsql/data/pg_hba.conf. The instructions are
- included in the file. (If your database is not located in the
- default location, i.e. if PGDATA is set to point elsewhere, then the
- location of this file will change accordingly.) This file should be
- made read only again once you are finsihed.
-
- If you are upgrading from v6.0 you can copy file pg_hba.conf from
- your old database on top of the one in your new database, rather than
- redoing this from scratch.
-
- 18) If you wish to skip the regression tests then skip to step 21.
- However, 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:
-
- Start the postmaster in preparation for the regression tests. First,
- set the timezone for Berkeley, California. On some systems you may do
- this by setting environment variable TZ. I.e., using bash, type
- export TZ=PST8PDT
-
- Now start the postmaster daemon running in the background by typing
- cd
- nohup postmaster > regress.log 2>&1 &
-
- Run postmaster from your postgres super user account (typically
- account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
-
- 19) Run the regression tests. Type
-
- cd /usr/src/pgsql/src/test/regress
- gmake clean
- gmake all runtest
-
- You do not need to type "gmake clean" if this is the first time you
- are running the tests.
-
- You should get on the screen (and also written to file ./regress.out)
- a series of statements stating which tests passed and which tests
- failed. Please note that it can be normal for some of the tests to
- "fail". For the failed tests, use diff to compare the files in
- directories ./results and ./expected. If float8 failed, type
- something like:
- cd /usr/src/pgsql/src/test/regress
- diff -w expected/float8.out results
-
- "Failed" tests may have failed due to slightly different error messages,
- output formatting, failure to set the timezone correctly for your
- platform, etc. "Failures" of this type do not indicate a problem with
- PostgreSQL.
-
- Here is an example from a i686/Linux-ELF platform (this is the platform
- on which most of the regression tests were generated). No tests failed
- since this is the v6.2 regression reference platform.
-
- Here is an example from the SPARC/Linux-ELF platform. Using the
- 970525 beta version of PostgreSQL v6.2 the following tests "failed".
- float8 and geometry "failed" due to minor precision differences in
- floating point numbers. select_views produces massively different output,
- but the differences are due to minor floating point differences.
-
- Conclusion? If you do see failures, try to understand the nature of
- the differences and then decide if those differences will affect your
- intended use of PostgreSQL. However, keep in mind that this is likely
- to be the most solid release of PostgreSQL to date, incorporating many
- bug fixes from v6.0, and that previous versions of PostgreSQL have been
- in use successfully for some time now.
-
- After running the tests, type
- destroydb regression
- cd /usr/src/pgsql/src/test/regress
- gmake clean
-
- 20) Stop the postmaster as described in step 7. Then restore the
- timezone to it's normal setting. If you changed the timezone by
- modifying environment variable TZ then one way to do this is to
- log out of, then back into, account postgres.
-
- 21) Start the postmaster daemon running. Type
- cd
- nohup postmaster > server.log 2>&1 &
- Run postmaster from your postgres super user account (typically
- account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
-
- 22) If you haven't already done so, this would be a good time to modify
- your computer so that it will automatically start postmaster whenever
- you boot your computer.
-
- Here are some suggestions on how to do this, contributed by various
- users.
-
- Whatever you do, postmaster must be run by user postgres, AND NOT BY
- ROOT. This is why all of the examples below start by switching user
- (su) to postgres. These commands also take into account the fact
- that environment variables like PATH and PGDATA may not be set properly.
-
- The examples are as follows. Use them with extreme caution.
-
- a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
- 2.5.1 to contain the following single line:
- su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
- /usr/local/pgsql/data"
-
- b) In RedHat v4.0 Linux edit file /etc/inittab to contain the
- following single line:
- pg:2345:respawn:/bin/su - postgres -c
- "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
- >> /usr/local/pgsql/server.log 2>&1" /dev/null
- (The author of this example says this example will revive the
- postmaster if it dies, but he doesn't know if there are other side
- effects.)
-
- c) 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 the
- other examples, this one has been tested.
-
- d) In RedHat v4.0 Linux create file /etc/rc.d/init.d/postgres.init to
- contain the following single line:
- su -c "cd ~postgres; nohup /usr/local/pgsql/bin/postmaster
- -D /usr/local/pgsql/data > server.log 2>&1 &" postgres
- Next, type the following:
- cd /etc/rc3.d
- ln -s ../init.d/postgres.init S1000postgres
- Change "1000" to a number of your choice to indicate the
- loading order of the various programs pointed to in directory
- /etc/rc3.d. (Note that this example has not been tested yet.)
-
- 22a) If you haven't already done so, this would be a good time to modify
- your computer to do regular maintainence. The following should be
- done at regular intervals:
-
- a) Run the SQL command vacuum. This will clean up your database.
- b) Back up your system. (You should probably keep the last few
- backups on hand.) Ideally, no one else should be using the
- system at the time.
-
- Ideally, the above tasks should be done by a shell script that is
- run nightly or weekly by cron. Look at the man page for crontab
- for a starting point on how to do this. (If you do it, please
- e-mail us a copy of your shell script. We would like to set up
- our own systems to do this too.)
-
- 23) If you are upgrading an existing system then install your old database.
- Type
- cd
- psql -e template1 < db.out
-
- If your old database uses either path or polygon geometric data types,
- then you will need to upgrade any columns containing those types. To
- do so, type (from within psql)
- update YourTable set PathCol = UpgradePath(PathCol);
- update YourTable set PolyCol = UpgradePoly(PolyCol);
- ...
- vacuum;
-
- UpgradePath() checks to see that a path value is consistant with the
- old syntax, and will not update a column which fails that examination.
- UpgradePoly() cannot verify that a polygon is in fact from an old
- syntax, but RevertPoly() is provided to reverse the effects of a
- mis-applied upgrade.
-
- 24) If you are a new user, you may wish to play with postgres as described
- below.
-
- 25) Clean up after yourself. Type
- rm -rf /usr/src/pgsql_6_0
- rm -rf /usr/local/pgsql_6_0
- # Also delete old database directory tree if it is not in
- # /usr/local/pgsql_6_0/data
- rm ~/postgresql-v6.2.tar.gz
-
- 26) You will probably want to print out the documentation. Here is how
- you might do it if you have Ghostscript on your system and are
- writing to a laserjet printer.
- alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
- export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
- # Print out the man pages.
- man -a -t /usr/local/pgsql/man/*/* > manpage.ps
- gshp -sOUTPUTFILE=manpage.hp manpage.ps
- rm manpage.ps
- lpr -l -s -r manpage.hp
- # Print out the Postgres95 User Manual, version 1.0,
- # Sept. 5, 1996.
- cd /usr/src/pgsql/doc
- gshp -sOUTPUTFILE=userguide.hp userguide.ps
- lpr -l -s -r userguide.hp
-
- If you are a developer, you will probably want to also print out
- the Postgres Implemention Guide, version 1.0, October 1, 1995.
- This is a WWW document located at
- http://www.postgresql.org/docs/impguide.
-
- 27) The Postgres team wants to keep PostgreSQL working on all of the
- supported platforms. We therefore ask you to let us know if you did
- or did not get PostgreSQL to work on you system. Please send a
- mail message to pgsql-ports@postgresql.org telling us the following:
- - The version of PostgreSQL (v6.2, 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.
-
- 28) Now create, access and manipulate databases as desired. Write client
- programs to access the database server. In other words, ENJOY!
-
-
-PLAYING WITH POSTGRESQL
------------------------
-
-After PostgreSQL is installed, a database system is created, a postmaster
-daemon is running, and the regression tests have passed, you'll want to
-see PostgreSQL do something. That's easy. Invoke the interactive interface
-to PostgreSQL, psql, and start typing SQL:
-
- $ psql template1
-
-(psql has to open a particular database, but at this point the only one
-that exists is the template1 database, which always exists. We will connect
-to it only long enough to create another one and switch to it).
-
-The response from psql is:
-
- type \? for help on slash commands
- type \q to quit
- type \g or terminate with semicolon to execute query
-You are currently connected to the database: template1
-
-template1=>
-
-Create the database foo:
-
-template1=> CREATE DATABASE FOO;
-INSERT 773248
-
-(Get in the habit of including those SQL semicolons. Psql won't execute
-anything until it sees the semicolon or a "\g" and the semicolon is required
-to delimit multiple statements.)
-
-template1=> \c foo
-closing connection to database: template1
-connecting to new database: foo
-
-(\ commands aren't SQL, so no semicolon. Use \? to see all the \ commands.)
-
-foo=> CREATE TABLE bar (column1 int4, column2 char16);
-CREATE
-
-foo=> \d bar
-
-...
-
-You get the idea.
-
-
-QUESTIONS? BUGS? FEEDBACK?
-----------------------------
-
-First, read the files in directory /usr/src/pgsql/doc. The FAQ in
-this directory may be particularly useful.
-
-If PostgreSQL failed to compile on your computer then fill out the form
-in file /usr/src/pgsql/doc/bug.template and mail it to the location
-indicated at the top of the form.
-
-Mail questions to pgsql-questions@postgresql.org. For more information
-on the various mailing lists, see http://www.postgresql.org under mailing
-lists.
-
-
-----------------------------------------------------------------------
-
-Porting Notes (these notes may be out of date):
--------------
+ Getting Started
-Ultrix4.x:
- You need to install the libdl-1.1 package since Ultrix 4.x doesn't
- have a dynamic loader. It's available in
- s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
+The following is a quick summary of how to get PostgreSQL up and running once
+installed. The Administrator's Guide contains more information.
-Linux:
- The linux-elf port installs cleanly. If you are using an
- i486 processor or higher, you can edit template/linux-elf
- to include "-m486" as a compiler option. configure does not
- detect that sigsetjmp() is available, but you can edit
- include/config.h after running configure and before running
- make to include "#define HAVE_SIGSETJMP 1". Note that I have
- not seen any difference in PostgreSQL behavior either way.
- (Thomas G. Lockhart
- <Thomas.Lockhart@jpl.nasa.gov> 97/05/17)
+ 1. Create a user account for the PostgreSQL server. This is the user the
+ server will run as. For production use you should create a separate,
+ unprivileged account ("postgres" is commonly used). If you do not have
+ root access or just want to play around, your own user account is enough,
+ but running the server as root is a security risk and will not work.
- 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
- <sneaker@powergrid.electriciti.com> 5/11/95)
+ adduser postgres
-BSD/OS:
- For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
+ 2. Create a database installation with the "initdb" command. To run "initdb"
+ you must be logged in to your PostgreSQL server account. It will not work
+ as root.
-NeXT:
- The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
- It requires a SysV IPC emulation library and header files for
- shared libary and semaphore stuff. Tom just happens to sell such
- a product so contact him for information. He has also indicated that
- binary releases of PostgreSQL for NEXTSTEP will be made available to
- the general public. Contact Info@RnA.nl for information.
+ root# mkdir /usr/local/pgsql/data
+ root# chown postgres /usr/local/pgsql/data
+ root# su - postgres
+ postgres$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
+
+ The "-D" option specifies the location where the data will be stored. You
+ can use any path you want, it does not have to be under the installation
+ directory. Just make sure that the server account can write to the
+ directory (or create it, if it doesn't already exist) before starting
+ "initdb", as illustrated here.
+
+ 3. The previous step should have told you how to start up the database
+ server. Do so now. The command should look something like
+
+ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
+
+ This will start the server in the foreground. To put the server in the
+ background use something like
+
+ nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
+ </dev/null >>server.log 2>&1 </dev/null &
+
+ To stop a server running in the background you can type
+
+ kill `cat /usr/local/pgsql/data/postmaster.pid`
+
+ In order to allow TCP/IP connections (rather than only Unix domain socket
+ ones) you need to pass the "-i" option to "postmaster".
+
+ 4. Create a database:
+
+ createdb testdb
+
+ Then enter
+
+ psql testdb
+
+ to connect to that database. At the prompt you can enter SQL commands and
+ start experimenting.
+
+-------------------------------------------------------------------------------
+
+ What Now?
+
+ * The PostgreSQL distribution contains a comprehensive documentation set,
+ which you should read sometime. After installation, the documentation can
+ be accessed by pointing your browser to "/usr/local/pgsql/doc/html/
+ index.html", unless you changed the installation directories.
+ The Tutorial should be your first reading if you are completely new to
+ SQL databases. If you are familiar with database concepts then you want
+ to proceed with the Administrator's Guide, which contains information
+ about how to set up the database server, database users, and
+ authentication.
+
+ * Usually, you will want to modify your computer so that it will
+ automatically start the database server whenever it boots. Some
+ suggestions for this are in the Administrator's Guide.
+
+ * Run the regression tests against the installed server (using the
+ sequential test method). If you didn't run the tests before installation,
+ you should definitely do it now. This is also explained in the
+ Administrator's Guide.
+
+-------------------------------------------------------------------------------
+
+ Supported Platforms
+
+PostgreSQL has been verified by the developer community to work on the
+platforms listed below. A supported platform generally means that PostgreSQL
+builds and installs according to these instructions and that the regression
+tests pass.
+ Note: If you are having problems with the installation on a supported
+ platform, please write to <pgsql-bugs@postgresql.org> or <pgsql-
+ ports@postgresql.org>, not to the people listed here.
+ ________________________________________________________________________________
+|OS______|Processor__|Version|Reported_________________________|Remarks__________|
+|AIX |RS6000 |7.3 |2002-11-12, Andreas Zeugswetter |see also doc/ |
+|________|___________|_______|(<ZeugswetterA@spardat.at>)______|FAQ_AIX__________|
+|BSD/OS |x86 |7.3 |2002-10-25, Bruce Momjian |4.2 |
+|________|___________|_______|(<pgman@candle.pha.pa.us>)_______|_________________|
+|FreeBSD |Alpha |7.3 |2002-11-13, Chris Kings-Lynne | |
+|________|___________|_______|(<chriskl@familyhealth.com.au>)__|_________________|
+|FreeBSD |x86 |7.3 |2002-10-29, 3.3, Nigel J. Andrews| |
+| | | |(<nandrews@investsystems.co.uk>),| |
+| | | |4.7, Larry Rosenman | |
+| | | |(<ler@lerctr.org>), 5.0, Sean | |
+| | | |Chittenden | |
+|________|___________|_______|(<sean@chittenden.org>)__________|_________________|
+|HP-UX |PA-RISC |7.3 |2002-10-28, 10.20 Tom Lane |gcc and cc; see |
+| | | |(<tgl@sss.pgh.pa.us>), 11.00, |also doc/FAQ_HPUX|
+| | | |11.11, 32 & 64 bit, Giles Lean | |
+|________|___________|_______|(<giles@nemeton.com.au>)_________|_________________|
+|IRIX |MIPS |7.3 |2002-10-27, Ian Barwick |Irix64 Komma 6.5 |
+|________|___________|_______|(<barwick@gmx.net>)______________|_________________|
+|Linux |Alpha |7.3 |2002-10-28, Magnus Naeslund |2.4.19-pre6 |
+|________|___________|_______|(<mag@fbab.net>)_________________|_________________|
+|Linux |armv4l |7.2 |2001-12-10, Mark Knox |2.2.x |
+|________|___________|_______|(<segfault@hardline.org>)________|_________________|
+|Linux |MIPS |7.2 |2001-11-15, Hisao Shibuya |2.0.x; Cobalt |
+|________|___________|_______|(<shibuya@alpha.or.jp>)__________|Qube2____________|
+|Linux |PlayStation|7.2 |2001-12-12, Permaine Cheung |#undef |
+| |2 | |<pcheung@redhat.com>) |HAS_TEST_AND_SET,|
+|________|___________|_______|_________________________________|slock_t__________|
+|Linux |PPC74xx |7.3 |2002-10-26, Tom Lane |bye 2.2.18; Apple|
+|________|___________|_______|(<tgl@sss.pgh.pa.us>)____________|G3_______________|
+|Linux |S/390 |7.2 |2001-12-12, Permaine Cheung | |
+|________|___________|_______|<pcheung@redhat.com>)____________|_________________|
+|Linux |Sparc |7.3 |2002-10-26, Doug McNaught |3.0 |
+|________|___________|_______|(<doug@mcnaught.org>)____________|_________________|
+|Linux |x86 |7.3 |2002-10-26, Alvaro Herrera |2.4 |
+|________|___________|_______|(<alvherre@dcc.uchile.cl>)_______|_________________|
+|MacOS X |PPC |7.3 |2002-10-28, 10.1, Tom Lane | |
+| | | |(<tgl@sss.pgh.pa.us>), 10.2.1, | |
+| | | |Adam Witney | |
+|________|___________|_______|(<awitney@sghms.ac.uk>)__________|_________________|
+|NetBSD |Alpha |7.2 |2001-11-20, Thomas Thai |1.5W |
+|________|___________|_______|(<tom@minnesota.com>)____________|_________________|
+|NetBSD |arm32 |7.3 |2002-11-19, Patrick Welche |1.6 |
+|________|___________|_______|(<prlw1@newn.cam.ac.uk>)_________|_________________|
+|NetBSD |m68k |7.0 |2000-04-10, Henry B. Hotz |Mac 8xx |
+|________|___________|_______|(<hotz@jpl.nasa.gov>)____________|_________________|
+|NetBSD |MIPS |7.2.1 |2002-06-13, Warwick Hunter |1.5.3 |
+|________|___________|_______|(<whunter@agile.tv>)_____________|_________________|
+|NetBSD |PPC |7.2 |2001-11-28, Bill Studenmund |1.5 |
+|________|___________|_______|(<wrstuden@netbsd.org>)__________|_________________|
+|NetBSD |Sparc |7.2 |2001-12-03, Matthew Green |32- and 64-bit |
+|________|___________|_______|(<mrg@eterna.com.au>)____________|builds___________|
+|NetBSD |VAX |7.1 |2001-03-30, Tom I. Helbekkmo |1.5 |
+|________|___________|_______|(<tih@kpnQwest.no>)______________|_________________|
+|NetBSD |x86 |7.3 |2002-11-14, Patrick Welche |1.6 |
+|________|___________|_______|(<prlw1@newn.cam.ac.uk>)_________|_________________|
+|OpenBSD |Sparc |7.3 |2002-11-17, Christopher Kings- |3.2 |
+| | | |Lynne | |
+|________|___________|_______|(<chriskl@familyhealth.com.au>)__|_________________|
+|OpenBSD |x86 |7.3 |2002-11-14, 3.1 Magnus Naeslund | |
+| | | |(<mag@fbab.net>), 3.2 Christopher| |
+| | | |Kings-Lynne | |
+|________|___________|_______|(<chriskl@familyhealth.com.au>)__|_________________|
+|Solaris |Sparc |7.3 |2002-10-28, Andrew Sullivan |Solaris 7 & 8; |
+| | | |(<andrew@libertyrms.info>) |see also doc/ |
+|________|___________|_______|_________________________________|FAQ_Solaris______|
+|Solaris |x86 |7.2 |2001-11-28, Martin Renters |2.8; see also |
+|________|___________|_______|(<martin@datafax.com>)___________|doc/FAQ_Solaris__|
+|SunOS 4 |Sparc |7.2 |2001-12-04, Tatsuo Ishii (<t- | |
+|________|___________|_______|ishii@sra.co.jp>)________________|_________________|
+|Tru64 |Alpha |7.3 |2002-11-05, Alessio Bragadini | |
+|UNIX____|___________|_______|(<alessio@albourne.com>)_________|_________________|
+|UnixWare|x86 |7.3 |2002-11-01, 7.1.3 Larry Rosenman |see also doc/ |
+| | | |(<ler@lerctr.org>), 7.1.1 and |FAQ_SCO |
+| | | |7.1.2(8.0.0) Olivier Prenant | |
+|________|___________|_______|(<ohp@pyrenet.fr>)_______________|_________________|
+|Windows |x86 |7.3 |2002-10-29, Dave Page |with Cygwin; see |
+| | | |(<dpage@vale-housing.co.uk>), |doc/FAQ_MSWIN |
+| | | |Jason Tishler | |
+|________|___________|_______|(<jason@tishler.net>)____________|_________________|
+|Windows |x86 |7.3 |2002-11-05, Dave Page |native is client-|
+| | | |(<dpage@vale-housing.co.uk>) |side only; see |
+| | | | |Administrator's |
+|________|___________|_______|_________________________________|Guide____________|
+
+Unsupported Platforms: The following platforms are either known not to work, or
+they used to work in a previous release and we did not receive explicit
+confirmation of a successful test with version 7.3 at the time this list was
+compiled. We include these here to let you know that these platforms *could* be
+supported if given some attention.
+ _____________________________________________________________________________
+|OS__________|Processor|Version|Reported_______________________|Remarks_______|
+|BeOS |x86 |7.2 |2001-11-29, Cyril Velter |needs updates |
+| | | |(<cyril.velter@libertysurf.fr>)|to semaphore |
+|____________|_________|_______|_______________________________|code__________|
+|DG/UX |m88k |6.3 |1998-03-01, Brian E Gallew |no recent |
+|5.4R4.11____|_________|_______|(<geek+@cmu.edu>)______________|reports_______|
+|MkLinux DR1 |PPC750 |7.0 |2001-04-03, Tatsuo Ishii (<t- |7.1 needs OS |
+|____________|_________|_______|ishii@sra.co.jp>)______________|update?_______|
+|NeXTSTEP |x86 |6.x |1998-03-01, David Wetzel |bit rot |
+|____________|_________|_______|(<dave@turbocat.de>)___________|suspected_____|
+|QNX 4 RTOS |x86 |7.2 |2001-12-10, Bernd Tegge |needs updates |
+| | | |(<tegge@repas-aeg.de>) |to semaphore |
+| | | | |code; see also|
+|____________|_________|_______|_______________________________|doc/FAQ_QNX4__|
+|QNX RTOS v6 |x86 |7.2 |2001-11-20, Igor Kovalenko |patches |
+| | | |(<Igor.Kovalenko@motorola.com>)|available in |
+| | | | |archives, but |
+| | | | |too late for |
+|____________|_________|_______|_______________________________|7.2___________|
+|SCO |x86 |6.5 |1999-05-25, Andrew Merrill |7.2 should |
+|OpenServer 5| | |(<andrew@compclass.com>) |work, but no |
+| | | | |reports; see |
+| | | | |also doc/ |
+|____________|_________|_______|_______________________________|FAQ_SCO_______|
+|System V R4 |m88k |6.2.1 |1998-03-01, Doug Winterburn |needs new TAS |
+|____________|_________|_______|(<dlw@seavme.xroads.com>)______|spinlock_code_|
+|System V R4 |MIPS |6.4 |1998-10-28, Frank Ridderbusch |no recent |
+|____________|_________|_______|(<ridderbusch.pad@sni.de>)_____|reports_______|
+|Ultrix |MIPS |7.1 |2001-03-26 |TAS spinlock |
+| | | | |code not |
+|____________|_________|_______|_______________________________|detected______|
+|Ultrix______|VAX______|6.x____|1998-03-01_____________________|______________|
projects / postgresql / blobdiff