Installation
Complete installation instructions for
Postgres v6.4.
Before installing Postgres, you may wish to visit
www.postgresql.org
for up to date information, patches, etc.
These installation instructions assume:
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 may vary wildly
between platforms on what options you should use.
Use common sense before typing in these commands.
Our Makefiles require GNU make (called
gmake in this document). They will not
work with non-GNU make programs. If you
have GNU make installed under the name
make instead of gmake, then you will use the
command make instead. That's OK, but
you need to have the GNU form of make to succeed with
an installation.
Requirements to Run Postgres
Up to date information on supported platforms is at
http://www.postgresql.org/docs/admin/install.htm.
In general, most Unix-compatible
platforms with modern libraries should be able to run Postgres.
Although the minimum required memory for running Postgres
is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows.
The rule is you can never have too much memory.
Check that you have sufficient disk space. You will need about
30 Mbytes for /usr/src/pgsql,
about 5 Mbytes for /usr/local/pgsql
(excluding your database) and 1 Mbyte for an empty database.
The database will temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes for the
distribution tar file.
We therefore recommend that during installation and testing you
have well over 20 Mbytes free under /usr/local and another 25 Mbytes
free on the disk partition containing your database. Once you
delete the source files, tar file and regression database, you
will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty
database, plus about five times the space you would require to
store your database data in a flat file.
To check for disk space, use
$ df -k
Installation ProcedurePostgres Installation
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 the Postgres superuser account
(postgres is commonly used) if it does not already exist.
The owner of the Postgres files can be any unprivileged user account.
It must not be root, bin,
or any other account with special access rights, as that would create a security risk.
Log in to the Postgres superuser account. Most of the
remaining steps in the installation will happen in this account.
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 Postgres.
You may want to do the entire flex installation from
the root account, though that is not absolutely necessary.
Assuming that you want the installation to place files in the usual default
areas, type the following:
$ su -
$ cd /usr/local/src
ftp prep.ai.mit.edu
ftp> cd /pub/gnu/
ftp> binary
ftp> get flex-2.5.4.tar.gz
ftp> quit
$ gunzip -c flex-2.5.4.tar.gz | tar xvf -
$ cd flex-2.5.4
$ configure --prefix=/usr
$ gmake
$ gmake check
# You must be root when typing the next line:
$ gmake install
$ cd /usr/local/src
$ rm -rf flex-2.5.4
This will update files /usr/man/man1/flex.1,
/usr/bin/flex,
/usr/lib/libfl.a,
/usr/include/FlexLexer.h and will add a link
/usr/bin/flex++ which points to flex.
If you are not upgrading an existing system then skip to
.
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.
Do not use the pg_dumpall
script from v6.0 or everything
will be owned by the Postgres super user.
To dump your fairly recent post-v6.0 database installation, type
$ pg_dumpall -z > db.out
To use the latest pg_dumpall script on your
existing older database before upgrading Postgres,
pull the most recent version of pg_dumpall
from the new distribution:
$ cd
$ gunzip -c postgresql-v6.4.tar.gz \
| tar xvf - src/bin/pg_dump/pg_dumpall
$ chmod a+x src/bin/pg_dump/pg_dumpall
$ src/bin/pg_dump/pg_dumpall -z > db.out
$ rm -rf src
If you wish to preserve object id's (oids), then use the -o
option when running pg_dumpall.
However, unless you have a
special reason for doing this (such as using OIDs as keys
in tables), don't do it.
If the pg_dumpall command seems to take a long time and you think
it might have died, then, from another terminal, type
$ ls -l db.out
several times to see if the size of the file is growing.
Please note that if you are upgrading from a version prior to
Postgres95 v1.09 then you must back up your database, install
Postgres95 v1.09, restore your database, then back it up again.
You should also read the release notes which should cover any release-specific issues.
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 pid
replaced by the process id for process
postmaster.
(Do not use the id for process "grep postmaster".) Type
$ kill pid
to actually stop the process.
On systems which have Postgres started at boot time, there
is probably a startup file which will accomplish the same thing. For example, on my
Linux system I can type
$ /etc/rc.d/init.d/postgres.init stop
to halt Postgres.
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 but you must be consistant throughout this procedure.
There are two places in this installation procedure where you will have an opportunity
to specify installation locations for programs, libraries, documentation, and other files.
Usually it is sufficient to specify these at the make install stage
of installation.
Type
$ su
$ cd /usr/src
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ cd /usr/local
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ exit
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 option to
make the right file be chosen.
Please Report Problems
If your system is not automatically recognized by configure and you have to do this, please
send email to
scrappy@hub.org with the output of the program
./config.guess. Indicate what the template file should be.
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 used on a Sparc Solaris 2.5 system
with /opt/postgres being the installation base directory:
$ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc --with-pgport=5432 \
--enable-hba --disable-locale
Of course, you may type these three lines all
on the same line.
Install the HTML documentation. Type
$ cd /usr/src/pgsql/doc
$ gmake install
The documentation is also available in Postscript format. Look for files
ending with .ps.gz in the same directory.
Install the man page documentation. Type
$ cd /usr/src/pgsql/doc
$ gmake man
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.)
You will probably find a number of warning
messages in make.log. Unless you have problems later on, these
messages may be safely ignored.
If the compiler fails with a message stating that
the flex command
cannot be found then install flex as described earlier.
Next,
change directory back to this directory, type
$ make clean
then recompile again.
Compiler options, such as optimization and debugging, may
be specified on the command line using the COPT variable.
For example, typing
$ gmake COPT="-g" all >& make.log &
would invoke your compiler's 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.
If necessary, tell your system how to find the new shared libraries. You can
do one of the following, preferably the first:
As root, edit file /etc/ld.so.conf. Add a 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 similarly prepared.
There are several ways to influence the runtime environment of the Postgres
server. Refer to the chapter on Administrator's Guide for more information.
The following instructions are for a
bash/sh 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.
Run postmaster from your Postgres superuser account (typically
account postgres).
Do not run postmaster from the root account!
Start the postmaster daemon running in the background by typing
$ cd
$ nohup postmaster > regress.log 2>&1 &
Run the regression tests.
The file /usr/src/pgsql/src/test/regress/README has detailed
instructions for running and interpreting the regression tests.
A short version follows here:
Type
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
$ gmake all runtest
You do not need to type gmake clean
if this is the first time you
are running the tests.
You should get on the screen (and also written to file ./regress.out)
a series of statements stating which tests passed and which tests
failed. Please note that it can be normal for some tests to
"fail" on some platforms.
The script says a test has failed if there is any difference
at all between the actual output of the test and the expected output.
Thus, tests may "fail" due to minor differences in wording of error
messages, small differences in floating-point roundoff, etc, between
your system and the regression test reference platform.
"Failures" of this type do not indicate a problem with
Postgres.
The file ./regression.diffs contains the textual differences between
the actual test output on your machine and the "expected" output
(which is simply what the reference system produced). You should
carefully examine each difference listed to see whether it appears to
be a significant issue.
For example,
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 may require some study to be useful.
After running the regression tests, type
$ destroydb regression
$ cd /usr/src/pgsql/src/test/regress
$ gmake clean
to recover the disk space used for the tests. (You may want to save
the regression.diffs file in another place before doing this.)
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
the Postgres superuser (postgres?)
and not by root.
This is why all of the examples below start by switching user
(su) to postgres. These commands also take into account the fact
that environment variables like PATH and PGDATA may not be set properly.
The examples are as follows. Use them with extreme caution.
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"
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.
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.
In RedHat Linux edit file /etc/inittab to add the
following as a single line:
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
>> /usr/local/pgsql/server.log 2>&1 </dev/null"
(The author of this example says this example will revive the
postmaster if it dies, but he doesn't know if there are other side
effects.)
If you haven't already done so, this would be a good time to modify
your computer to do regular maintainence. The following should be
done at regular intervals:
Minimal Backup Procedure
Run the SQL command VACUUM.
This will clean up your database.
Back up your system. (You should probably keep the last few
backups on hand.) Preferably, no one else should be using the
system at the time.
Ideally, the above tasks should be done by a shell script that is
run nightly or weekly by cron.
Look at the man page for crontab
for a starting point on how to do this. (If you do it, please
e-mail us a copy of your shell script. We would like to set up
our own systems to do this too.)
If you are upgrading an existing system then reinstall your old database.
Type
$ cd
$ psql -e template1 < db.out
If your pre-v6.2 database uses either path or polygon geometric data types,
then you will need to upgrade any columns containing those types. To
do so, type (from within psql)
UPDATE FirstTable SET PathCol = UpgradePath(PathCol);
UPDATE SecondTable SET PathCol = UpgradePath(PathCol);
...
VACUUM;
UpgradePath() checks to see that a path value is consistant with the
old syntax, and will not update a column which fails that examination.
UpgradePoly() cannot verify that a polygon is in fact from an old
syntax, but RevertPoly() is provided to reverse the effects of a
mis-applied upgrade.
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. If you have
a Postscript printer, or have your machine already set up to accept
Postscript files using a print filter, then to print the User's Guide
simply type
$ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr
Here is how
you might do it if you have Ghostscript on your system and are
writing to a laserjet printer.
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
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.4, 6.3.2, beta 981014, etc.).
Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
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!
Playing with Postgres
After Postgres is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to
see Postgres do something. That's easy. Invoke the interactive interface
to Postgres, psql:
% psql template1
(psql has to open a particular database, but at this point the only one
that exists is the template1 database, which always exists. We will connect
to it only long enough to create another one and switch to it.)
The response from psql is:
Welcome to the POSTGRESQL interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRESQL
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: template1
template1=>
Create the database foo:
template1=> create database foo;
CREATEDB
(Get in the habit of including those SQL semicolons. Psql won't execute
anything until it sees the semicolon or a "\g" and the semicolon is required
to delimit multiple statements.)
Now connect to the new database:
template1=> \c foo
connecting to new database: foo
("slash" commands aren't SQL, so no semicolon. Use \? to see all the slash commands.)
And create a table:
foo=> create table bar (i int4, c char(16));
CREATE
Then inspect the new table:
foo=> \d bar
Table = bar
+----------------------------------+----------------------------------+-------+
| Field | Type | Length|
+----------------------------------+----------------------------------+-------+
| i | int4 | 4 |
| c | (bp)char | 16 |
+----------------------------------+----------------------------------+-------+
And so on. You get the idea.
The Next Step
Questions? Bugs? Feedback?
First, read the files in directory /usr/src/pgsql/doc. The FAQ in
this directory may be particularly useful.
If Postgres failed to compile on your computer then fill out the form
in file /usr/src/pgsql/doc/bug.template and mail it to the location
indicated at the top of the form.
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.
Porting Notes
Check for any platform-specific FAQs in the doc/ directory of
the source distribution. For some ports, the notes below may be out of date.
Ultrix4.x
There have been no recent reports of Ultrix usage with Postgres.
You need to install the libdl-1.1 package since Ultrix 4.x doesn't
have a dynamic loader. It's available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
LinuxThomas G.Lockhart1998-02-19Linux ELF
The regression test reference machine is
a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
The linux-elf port installs cleanly. See the Linux FAQ for more details.
1995-05-11Linux a.out
For non-ELF Linux, the dld library MUST be obtained and installed on
the system. It enables dynamic link loading capability to the Postgres
port. The dld library can be obtained from the sunsite linux
distributions. The current name is dld-3.2.5.
Jalon Q. ZimmermanBSD/OS
For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
NeXT
The NeXT port for v1.09 was supplied by
Tom R. Hageman.
It requires a SysV IPC emulation library and header files for
shared libary and semaphore stuff. Tom just happens to sell such
a product so contact him for information. He has also indicated that
binary releases of Postgres for NEXTSTEP will be made available to
the general public. Contact Info@RnA.nl for information.
We have no recent reports of successful NeXT installations (as of v6.2.1).
However, the client-side libraries should work even
if the backend is not supported.