I have taken Peter's new install.sgml and generated a new INSTALL text
file to match it. I used sgmltools to convert to HTML and netscape to
dump the html as text.
File attached.
--
Bruce Momjian | http://www.op.net/~candle
pgman@candle.pha.pa.us | (610) 853-3000
+ If your life is a hard drive, | 830 Blythe Avenue
+ Christ can be your backup. | Drexel Hill, Pennsylvania 19026
Chapter 0. Installation
Table of Contents
Before you start
Installation Procedure
Installation instructions for PostgreSQL 7.0.0.
Commands were tested on RedHat Linux version 5.2 using the bash shell.
Except where noted, they will probably work on most systems. Commands like
ps and tar may vary wildly between platforms on what options you should use.
Use common sense before typing in these commands.
If you haven't gotten the PostgreSQL distribution, get it from
ftp.postgresql.org, then unpack it:
$ gunzip postgresql-7.0.0.tar.gz
$ tar -xf postgresql-7.0.0.tar
$ mv postgresql-7.0.0 /usr/src
Again, these commands might differ on your system.
Before you start
Building PostgreSQL requires GNU make. It will not work with other make
programs. On GNU/Linux systems GNU make is the default tool, on other
systems you may find that GNU make is installed under the name "gmake". We
will use that name from now on to indicate GNU make, no matter what name it
has on your system. To test for GNU make enter
$ gmake --version
If you need to get GNU make, you can find it at ftp://ftp.gnu.org.
Up to date information on supported platforms is at
http://www.postgresql.org/docs/admin/ports.htm. In general, most
Unix-compatible platforms with modern libraries should be able to run
PostgreSQL. In the doc subdirectory of the distribution are several
platform-specific FAQ and README documents you might wish to consult if you
are having trouble.
Although the minimum required memory for running PostgreSQL can be as little
as 8MB, there are noticable speed improvements when expanding memory up to
96MB or beyond. The rule is you can never have too much memory.
Check that you have sufficient disk space. You will need about 30 Mbytes for
the source tree during compilation and about 5 Mbytes for the installation
directory. An empty database takes about 1 Mbyte, otherwise they take about
five times the amount of space that a flat text file with the same data
would take. If you run the regression tests you will temporarily need an
extra 20MB.
To check for disk space, use
$ df -k
Considering today's prices for hard disks, getting a large and fast hard
disk should probably be in your plans before putting a database into
production use.
---------------------------------------------------------------------------
Installation Procedure
PostgreSQL Installation
For a fresh install or upgrading from previous releases of PostgreSQL:
1. Create the PostgreSQL superuser account. This is the user the server
will run as. For production use you should create a separate,
unprivileged account (postgres is commonly used). If you do not have
root access or just want to play around, your own user account is
enough.
Running PostgreSQL as root, bin, or any other account with special
access rights is a security risk and therefore won't be allowed.
You need not do the building and installation itself under this account
(although you can). You will be told when you need to login as the
database superuser.
2. If you are not upgrading an existing system then skip to .
You now need to back up your existing database. To dump your fairly
recent post-6.0 database installation, type
$ pg_dumpall > db.out
If you wish to preserve object id's (oids), then use the -o option when
running pg_dumpall. However, unless you have a special reason for doing
this (such as using OIDs as keys in tables), don't do it.
Make sure to use the pg_dumpall command from the version you are
currently running. However, do not use the pg_dumpall script from 6.0
or everything will be owned by the PostgreSQL super user. In that case
you should grab pg_dumpall from a later 6.x.x release. 7.0's pg_dumpall
will not work on older databases. If you are upgrading from a version
prior to Postgres95 v1.09 then you must back up your database, install
Postgres95 v1.09, restore your database, then back it up again.
Caution
You must make sure that your database is not updated in the middle of your
backup. If necessary, bring down postmaster, edit the permissions in file
/usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring
postmaster back up.
3. If you are upgrading an existing system then kill the database server
now. Type
$ ps ax | grep postmaster
This should list the process numbers for a number of processes, similar
to this:
263 ? SW 0:00 (postmaster)
777 p1 S 0:00 grep postmaster
Type the following line, with pid replaced by the process id for
process postmaster (263 in the above case). (Do not use the id for the
process "grep postmaster".)
$ kill pid
Tip: On systems which have PostgreSQL started at boot time,
there is probably a startup file which will accomplish the
same thing. For example, on a Redhat Linux system one might
find that
$ /etc/rc.d/init.d/postgres.init stop
works.
Also move the old directories out of the way. Type the following:
$ mv /usr/local/pgsql /usr/local/pgsql.old
or replace your particular paths.
4. Configure the source code for your system. It is this step at which you
can specify your actual installation path for the build process and
make choices about what gets installed. Change into the src
subdirectory and type:
$ ./configure [ options ]
For a complete list of options, type:
./configure --help
Some of the more commonly used ones are:
--prefix=BASEDIR
Selects a different base directory for the installation of
PostgreSQL. The default is /usr/local/pgsql.
--enable-locale
If you want to use locales.
--enable-multibyte
Allows the use of multibyte character encodings. This is primarily
for languages like Japanese, Korean, or Chinese.
--with-perl
Builds the Perl interface. Please note that the Perl interface
will be installed into the usual place for Perl modules (typically
under /usr/lib/perl), so you must have root access to use this
option successfully.
--with-odbc
Builds the ODBC driver package.
--with-tcl
Builds interface libraries and programs requiring Tcl/Tk,
including libpgtcl, pgtclsh, and pgtksh.
5. Compile the program. Type
$ gmake
The compilation process can take anywhere from 10 minutes to an hour.
Your milage will most certainly vary.
The last line displayed will hopefully be
All of PostgreSQL is successfully made. Ready to install.
Remember, "gmake" may be called "make" on your system.
6. Install the program. Type
$ gmake install
7. Tell your system how to find the new shared libraries. How to do this
varies between platforms. What tends to work everywhere is to set the
environment variable LD_LIBRARY_PATH:
$ LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ export LD_LIBRARY_PATH
You might want to put this into a shell startup file such as
~/.bash_profile.
On some systems the following is the preferred method, but you must
have root access. Edit file /etc/ld.so.conf to add a line
/usr/local/pgsql/lib
Then run command /sbin/ldconfig.
If in doubt, refer to the manual pages of your system. If you later on
get a message like
./psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
then the above was necessary. Simply do this step then.
8. Create the database installation. To do this you must log in to your
PostgreSQL superuser account. It will not work as root.
$ mkdir /usr/local/pgsql/data
$ chown postgres /usr/local/pgsql/data
$ su - postgres
$ /usr/local/pgsql/initdb -D /usr/local/pgsql/data
The -D option specifies the location where the data will be stored. You
can use any path you want, it does not have to be under the
installation directory. Just make sure that the superuser account can
write to it (or create it) before starting initdb.
9. The previous step should have told you how to start up the database
server. Do so now.
$ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data
This will start the server in the foreground. To make it detach to the
background, use the -S.
10. If you are upgrading from an existing installation, dump your data back
in:
$ /usr/local/pgsql/bin/psql < db.out
You also might want to copy over the old pg_hba.conf file and any other
files you might have had set up for authentication, such as password
files.
This concludes the installation proper. To make your life more productive
and enjoyable you should look at the following optional steps and
suggestions.
* Life will be more convenient if you set up some enviroment variables.
First of all you probably want to include /usr/local/pgsql/bin (or
equivalent) into your PATH. To do this, add the following to your shell
startup file, such as ~/.bash_profile (or /etc/profile, if you want it
to affect every user):
PATH=$PATH:/usr/local/pgsql/bin
Furthermore, if you set PGDATA in the environment of the PostgreSQL
superuser, you can omit the -D for postmaster and initdb.
* You probably want to install the man and HTML documentation. Type
$ cd /usr/src/pgsql/postgresql-7.0.0/doc
$ gmake install
This will install files under /usr/local/pgsql/doc.
The documentation is also available in Postscript format. If you have a
Postscript printer, or have your machine already set up to accept
Postscript files using a print filter, then to print the User's Guide
simply type
$ cd /usr/local/pgsql/doc
$ gunzip -c user.ps.tz | lpr
Here is how you might do it if you have Ghostscript on your system and
are writing to a laserjet printer.
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
If in doubt, confer your manuals or your local expert.
The Adminstrator's Guide should probably be your first reading if you
are completely new to PostgreSQL, as it contains information about how
to set up database users and authentication.
* Usually, you will want to modify your computer so that it will
automatically start the database server whenever it boots. This is not
required; the PostgreSQL server can be run successfully from
non-privileged accounts without root intervention.
Different systems have different conventions for starting up daemons at
boot time, so you are advised to familiarize yourself with them. Most
systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost
certainly no bad place to put such a command. Whatever you do,
postmaster must be run by the PostgreSQL superuser (postgres) and not
by root or any other user. Therefore you probably always want to form
your command lines along the lines of su -c '...' postgres.
It might be advisable to keep a log of the server output. To start the
server that way try:
nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
Here are a few more operating system specific suggestions.
o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
to contain the following single line:
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
contain the following lines and make it chmod 755 and chown
root:bin.
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
You may put the line breaks as shown above. The shell is smart
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under the
postmaster process so the parent is init.
o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
based on the example in contrib/linux/. Then make a softlink to
this file from /etc/rc.d/rc5.d/S98postgres.init.
* Run the regression tests. The regression tests are a test suite to
verify that PostgreSQL runs on your machine in the way the developers
expected it to. You should definitely do this before putting a server
into production use. The file
/usr/src/pgsql/postgresql-7.0.0/src/test/regress/README has detailed
instructions for running and interpreting the regression tests.
