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.
The installation notes below assume the following (except where noted):
Commands are Unix-compatible. See note below.
Defaults are used except where noted.
User postgres is the Postgres superuser.
The source path is /usr/src/pgsql (other paths are possible).
The runtime path is /usr/local/pgsql (other paths are possible).
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
like ps and tar vary wildly on what options you should use on each
platform. Use common sense before typing in these commands.
Our Makefiles require GNU make (called
gmake
in this document). They will not
work with non-GNU make programs. If you
have GNU make installed under the name
make
instead of gmake
, that's OK, but
you need to have it.
Requirements to Run Postgres
Information on supported platforms is in another chapter. In general, most Unix-compatible
platforms with modern libraries should be able to run Postgres.
You should have at least 8 MB of memory and at least 45 MB of disk space
to hold the source, binaries, and user databases. After installation
you may reduce this to about 3 Mbytes plus space for user databases.
Installation Procedure
Postgres 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 account postgres if it does not already exist.
Log into account postgres.
Check that you have sufficient disk space. You will need about
17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
(excluding your database) and 1 Mbyte for an empty database.
The database will temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes for the
distribution tar file.
We therefore recommend that during installation and testing you
have well over 20 Mbytes free under /usr/local and another 25 Mbytes
free on the disk partition containing your database. Once you
delete the source files, tar file and regression database, you
will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty
database, plus about five times the space you would require to
store your database data in a flat file.
To check for disk space, use df -k.
Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the
Internet. Store it in your home directory.
Some platforms use flex. If your system uses flex then make sure
you have a good version. To check, type flex --version.
If the flex command is not found then you probably do not need it.
If the version is 2.5.2 or 2.5.4 or greater then you are okay. If it
is 2.5.3 or before 2.5.2 then you will have to upgrade flex. You may
get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
If you need flex and don't have it or have the wrong version, then
you will be told so when you attempt to compile the program. Feel
free to skip this step if you aren't sure you need it. If you do
need it then you will be told to install/upgrade flex when you try to
compile.
To install it, type the following:
cd
gunzip -c flex-2.5.4.tar.gz | tar xvf -
cd flex-2.5.4
configure --prefix=/usr
make
make check
# You must be root when typing the next line.
make install
cd
rm -rf flex-2.5.4
This will update files /usr/man/man1/flex.1, /usr/bin/flex,
/usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
/usr/bin/flex++ which points to flex.
If you are upgrading an existing system then back up your database.
For alpha- and beta-level releases, the database format is liable
to change often every few weeks with no notice besides a quick comment
in the HACKERS mailing list. Full releases always require a dump/reload
from previous releases. It is therefore a bad idea to skip this
step. Also, do not use the pg_dumpall script from v6.0 or everything
will be owned by the Postgres super user.
Type (with the gunzip line
and the following line typed as one line):
cd
gunzip -c postgresql-v6.4.tar.gz |
tar xvf - src/bin/pg_dump/pg_dumpall
chmod a+x src/bin/pg_dump/pg_dumpall
src/bin/pg_dump/pg_dumpall > db.out
rm -rf src
If you wish to preserve object id's (oids), then use the -o
option when running pg_dumpall. However, unless you have a
special reason for doing this, don't do it.
If the pg_dumpall command seems to take a long time and you think
it might have died, then, from another terminal, use "ls -l db.out"
several times to see if the size of the file is growing.
Please note that if you are upgrading from a version prior to
Postgres95 v1.09 then you must back up your database, install
Postgres95 v1.09, restore your database, then back it up again.
You should also read files /usr/src/pgsql/migration/*.
You must make sure that your database is not updated in the middle of
your backup. If necessary, bring down postmaster, edit the permissions
in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then
bring postmaster back up.
If you are upgrading an existing system then kill the postmaster. Type
ps -ax | grep postmaster
This should list the process numbers for a number of processes. Type
the following line, with "???" replaced by the process id for process
"postmaster". (Do not use the id for process "grep postmaster".) Type
kill ???
with "???" modified as indicated.
If you are upgrading an existing system then move the old directories
out of the way. If you are short of disk space then you may have to
back up and delete the directories instead. If you do this, save the
old database in the /usr/local/pgsql/data directory tree. At a
minimum, save file /usr/local/pgsql/data/pg_hba.conf.
Type the following:
su
cd /usr/src
mv pgsql pgsql_6_0
cd /usr/local
mv pgsql pgsql_6_0
exit
If you are not using /usr/local/pgsql/data as your data directory
(check to see if environment variable PGDATA is set to something
else) then you will also want to move this directory in the same
manner.
Make new source and install directories. The actual paths can be
different for your installation; be consistant throughout this procedure.
Type
su
cd /usr/src
mkdir pgsql
chown postgres:postgres pgsql
cd /usr/local
mkdir pgsql
chown postgres:postgres pgsql
exit
Unzip and untar the new source file. Type
cd /usr/src/pgsql
gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
Configure the source code for your system. It is this step at which
you can specify your actual installation path for
the build process (see the --prefix option below). Type
cd /usr/src/pgsql/src
./configure [ options as described below ]
Among other chores, the configure script selects a system-specific
"template" file from the files provided in the template subdirectory.
If it cannot guess which one to use for your system, it will say so and
exit. In that case you'll need to figure out which one to use and run
configure again, this time giving the --with-template=TEMPLATE option to
make the right file be chosen. (If you have to do this, please
send email to scrappy@hub.org stating the output of the program
'./config.guess' and what the template file should be.)
The configure script accepts many additional options that you can use
if you don't like the default configuration. To see them all, type
./configure --help
Some of the more commonly used ones are:
--prefix=BASEDIR Selects a different base directory for the
installation of the Postgres configuration.
The default is /usr/local/pgsql.
--with-template=TEMPLATE
Use template file TEMPLATE - the template
files are assumed to be in the directory
src/template, so look there for proper values.
--with-pgport=PORT Sets the port that the postmaster process
listens for incoming connections on. The
default is port 5432.
--with-tcl Build interface libraries and programs requiring
Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
--with-perl Build the Perl interface library.
--with-odbc Build the ODBC driver package.
--enable-hba Enables Host Based Authentication (DEFAULT)
--disable-hba Disables Host Based Authentication
--enable-locale Enables USE_LOCALE
--enable-cassert Enables ASSERT_CHECKING
--with-CC=compiler
Use a specific C compiler that the configure
script cannot find.
--with-CXX=compiler
--without-CXX
Use a specific C++ compiler that the configure
script cannot find, or exclude C++ compilation
altogether. (This only affects libpq++ at
present.)
As an example, here is the configure script I use on a Sparc
Solaris 2.5 system with /opt/postgres being the install base.
./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc --with-pgport=5432 \
--enable-hba --disable-locale
Of course, in a real shell, you would type these three lines all
on the same line.
Compile the program. Type
cd /usr/src/pgsql/src
gmake all >& make.log &
tail -f make.log
The last line displayed will hopefully be "All of PostgreSQL is
successfully made. Ready to install." At this point, or earlier
if you wish, type control-C to get out of tail. (If you have
problems later on you may wish to examine file make.log for
warning and error messages.)
If your computer does not have gmake (GNU make) then try running
make instead throughout the rest of these notes.
Please note that you will probably find a number of warning
messages in make.log. Unless you have problems later on, these
messages may be safely ignored.
If the compiler fails with an error stating that the flex command
cannot be found then install flex as described earlier. Next,
change directory back to this directory, type "make clean", then
recompile again.
Compiler options, such as optimization and debugging, may
be specified on the command line using the COPT variable.
For example, typing
gmake COPT="-g" all >& make.log &
would invoke your compiler's -g option in all steps of the
build. See src/Makefile.global.in for further details.
Install the program. Type
cd /usr/src/pgsql/src
gmake install >& make.install.log &
tail -f make.install.log
The last line displayed will be "gmake[1]: Leaving directory
`/usr/src/pgsql/src/man'". At this point, or earlier if you wish,
type control-C to get out of tail.
14) If necessary, tell UNIX how to find your shared libraries. You can
do ONE of the following, preferably the first:
As root, edit file /etc/ld.so.conf. Add line
/usr/local/pgsql/lib
to the file. Then run command /sbin/ldconfig.
In a bash shell, type
export LD_LIBRARY_PATH=/usr/local/pgsql/lib
In a csh shell, type
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
Please note that the above commands may vary wildly for different
operating systems. Check the platform specific notes, such as
those for Ultrix4.x or and for non-ELF Linux.
If, when you create the database, you get the message "pg_id: can't
load library 'libpq.so'" then the above step was necessary. Simply
do this step, then try to create the database again.
If it has not already been done, then prepare account postgres
for using Postgres. Any account that will use Postgres must
be similarily prepared. (The following instructions are for a
bash shell. Adapt accordingly for other shells.)
Add the following lines to your login shell, ~/.bash_profile:
PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
PGLIB=/usr/local/pgsql/lib
PGDATA=/usr/local/pgsql/data
export PATH MANPATH PGLIB PGDATA
Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type:
source ~/.bash_profile
Create the database. Do not do the following as root!
This would be a major security hole. Type
initdb
Set up permissions to access the database system. Do this by editing
file /usr/local/pgsql/data/pg_hba.conf. The instructions are
included in the file. (If your database is not located in the
default location, i.e. if PGDATA is set to point elsewhere, then the
location of this file will change accordingly.) This file should be
made read only again once you are finished.
If you are upgrading from v6.0 or later you can copy file pg_hba.conf from
your old database on top of the one in your new database, rather than
redoing the file from scratch.
Start the postmaster daemon running. Type
cd
nohup postmaster > server.log 2>&1 &
Run postmaster from your Postgres super user account (typically
account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
Run the regression tests.
(You can skip this step if you wish, but
we think skipping the tests is a BAD idea!)
The file /usr/src/pgsql/src/test/regress/README has detailed
instructions for running and interpreting the regression tests.
A short version follows here:
Type
cd /usr/src/pgsql/src/test/regress
gmake clean
gmake all runtest
You do not need to type "gmake clean" if this is the first time you
are running the tests.
You should get on the screen (and also written to file ./regress.out)
a series of statements stating which tests passed and which tests
failed. Please note that it can be normal for some of the tests to
"fail". The script says a test has failed if there is any difference
at all between the actual output of the test and the expected output.
Thus, tests may "fail" due to minor differences in wording of error
messages, small differences in floating-point roundoff, etc, between
your system and the regression test reference platform.
"Failures" of this type do not indicate a problem with
Postgres.
The file ./regression.diffs contains the textual differences between
the actual test output on your machine and the "expected" output
(which is simply what the reference system produced). You should
carefully examine each difference listed to see whether it appears to
be a significant issue.
For a i686/Linux-ELF platform, no tests failed since this is the
v6.4 regression testing reference platform.
For the SPARC/Linux-ELF platform, using the 970525 beta version of
Postgres v6.2 the following tests "failed":
float8 and geometry "failed" due to minor precision differences in
floating point numbers. select_views produces massively different output,
but the differences are due to minor floating point differences.
Even if a test result clearly indicates a real failure, it may be a
localized problem that will not affect you. An example is that the
int8 test will fail, producing obviously incorrect output, if your
machine and C compiler do not provide a 64-bit integer data type
(or if they do but configure didn't discover it). This is not
something to worry about unless you need to store 64-bit integers.
Conclusion? If you do see failures, try to understand the nature of
the differences and then decide if those differences will affect your
intended use of Postgres. The regression
tests are a helpful tool, but they require some study to be useful.
After running the regression tests, type
destroydb regression
cd /usr/src/pgsql/src/test/regress
gmake clean
to recover the disk space used for the tests. (You may want to save
the regression.diffs file in another place before doing this.)
If you haven't already done so, this would be a good time to modify
your computer so that it will automatically start postmaster whenever
you boot your computer.
Here are some suggestions on how to do this, contributed by various
users.
Whatever you do, postmaster must be run by user postgres AND NOT BY
ROOT. This is why all of the examples below start by switching user
(su) to postgres. These commands also take into account the fact
that environment variables like PATH and PGDATA may not be set properly.
The examples are as follows. Use them with extreme caution.
a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
2.5.1 to contain the following single line:
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
/usr/local/pgsql/data"
b) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
contain the following lines and make it chmod 755 and chown
root:bin.
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
You may put the line breaks as shown above. The shell is smart
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init. Note: Unlike most
other examples, this one has been tested.
c) In RedHat v4.0 Linux edit file /etc/inittab to add the
following single line:
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
>> /usr/local/pgsql/server.log 2>&1 Postgres distribution has an example
init.d script compatible with and tested using recent RedHat packages.
If you haven't already done so, this would be a good time to modify
your computer to do regular maintainence. The following should be
done at regular intervals:
a) Run the SQL command vacuum. This will clean up your database.
b) Back up your system. (You should probably keep the last few
backups on hand.) Ideally, no one else should be using the
system at the time.
Ideally, the above tasks should be done by a shell script that is
run nightly or weekly by cron. Look at the man page for crontab
for a starting point on how to do this. (If you do it, please
e-mail us a copy of your shell script. We would like to set up
our own systems to do this too.)
If you are upgrading an existing system then reinstall your old database.
Type
cd
psql -e template1 < db.out
If your pre-v6.2 database uses either path or polygon geometric data types,
then you will need to upgrade any columns containing those types. To
do so, type (from within psql)
update YourTable set PathCol = UpgradePath(PathCol);
update YourTable set PolyCol = UpgradePoly(PolyCol);
...
vacuum;
UpgradePath() checks to see that a path value is consistant with the
old syntax, and will not update a column which fails that examination.
UpgradePoly() cannot verify that a polygon is in fact from an old
syntax, but RevertPoly() is provided to reverse the effects of a
mis-applied upgrade.
If you are a new user, you may wish to play with Postgres as described
below.
Clean up after yourself. Type
rm -rf /usr/src/pgsql_6_0
rm -rf /usr/local/pgsql_6_0
# Also delete old database directory tree if it is not in
# /usr/local/pgsql_6_0/data
rm ~/postgresql-v6.2.1.tar.gz
You will probably want to print out the documentation. Here is how
you might do it if you have Ghostscript on your system and are
writing to a laserjet printer.
alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
# Print out the man pages.
man -a -t /usr/local/pgsql/man/*/* > manpage.ps
gshp -sOUTPUTFILE=manpage.hp manpage.ps
rm manpage.ps
lpr -l -s -r manpage.hp
# Print out the Postgres95 User Manual, version 1.0,
# Sept. 5, 1996.
cd /usr/src/pgsql/doc
gshp -sOUTPUTFILE=userguide.hp userguide.ps
lpr -l -s -r userguide.hp
If you are a developer, you will probably want to also print out
the Postgres Implemention Guide, version 1.0, October 1, 1995.
This is a WWW document located at
http://www.postgresql.org/docs/impguide.
The Postgres team wants to keep Postgres working on all of the
supported platforms. We therefore ask you to let us know if you did
or did not get Postgres to work on you system. Please send a
mail message to pgsql-ports@postgresql.org telling us the following:
- The version of Postgres (v6.2.1, 6.1.1, beta 970703, etc.).
- Your operating system (i.e. RedHat v4.0 Linux v2.0.26).
- Your hardware (SPARC, i486, etc.).
- Did you compile, install and run the regression tests cleanly?
If not, what source code did you change (i.e. patches you
applied, changes you made, etc.), what tests failed, etc.
It is normal to get many warning when you compile. You do
not need to report these.
Now create, access and manipulate databases as desired. Write client
programs to access the database server. In other words, ENJOY!
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
For some ports, these notes may be out of date.
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
Linux
Thomas G.
Lockhart
1998-02-19
Linux 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-11
Linux 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. Zimmerman
BSD/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 (for v6.2.1).
However, the client-side libraries should work even
if the backend is not supported.