Here is a new attempt of the INSTALL file, that is a conversion of the
HTML to txt using:
lynx -force_html -dump -hiddenlinks=ignore -nolist "$@"
This is not the whole file because the install document is split up into
files, and I just converted the largest one. Our current INSTALL is
also attached. Seems my method has problems because though some parts
are formatted better, others are worse, and the number seems to stop
after item 11.
--
Bruce Momjian | http://www.op.net/~candle
maillist@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
#InstallationInstallationPlaying with Postgres
Installation
Prev Next
______________________________________________________________________
Installation Procedure
Postgres Installation
For a fresh install or upgrading from previous releases of Postgres:
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 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.
2. 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.
3. Log in to the Postgres superuser account. Most of the remaining
steps in the installation will happen in this account.
4. Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.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. 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.
6. If you are not upgrading an existing system then skip to . If you
are upgrading from 6.5, you do not need to dump/reload or initdb.
Simply compile the source code, stop the postmaster, do a "make
install", and restart the postmaster. If you are upgrading from
6.4.* or earlier, 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.
Tip: 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 > 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.5.1.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 (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.
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.
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 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.
Tip: 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.
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 but you must be consistent
throughout this procedure.
Note: 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 gmake 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
10. Unzip and untar the new source file. Type
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-v6.5.1.tar.gz | tar xvf -
11. 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 ]
a. 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.
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.
b. Choose configuration options. Check for details. However, for a
plain-vanilla first installation with no extra options like
multi-byte character support or locale collation support it may be
adequate to have chosen the installation areas and to run
configure without extra options specified. 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-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.)
c. Here is the configure script used on a Sparc Solaris 2.5 system
with /opt/postgres specified as the installation base directory:
$ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc --with-pgport=5432 \
--enable-hba --disable-locale
Tip: Of course, you may type these three lines all on the same
line.
Install the man and 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.
Compile the program. Type
$ cd /usr/src/pgsql/src
$ gmake all > make.log 2>&1 &
$ tail -f make.log
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. 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.)
Note: 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
$ gmake 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 2>&1 &
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 2>&1 &
$ 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. Remember, "gmake" may be called "make" on your system.
If necessary, tell your system how to find the new shared libraries.
You can do one of the following, preferably the first:
a. As root, edit file /etc/ld.so.conf. Add a 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.
If you used the --with-perl option to configure, check the install log
to see whether the Perl module was actually installed. If you've
followed our advice to make the Postgres files be owned by an
unprivileged userid, then the Perl module won't have been installed,
for lack of write privileges on the Perl library directories. You can
complete its installation, either now or later, by becoming the user
that does own the Perl library (often root) (via su) and doing
$ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install
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 Administrator's Guide for more
information.
Note: The following instructions are for a bash/sh shell. Adapt
accordingly for other shells.
a. Add the following lines to your login environment: 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
b. Several regression tests could fail if the user's locale collation
scheme is different from that of the standard C locale.
If you configure and compile Postgres with --enable-locale then
you should set the locale environment to "C" (or unset all "LC_*"
variables) by putting these additional lines to your login
environment before starting postmaster:
LC_COLLATE=C
LC_CTYPE=C
export LC_COLLATE LC_CTYPE
c. 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 installation from your Postgres superuser account
(typically account postgres). 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.
Briefly test that the backend will start and run by running it from
the command line.
a. Start the postmaster daemon running in the background by typing
$ cd
$ nohup postmaster -i > pgserver.log 2>&1 &
b. Create a database by typing
$ createdb
c. Connect to the new database:
$ psql
d. And run a sample query:
postgres=> SELECT datetime 'now';
e. Exit psql:
postgres=> \q
f. Remove the test database (unless you will want to use it later for
other tests):
$ destroydb
Run postmaster in the background from your Postgres superuser account
(typically account postgres). Do not run postmaster from the root
account!
Usually, you will want to modify your computer so that it will
automatically start postmaster whenever it boots. It is not required;
the Postgres server can be run successfully from non-privileged
accounts without root intervention.
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.
* If you are installing from a non-privileged account and have no
root access, then start the postmaster and send it to the
background:
$ cd
$ nohup postmaster > regress.log 2>&1 &
* 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.)
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:
a. 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.5.1 regression testing reference platform.
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 to do regular maintainence. The following should be done
at regular intervals:
Minimal Backup Procedure
1. Run the SQL command VACUUM. This will clean up your database.
2. 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_5
$ rm -rf /usr/local/pgsql_6_5
# Also delete old database directory tree if it is not in
# /usr/local/pgsql_6_5/data
$ rm ~/postgresql-v6.5.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.5.1, 6.5, beta 990318, 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!
______________________________________________________________________
Prev Home Next
Installation Playing with Postgres
Installation Procedure
Postgres Installation
For a fresh install or upgrading from previous
releases of Postgres:
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
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.
2. 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.
3. Log in to the Postgres superuser account. Most of
the remaining steps in the installation will
happen in this account.
4. Ftp file
ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.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. 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.
6. If you are not upgrading an existing system then
skip to step 9. If you are upgrading from 6.5, you
do not need to dump/reload or initdb. Simply
compile the source code, stop the postmaster, do a
"make install", and restart the postmaster.
If you are upgrading from 6.4.* or earlier,
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.
Tip: 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 > 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.5.1.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 (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.
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.
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 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.
Tip: 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.
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 but you must be consistent throughout
this procedure.
Note: 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
gmake 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
10. Unzip and untar the new source file. Type
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-v6.5.1.tar.gz | tar xvf -
11. 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 ]
a. 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.
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 (mailto:scrappy@hub.org)
with the output of the program
./config.guess. Indicate what the template
file should be.
b. Choose configuration options. Check
Configuration Options for details. However,
for a plain-vanilla first installation with
no extra options like multi-byte character
support or locale collation support it may be
adequate to have chosen the installation
areas and to run configure without extra
options specified. 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-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.)
c. Here is the configure script used on a Sparc
Solaris 2.5 system with /opt/postgres
specified as the installation base directory:
$ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc
--with-pgport=5432 \
--enable-hba --disable-locale
Tip: Of course, you may type these three
lines all on the same line.
12. Install the man and 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.
13. 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.
Remember, ?gmake? may be called ?make? on your system.
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.)
Note: 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
$ gmake 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.
14. 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. Remember, ?gmake? may
be called ?make? on your system.
15. If necessary, tell your system how to find
the new shared libraries. You can do one of the
following, preferably the first:
a. As root, edit file /etc/ld.so.conf. Add a
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.
16. If you used the --with-perl option to
configure, check the install log to see whether
the Perl module was actually installed. If you've
followed our advice to make the Postgres files be
owned by an unprivileged userid, then the Perl
module won't have been installed, for lack of
write privileges on the Perl library directories.
You can complete its installation, either now or
later, by becoming the user that does own the Perl
library (often root) (via su) and doing
$ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install
17. 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
Administrator's Guide for more information.
Note: The following instructions are for a
bash/sh shell. Adapt accordingly for other
shells.
a. Add the following lines to your login
environment: 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
b. Several regression tests could fail if the
user's locale collation scheme is different
from that of standard C locale.
If you configure and compile Postgres with
the --enable-locale option then set locale
environment to C (or unset all LC_*
variables) by putting these additional lines
to your login environment before starting
postmaster:
LC_COLLATE=C
LC_CTYPE=C
LC_COLLATE=C
export LC_COLLATE LC_CTYPE LC_COLLATE
c. 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
18. Create the database installation from your
Postgres superuser account (typically account
postgres). Do not do the following as root! This
would be a major security hole. Type
$ initdb
19. 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.
20. Briefly test that the backend will start and
run by running it from the command line.
a. Start the postmaster daemon running in the
background by typing
$ cd
$ nohup postmaster -i > pgserver.log 2>&1 &
b. Create a database by typing
$ createdb
c. Connect to the new database:
$ psql
d. And run a sample query:
postgres=> SELECT datetime 'now';
e. Exit psql:
postgres=> \q
f. Remove the test database (unless you will
want to use it later for other tests):
$ destroydb
21. Run postmaster in the background from your
Postgres superuser account (typically account
postgres). Do not run postmaster from the root
account!
Usually, you will want to modify your computer so
that it will automatically start postmaster
whenever it boots. It is not required; the
Postgres server can be run successfully from
non-privileged accounts without root intervention.
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.
o If you are installing from a non-privileged
account and have no root access, then start the
postmaster and send it to the background:
$ cd
$ nohup postmaster > regress.log 2>&1 &
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.
o 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.)
22. 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:
a. 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,
o For a i686/Linux-ELF platform, no tests
failed since this is the v6.5 regression
testing reference platform.
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.)
23. 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
1. Run the SQL command VACUUM. This will clean
up your database.
2. 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.)
24. 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.
25. If you are a new user, you may wish to play
with Postgres as described below.
26. Clean up after yourself. Type
$ rm -rf /usr/src/pgsql_6_5
$ rm -rf /usr/local/pgsql_6_5
# Also delete old database directory tree if it is
not in
# /usr/local/pgsql_6_5/data
$ rm ~/postgresql-v6.5.1.tar.gz
27. 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/ghostscr-
ipt/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
28. 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
(mailto:pgsql-ports@postgresql.org) telling us the
following:
o The version of Postgres (v6.5.1, 6.5, beta
990318, etc.).
o Your operating system (i.e. RedHat v5.2 Linux
v2.0.36).
o Your hardware (SPARC, i486, etc.).
o 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.
29. Now create, access and manipulate databases
as desired. Write client programs to access the
database server. In other words, enjoy!