Skip to content

P
Postgres FD Implementation
Commit 13f88750 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Added new pg_id to fix initdb problems 

New INSTALL file
Fixed a copyright notice
parent a959e3f7
Show whitespace changes
Inline Side-by-side
Showing with 835 additions and 2719 deletions
INSTALL
View file @ 13f88750
Installation instructions for PostgreSQL 7.0.0.
PostgreSQL Installation Guide
by The PostgreSQL Development Team
PostgreSQL is 1998-9 by the Postgres Global Development Group.
Table of Contents
Summary
1. Introduction
2. Ports
Currently Supported Platforms
Unsupported Platforms
3. Installation
Requirements to Run Postgres
Installation Procedure
Playing with Postgres
The Next Step
Porting Notes
4. Configuration Options
Parameters for Configuration (configure)
Parameters for Building (make)
Locale Support
What are the Benefits?
What are the Drawbacks?
Kerberos Authentication
Availability
Installation
Operation
5. Release Notes
Release 6.5.1
Migration to v6.5.1
Detailed Change List
Release 6.5
Migration to v6.5
Multi-Version Concurrency Control
Detailed Change List
Summary
Postgres, developed originally in the UC Berkeley
Computer Science Department, pioneered many of the
object-relational concepts now becoming available in
some commercial databases. It provides SQL92/SQL3
language support, transaction integrity, and type
extensibility. PostgreSQL is a public-domain, open
source descendant of this original Berkeley code.
Chapter 1. Introduction
This installation procedure makes some assumptions
about the desired configuration and runtime
environment for your system. This may be adequate for
many installations, and is almost certainly adequate
for a first installation. But you may want to do an
initial installation up to the point of unpacking the
source tree and installing documentation, and then
print or browse the Administrator's Guide.
Chapter 2. Ports
This manual describes version 6.5.1 of Postgres. The
Postgres developer community has compiled and tested
Postgres on a number of platforms. Check the web site
(http://www.postgresql.org/docs/admin/ports.htm) for
the latest information.
Currently Supported Platforms
At the time of publication, the following platforms
have been tested:
Table 2-1. Supported Platforms
OS Processor Version Reported Remarks
AIX 4.3.2 RS6000 v6.5 1999-05-26 (Andreas Zeugswetter
(mailto:Andreas.Zeugswetter@telecom.at))
BSDI x86 v6.5 1999-05-25 (Bruce Momjian
(mailto:maillist@candle.pha.pa.us)
FreeBSD x86 v6.5 1999-05-25 (Tatsuo Ishii
2.2.x-4.0 (mailto:t-ishii@sra.co.jp),
Marc Fournier
(mailto:scrappy@hub.org))
DGUX m88k v6.3 1998-03-01 v6.4 probably OK.
5.4R4.11 Needs new maintainer.
(Brian E Gallew
(mailto:geek+@cmu.edu))
Digital Alpha v6.4 1998-10-29 Minor patchable problems
Unix 4.0 (Pedro J. Lobo
(mailto:pjlobo@euitt.upm.es))
HPUX PA-RISC v6.4 1998-10-25 Both 9.0x and 10.20
(Tom Lane (mailto:tgl@sss.pgh.pa.us),
Stan Brown (mailto:stanb@awod.com))
IRIX 6.5 MIPS v6.4 1998-12-29 IRIX 5.x is different
(Mark Dalphin (mdalphin@amgen.com))
linux Alpha v6.3.2 1998-04-16 Mostly successful. Needs
2.0.x work for v6.4.
(Ryan Kirkpatrick
(mailto:rkirkpat@nag.cs.colorado.edu))
linux x86 v6.4 1998-10-27 (Thomas Lockhart
2.0.x/libc5 (mailto:lockhart@alumni.caltech.edu))
linux x86 v6.4 1999-05-24 (Thomas Lockhart
2.0.x/glibc2 (mailto:lockhart@alumni.caltech.edu))
linux MIPS v6.4 1998-12-16 Cobalt Qube (Tatsuo Ishii
2.0.x (mailto:t-ishii@sra.co.jp))
linux Sparc v6.4 1998-10-25 (Tom Szybist
2.0.x (mailto:szybist@boxhill.com))
linuxPPC PPC603e v6.4 1998-10-26 Powerbook 2400c
2.1.24 (Tatsuo Ishii
(mailto:t-ishii@sra.co.jp))
mklinux PPC750 v6.4 1998-09-16 PowerMac 7600
DR3 (Tatsuo Ishii
(mailto:t-ishii@sra.co.jp))
NetBSD arm32 v6.5 1999-04-14 (Andrew McMurry
(mailto:a.mcmurry1@physics.oxford.ac.uk))
NetBSD/i3- x86 v6.4 1998-10-25 (Brook Milligan
86 1.3.2 (mailto:brook@trillium.NMSU.Edu))
NetBSD m68k v6.4.2 1998-12-28 Mac SE/30 (Mr. Mutsuki
Nakajima, Tatsuo Ishii
(mailto:t-ishii@sra.co.jp))
NetBSD- NS32532 v6.4 1998-10-27 small problems
current in date/time math (Jon Buller
(mailto:jonb@metronet.com))
NetBSD/sp- Sparc v6.4 1998-10-27 (Tom I Helbekkmo
arc 1.3H (mailto:tih@hamartun.priv.no))
NetBSD 1.3 VAX v6.3 1998-03-01 (Tom I Helbekkmo
(mailto:tih@hamartun.priv.no))
SCO x86 v6.5 1999-05-25 (Andrew Merrill
OpenServer 5 (mailto:andrew@compclass.com))
SCO x86 v6.5 1999-05-25 (Andrew Merrill
UnixWare 7 (mailto:andrew@compclass.com))
Solaris x86 v6.4 1998-10-28 (Marc Fournier
(mailto:scrappy@hub.org))
Solaris Sparc v6.4 1998-10-28 (Tom Szybist
2.6-2.7 (mailto:szybist@boxhill.com),
Frank Ridderbusch
(mailto:ridderbusch.pad@sni.de))
SunOS Sparc v6.3 1998-03-01 Patches submitted
4.1.4 (Tatsuo Ishii
(mailto:t-ishii@sra.co.jp))
SVR4 MIPS v6.4 1998-10-28 No 64-bit int compiler
support (Frank Ridderbusch
(mailto:ridderbusch.pad@sni.de))
Windows x86 v6.4 1999-01-06 Client-side libraries
or ODBC/JDBC. No server yet.
(Magnus Hagander
(mha@sollentuna.net)
Windows NT x86 v6.5 1999-05-26 Working with the Cygwin
library. (Daniel Horak
(mailto:Dan.Horak@email.cz))
Platforms listed for v6.3.x and v6.4.x should also
work with v6.5.1, but we did not receive explicit
confirmation of such at the time this list was
compiled.
Note: For Windows NT, the server-side port of
Postgres has recently been accomplished. The
Cygnus library is required to compile it.
Unsupported Platforms
There are a few platforms which have been attempted
and which have been reported to not work with the
standard distribution. Others listed here do not
provide sufficient library support for an attempt.
Table 2-2. Possibly Incompatible Platforms
OS Processor Version Reported Remarks
MacOS all v6.3 1998-03-01 Not library compatible;
use ODBC/JDBC
NextStep x86 v6.x 1998-03-01 Client-only support;
v1.0.9 worked with patches
(David Wetzel
(mailto:dave@turbocat.de))
SVR4 4.4 m88k v6.2.1 1998-03-01 Confirmed
with patching;
v6.4.x will need TAS
spinlock code (Doug
Winterburn
(mailto:dlw@seavme.xroads.com))
Ultrix MIPS,VAX? v6.x 1998-03-01 No recent reports;
obsolete?
Chapter 3. Installation
Complete installation instructions for Postgres
v6.5.1.
Before installing Postgres, you may wish to visit
www.postgresql.org (http://www.postgresql.org) for up
to date information, patches, etc.
These installation instructions assume:
o Commands are Unix-compatible. See note below.
o Defaults are used except where noted.
o User postgres is the Postgres superuser.
o The source path is /usr/src/pgsql (other paths are
possible).
o The runtime path is /usr/local/pgsql (other paths
are possible).
Commands were tested on RedHat Linux version 5.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
(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
Commands were tested on RedHat Linux version 5.2 using the bash shell.
Except where noted, they will probably work on most systems. Commands like
ps and tar may vary wildly between platforms on what options you should use.
Use common sense before typing in these commands.
If you haven't gotten the PostgreSQL distribution, get it from
ftp.postgresql.org, then unpack it:
$ gunzip postgresql-7.0.0.tar.gz
$ tar -xf postgresql-7.0.0.tar
$ mv postgresql-7.0.0 /usr/src
Again, these commands might differ on your system.
Before you start
Building PostgreSQL requires GNU make. It will not work with other make
programs. On GNU/Linux systems GNU make is the default tool, on other
systems you may find that GNU make is installed under the name "gmake". We
will use that name from now on to indicate GNU make, no matter what name it
has on your system. To test for GNU make enter
$ gmake --version
If you need to get GNU make, you can find it at ftp://ftp.gnu.org.
Up to date information on supported platforms is at
http://www.postgresql.org/docs/admin/ports.htm. In general, most
Unix-compatible platforms with modern libraries should be able to run
PostgreSQL. In the doc subdirectory of the distribution are several
platform-specific FAQ and README documents you might wish to consult if you
are having trouble.
Although the minimum required memory for running PostgreSQL can be as little
as 8MB, there are noticable speed improvements when expanding memory up to
96MB or beyond. The rule is you can never have too much memory.
Check that you have sufficient disk space. You will need about 30 Mbytes for
the source tree during compilation and about 5 Mbytes for the installation
directory. An empty database takes about 1 Mbyte, otherwise they take about
five times the amount of space that a flat text file with the same data
would take. If you run the regression tests you will temporarily need an
extra 20MB.
To check for disk space, use
$ df -k
Considering today's prices for hard disks, getting a large and fast hard
disk should probably be in your plans before putting a database into
production use.
Installation Procedure
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
PostgreSQL Installation
For a fresh install or upgrading from previous releases of PostgreSQL:
1. Create the PostgreSQL superuser account. This is the user the server
will run as. For production use you should create a separate,
unprivileged account (postgres is commonly used). If you do not have
root access or just want to play around, your own user account is
enough.
Running PostgreSQL as root, bin, or any other account with special
access rights is a security risk and therefore won't be allowed.
You need not do the building and installation itself under this account
(although you can). You will be told when you need to login as the
database superuser.
2. If you are not upgrading an existing system then skip to step 4.
You now need to back up your existing database. To dump your fairly
recent post-6.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.
If you wish to preserve object id's (oids), then use the -o option when
running pg_dumpall. However, unless you have a special reason for doing
this (such as using OIDs as keys in tables), don't do it.
Make sure to use the pg_dumpall command from the version you are
currently running. However, do not use the pg_dumpall script from 6.0
or everything will be owned by the PostgreSQL super user. In that case
you should grab pg_dumpall from a later 6.x.x release. 7.0's pg_dumpall
will not work on older databases. If you are upgrading from a version
prior to Postgres95 v1.09 then you must back up your database, install
Postgres95 v1.09, restore your database, then back it up again.
Caution
You must make sure that your database is not
updated in the middle of your backup. If
necessary, bring down postmaster, edit the
permissions in file
/usr/local/pgsql/data/pg_hba.conf to allow
only you on, then bring postmaster back up.
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
You must make sure that your database is not updated in the middle of your
backup. If necessary, bring down postmaster, edit the permissions in file
/usr/local/pgsql/data/pg_hba.conf to allow only you on, then bring
postmaster back up.
3. If you are upgrading an existing system then kill the database server
now. Type
$ ps ax | grep postmaster
This should list the process numbers for a number of processes, similar
to this:
263 ? SW 0:00 (postmaster)
777 p1 S 0:00 grep postmaster
Type the following line, with pid replaced by the process id for
process postmaster (263 in the above case). (Do not use the id for the
process "grep postmaster".)
$ kill pid
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
Tip: On systems which have PostgreSQL started at boot time,
there is probably a startup file which will accomplish the
same thing. For example, on a Redhat Linux system one might
find that
$ /etc/rc.d/init.d/postgres.init stop
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
works.
Also move the old directories out of the way. Type the following:
$ mv /usr/local/pgsql /usr/local/pgsql.old
or replace your particular paths.
4. Configure the source code for your system. It is this step at which you
can specify your actual installation path for the build process and
make choices about what gets installed. Change into the src
subdirectory and type:
$ ./configure [ options ]
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
For a complete list of options, type:
./configure --help
Some of the more commonly used ones are:
--prefix=BASEDIR Selects a different
base directory for the
installation of 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
--prefix=BASEDIR
Selects a different base directory for the installation of
PostgreSQL. The default is /usr/local/pgsql.
--enable-locale
If you want to use locales.
--enable-multibyte
Allows the use of multibyte character encodings. This is primarily
for languages like Japanese, Korean, or Chinese.
--with-perl
Builds the Perl interface. Please note that the Perl interface
will be installed into the usual place for Perl modules (typically
under /usr/lib/perl), so you must have root access to use this
option successfully.
--with-odbc
Builds the ODBC driver package.
--with-tcl
Builds interface libraries and programs requiring Tcl/Tk,
including libpgtcl, pgtclsh, and pgtksh.
5. Compile the program. Type
$ gmake
The compilation process can take anywhere from 10 minutes to an hour.
Your milage will most certainly vary.
The last line displayed will hopefully be
All of PostgreSQL is successfully made. Ready to
install.
Remember, ?gmake? may be called ?make? on your system.
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
All of PostgreSQL is successfully made. Ready to install.
Remember, "gmake" may be called "make" on your system.
6. Install the program. Type
$ gmake install
7. Tell your system how to find the new shared libraries. How to do this
varies between platforms. What tends to work everywhere is to set the
environment variable LD_LIBRARY_PATH:
$ LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ export LD_LIBRARY_PATH
You might want to put this into a shell startup file such as
~/.bash_profile.
On some systems the following is the preferred method, but you must
have root access. Edit file /etc/ld.so.conf to add a line
/usr/local/pgsql/lib
Then run command /sbin/ldconfig.
If in doubt, refer to the manual pages of your system. If you later on
get a message like
./psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
then the above was necessary. Simply do this step then.
8. Create the database installation. To do this you must log in to your
PostgreSQL superuser account. It will not work as root.
$ mkdir /usr/local/pgsql/data
$ chown postgres /usr/local/pgsql/data
$ su - postgres
$ /usr/local/pgsql/initdb -D /usr/local/pgsql/data
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.
The -D option specifies the location where the data will be stored. You
can use any path you want, it does not have to be under the
installation directory. Just make sure that the superuser account can
write to it (or create it) before starting initdb.
Note: The following instructions are for a
bash/sh shell. Adapt accordingly for other
shells.
9. The previous step should have told you how to start up the database
server. Do so now.
$ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data
This will start the server in the foreground. To make it detach to the
background, use the -S.
10. If you are upgrading from an existing installation, dump your data back
in:
$ /usr/local/pgsql/bin/psql < db.out
You also might want to copy over the old pg_hba.conf file and any other
files you might have had set up for authentication, such as password
files.
This concludes the installation proper. To make your life more productive
and enjoyable you should look at the following optional steps and
suggestions.
* Life will be more convenient if you set up some enviroment variables.
First of all you probably want to include /usr/local/pgsql/bin (or
equivalent) into your PATH. To do this, add the following to your shell
startup file, such as ~/.bash_profile (or /etc/profile, if you want it
to affect every user):
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
Furthermore, if you set PGDATA in the environment of the PostgreSQL
superuser, you can omit the -D for postmaster and initdb.
* You probably want to install the man and HTML documentation. Type
$ cd /usr/src/pgsql/postgresql-7.0.0/doc
$ gmake install
This will install files under /usr/local/pgsql/doc.
The documentation is also available in Postscript format. If you have a
Postscript printer, or have your machine already set up to accept
Postscript files using a print filter, then to print the User's Guide
simply type
$ cd /usr/local/pgsql/doc
$ gunzip -c user.ps.tz | lpr
Here is how you might do it if you have Ghostscript on your system and
are writing to a laserjet printer.
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
If in doubt, confer your manuals or your local expert.
The Adminstrator's Guide should probably be your first reading if you
are completely new to PostgreSQL, as it contains information about how
to set up database users and authentication.
* Usually, you will want to modify your computer so that it will
automatically start the database server whenever it boots. This is not
required; the PostgreSQL server can be run successfully from
non-privileged accounts without root intervention.
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
Different systems have different conventions for starting up daemons at
boot time, so you are advised to familiarize yourself with them. Most
systems have a file /etc/rc.local or /etc/rc.d/rc.local which is almost
certainly no bad place to put such a command. Whatever you do,
postmaster must be run by the PostgreSQL superuser (postgres) and not
by root or any other user. Therefore you probably always want to form
your command lines along the lines of su -c '...' postgres.
It might be advisable to keep a log of the server output. To start the
server that way try:
nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
Here are a few more operating system specific suggestions.
o Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris 2.5.1
to contain the following single line:
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
o In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
contain the following lines and make it chmod 755 and chown
root:bin.
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec
/usr/local/pgsql/bin/postmaster
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!
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.
Check on the web site at http://www.postgresql.org
For more information on the various support mailing
lists.
Porting Notes
Check for any platform-specific FAQs in the doc/
directory of the source distribution.
Chapter 4. Configuration Options
Parameters for Configuration (configure)
The full set of parameters available in configure
can be obtained by typing
$ ./configure --help
The following parameters may be of interest to
installers:
Directory and file names:
--prefix=PREFIX install
architecture-independent files in PREFIX
[/usr/local/pgsql]
--bindir=DIR user executables in DIR
[EPREFIX/bin]
--libdir=DIR object code libraries in
DIR [EPREFIX/lib]
--includedir=DIR C header files in DIR
[PREFIX/include]
--mandir=DIR man documentation in DIR
[PREFIX/man]
Features and packages:
--disable-FEATURE do not include FEATURE
(same as --enable-FEATURE=no)
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as
--with-PACKAGE=no)
--enable and --with options recognized:
--with-template=template
use operating system
template file
see template directory
--with-includes=incdir site header files for
tk/tcl, etc in DIR
--with-libs=incdir also search for libraries
in DIR
--with-libraries=libdir also search for libraries
in DIR
--enable-locale enable locale support
--enable-recode enable cyrillic recode
support
--with-mb=encoding enable multi-byte support
--with-pgport=portnum change default startup port
--with-maxbackends=n set default maximum number of
server processes
--with-tcl build Tcl interfaces and
pgtclsh
--with-tclconfig=tcldir tclConfig.sh and
tkConfig.sh are in DIR
--with-perl build Perl interface
--with-odbc build ODBC driver package
--with-odbcinst=odbcdir change default directory
for odbcinst.ini
--enable-cassert enable assertion checks
(debugging)
--with-CC=compiler use specific C compiler
--with-CXX=compiler use specific C++ compiler
--without-CXX prevent building C++ code
Some systems may have trouble building a specific
feature of Postgres. For example, systems with a
damaged C++ compiler may need to specify
--without-CXX to instruct the build procedure to skip
construction of libpq++.
Parameters for Building (make)
Many installation-related parameters can be set in
the building stage of Postgres installation.
In most cases, these parameters should be placed in
a file, Makefile.custom, intended just for that
purpose. The default distribution does not contain
this optional file, so you will create it using a
text editor of your choice. When upgrading
installations, you can simply copy your old
Makefile.custom to the new installation before doing
the build.
make [ variable=value [,...] ]
A few of the many variables which can be specified
are:
POSTGRESDIR
Top of the installation tree.
BINDIR
Location of applications and utilities.
LIBDIR
Location of object libraries, including shared
libraries.
HEADERDIR
Location of include files.
ODBCINST
Location of installation-wide psqlODBC (ODBC)
configuration file.
There are other optional parameters which are not as
commonly used. Many of those listed below are
appropriate when doing Postgres server code
development.
CFLAGS
Set flags for the C compiler. Should be assigned
with "+=" to retain relevant default parameters.
YFLAGS
Set flags for the yacc/bison parser. -v might be
used to help diagnose problems building a new
parser. Should be assigned with "+=" to retain
relevant default parameters.
USE_TCL
Enable Tcl interface building.
HSTYLE
DocBook HTML style sheets for building the
documentation from scratch. Not used unless you
are developing new documentation from the
DocBook-compatible SGML source documents in
doc/src/sgml/.
PSTYLE
DocBook style sheets for building printed
documentation from scratch. Not used unless you
are developing new documentation from the
DocBook-compatible SGML source documents in
doc/src/sgml/.
Here is an example Makefile.custom for a PentiumPro
Linux system:
# Makefile.custom
# Thomas Lockhart 1998-03-01
POSTGRESDIR= /opt/postgres/current
CFLAGS+= -m486 # -g -O0
USE_TCL= true
TCL_LIB= -ltcl
X_LIBS= -L/usr/X11/lib
TK_LIB= -ltk
# documentation
HSTYLE= /home/tgl/SGML/db118.d/docbook/html
PSTYLE= /home/tgl/SGML/db118.d/docbook/print
Locale Support
Note: Written by Oleg Bartunov. See Oleg's web
page (http://www.sai.msu.su/~megera/postgres/) for
additional information on locale and Russian
language support.
While doing a project for a company in Moscow,
Russia, I encountered the problem that postgresql had
no support of national alphabets. After looking for
possible workarounds I decided to develop support of
locale myself. I'm not a C-programer but already had
some experience with locale programming when I work
with perl (debugging) and glimpse. After several days
of digging through the Postgres source tree I made
very minor corections to
src/backend/utils/adt/varlena.c and
src/backend/main/main.c and got what I needed! I did
support only for LC_CTYPE and LC_COLLATE, but later
LC_MONETARY was added by others. I got many messages
from people about this patch so I decided to send it
to developers and (to my surprise) it was
incorporated into the Postgres distribution.
People often complain that locale doesn't work for
them. There are several common mistakes:
o Didn't properly configure postgresql before
compilation. You must run configure with
--enable-locale option to enable locale support.
Didn't setup environment correctly when starting
postmaster. You must define environment variables
LC_CTYPE and LC_COLLATE before running postmaster
because backend gets information about locale from
environment. I use following shell script
(runpostgres):
#!/bin/sh
export LC_CTYPE=koi8-r
export LC_COLLATE=koi8-r
postmaster -B 1024 -S
-D/usr/local/pgsql/data/ -o '-Fe'
and run it from rc.local as
/bin/su - postgres -c
"/home/postgres/runpostgres"
o Broken locale support in OS (for example, locale
support in libc under Linux several times has
changed and this caused a lot of problems). Latest
perl has also support of locale and if locale is
broken perl -v will complain something like:
8:17[mira]:~/WWW/postgres>setenv LC_CTYPE
not_exist
8:18[mira]:~/WWW/postgres>perl -v
perl: warning: Setting locale failed.
perl: warning: Please check that your locale
settings:
LC_ALL = (unset),
LC_CTYPE = "not_exist",
LANG = (unset)
are supported and installed on your system.
perl: warning: Falling back to the standard
locale ("C").
o Wrong location of locale files! Possible locations
include: /usr/lib/locale (Linux, Solaris),
/usr/share/locale (Linux), /usr/lib/nls/loc (DUX
4.0). Check man locale to find the correct
location. Under Linux I did a symbolic link between
/usr/lib/locale and /usr/share/locale to be sure
that the next libc will not break my locale.
What are the Benefits?
You can use ~* and order by operators for strings
contain characters from national alphabets.
Non-english users definitely need that. If you won't
use locale stuff just undefine the USE_LOCALE
variable.
What are the Drawbacks?
There is one evident drawback of using locale - its
speed! So, use locale only if you really need it.
Kerberos Authentication
Kerberos is an industry-standard secure
authentication system suitable for distributed
computing over a public network.
Availability
The Kerberos authentication system is not
distributed with Postgres. Versions of Kerberos are
typically available as optional software from
operating system vendors. In addition, a source code
distribution may be obtained through MIT Project
Athena (ftp://athena-dist.mit.edu).
Note: You may wish to obtain the MIT version even
if your vendor provides a version, since some
vendor ports have been deliberately crippled or
rendered non-interoperable with the MIT version.
Users located outside the United States of America
and Canada are warned that distribution of the actual
encryption code in Kerberos is restricted by U. S.
Government export regulations.
Inquiries regarding your Kerberos should be directed
to your vendor or MIT Project Athena
(info-kerberos@athena.mit.edu). Note that FAQLs
(Frequently-Asked Questions Lists) are periodically
posted to the Kerberos mailing list
(mailto:kerberos@ATHENA.MIT.EDU) (send mail to
subscribe (mailto:kerberos-request@ATHENA.MIT.EDU)),
and USENET news group (news:comp.protocols.kerberos).
Installation
Installation of Kerberos itself is covered in detail
in the Kerberos Installation Notes . Make sure that
the server key file (the srvtab or keytab) is somehow
readable by the Postgres account.
Postgres and its clients can be compiled to use
either Version 4 or Version 5 of the MIT Kerberos
protocols by setting the KRBVERS variable in the file
src/Makefile.global to the appropriate value. You can
also change the location where Postgres expects to
find the associated libraries, header files and its
own server key file.
After compilation is complete, Postgres must be
registered as a Kerberos service. See the Kerberos
Operations Notes and related manual pages for more
details on registering services.
Operation
After initial installation, Postgres should operate
in all ways as a normal Kerberos service. For details
on the use of authentication, see the PostgreSQL
User's Guide reference sections for postmaster and
psql.
In the Kerberos Version 5 hooks, the following
assumptions are made about user and service naming:
o User principal names (anames) are assumed to
contain the actual Unix/Postgres user name in the
first component.
o The Postgres service is assumed to be have two
components, the service name and a hostname,
canonicalized as in Version 4 (i.e., with all
domain suffixes removed).
Table 4-1. Kerberos Parameter Examples
Parameter Example
user frew@S2K.ORG
user aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
host postgres_dbms/ucbvax@S2K.ORG
Support for Version 4 will disappear sometime after
the production release of Version 5 by MIT.
Chapter 5. Release Notes
Release 6.5
This release marks a major step in the development
team's mastery of the source code we inherited from
Berkeley. You will see we are now easily adding major
features, thanks to the increasing size and
experience of our world-wide development team.
Here is a brief summary of some of the more
noticable changes:
Multi-version concurrency control(MVCC)
This removes our old table-level locking, and
replaces it with a locking system that is superior
to most commercial database systems. In a
traditional system, each row that is modified is
locked until committed, preventing reads by other
users. MVCC uses the natural multi-version nature
of PostgreSQL to allow readers to continue reading
consistent data during writer activity. Writers
continue to use the compact pg_log transaction
system. This is all performed without having to
allocate a lock for every row like traditional
database systems. So, basically, we no longer are
restricted by simple table-level locking; we have
something better than row-level locking.
Numeric data type
We now have a true numeric data type, with
user-specified precision.
Temporary tables
Temporary tables are guaranteed to have unique
names within a database session, and are destroyed
on session exit.
New SQL features
We now have CASE, INTERSECT, and EXCEPT statement
support. We have new LIMIT/OFFSET, SET TRANSACTION
ISOLATION LEVEL, SELECT ... FOR UPDATE, and an
improved LOCK command.
Speedups
We continue to speed up PostgreSQL, thanks to the
variety of talents within our team. We have sped
up memory allocation, optimization, table joins,
and row transfer routines.
Ports
We continue to expand our port list, this time
including WinNT/ix86 and NetBSD/arm32.
Interfaces
Most interfaces have new versions, and existing
functionality has been improved.
Migration to v6.5
A dump/restore using pg_dump or pg_dumpall is
required for those wishing to migrate data from any
previous release of Postgres.
The new Multi-Version Concurrency Control (MVCC)
features can give somewhat different behaviors in
multi-user environments. Read and understand the
following section to ensure that your existing
applications will give you the behavior you need.
Multi-Version Concurrency Control
Because readers in 6.5 don't lock data, regardless
of transaction isolation level, data read by one
transaction can be overwritten by another. In the
other words, if a row is returned by SELECT it
doesn't mean that this row really exists at the time
it is returned (i.e. sometime after the statement or
transaction began) nor that the row is protected from
deletion or updation by concurrent transactions
before the current transaction does a commit or
rollback.
To ensure the actual existance of a row and protect
it against concurrent updates one must use SELECT FOR
UPDATE or an appropriate LOCK TABLE statement. This
should be taken into account when porting
applications from previous releases of Postgres and
other environments.
Keep above in mind if you are using contrib/refint.*
triggers for referential integrity. Additional
technics are required now. One way is to use LOCK
parent_table IN SHARE ROW EXCLUSIVE MODE command if a
transaction is going to update/delete a primary key
and use LOCK parent_table IN SHARE MODE command if a
transaction is going to update/insert a foreign key.
Note: Note that if you run a transaction in
SERIALIZABLE mode then you must execute LOCK
commands above before execution of any DML
statement
(SELECT/INSERT/DELETE/UPDATE/FETCH/COPY_TO) in the
transaction.
These inconveniences will disappear in the future
when the ability to read dirty (uncommitted) data
(regardless of isolation level) and true referential
integrity will be implemented.
Detailed Change List
Bug Fixes
---------
Fix text<->float8 and text<->float4 conversion
functions(Thomas)
Fix for creating tables with mixed-case
constraints(Billy)
Change exp()/pow() behavior to generate error on
underflow/overflow(Jan)
Fix bug in pg_dump -z
Memory overrun cleanups(Tatsuo)
Fix for lo_import crash(Tatsuo)
Adjust handling of data type names to suppress double
quotes(Thomas)
Use type coersion for matching columns and
DEFAULT(Thomas)
Fix deadlock so it only checks once after one second
of sleep(Bruce)
Fixes for aggregates and PL/pgsql(Hiroshi)
Fix for subquery crash(Vadim)
Fix for libpq function PQfnumber and case-insensitive
names(Bahman Rafatjoo)
Fix for large object write-in-middle, no extra block,
memory consumption(Tatsuo)
Fix for pg_dump -d or -D and quote special
characters in INSERT
Repair serious problems with dynahash(Tom)
Fix INET/CIDR portability problems
Fix problem with selectivity error in ALTER TABLE ADD
COLUMN(Bruce)
Fix executor so mergejoin of different column types
works(Tom)
Fix for Alpha OR selectivity bug
Fix OR index selectivity problem(Bruce)
Fix so \d shows proper length for
char()/varchar()(Ryan)
Fix tutorial code(Clark)
Improve destroyuser checking(Oliver)
Fix for Kerberos(Rodney McDuff)
Fix for dropping database while dirty buffers(Bruce)
Fix so sequence nextval() can be
case-sensitive(Bruce)
Fix !!= operator
Drop buffers before destroying database files(Bruce)
Fix case where executor evaluates functions
twice(Tatsuo)
Allow sequence nextval actions to be
case-sensitive(Bruce)
Fix optimizer indexing not working for negative
numbers(Bruce)
Fix for memory leak in executor with fjIsNull
Fix for aggregate memory leaks(Erik Riedel)
Allow username containing a dash GRANT permissions
Cleanup of NULL in inet types
Clean up system table bugs(Tom)
Fix problems of PAGER and \? command(Masaaki Sakaida)
Reduce default multi-segment file size limit to
1GB(Peter)
Fix for dumping of CREATE OPERATOR(Tom)
Fix for backward scanning of cursors(Hiroshi Inoue)
Fix for COPY FROM STDIN when using \i(Tom)
Fix for subselect is compared inside an
expression(Jan)
Fix handling of error reporting while returning
rows(Tom)
Fix problems with reference to array types(Tom,Jan)
Prevent UPDATE SET oid(Jan)
Fix pg_dump so -t option can handle case-sensitive
tablenames
Fixes for GROUP BY in special cases(Tom, Jan)
Fix for memory leak in failed queries(Tom)
DEFAULT now supports mixed-case identifiers(Tom)
Fix for multi-segment uses of DROP/RENAME table,
indexes(Ole Gjerde)
Enhancements
------------
Add "vacuumdb" utility
Speed up libpq by allocating memory better(Tom)
EXPLAIN all indices used(Tom)
Implement CASE, COALESCE, NULLIF expression(Thomas)
New pg_dump table output format(Constantin)
Add string min()/max() functions(Thomas)
Extend new type coersion techniques to
aggregates(Thomas)
New moddatetime contrib(Terry)
Update to pgaccess 0.96(Constantin)
Add routines for single-byte "char" type(Thomas)
Improved substr() function(Thomas)
Improved multi-byte handling(Tatsuo)
Multi-version concurrency control/MVCC(Vadim)
New Serialized mode(Vadim)
Fix for tables over 2gigs(Peter)
New SET TRANSACTION ISOLATION LEVEL(Vadim)
New LOCK TABLE IN ... MODE(Vadim)
Update ODBC driver(Byron)
New NUMERIC data type(Jan)
New SELECT FOR UPDATE(Vadim)
Handle "NaN" and "Infinity" for input values(Jan)
Improved date/year handling(Thomas)
Improved handling of backend connections(Magnus)
New options ELOG_TIMESTAMPS and USE_SYSLOG options
for log files(Massimo)
New TCL_ARRAYS option(Massimo)
New INTERSECT and EXCEPT(Stefan)
New pg_index.indisprimary for primary key
tracking(D'Arcy)
New pg_dump option to allow dropping of tables before
creation(Brook)
Speedup of row output routines(Tom)
New READ COMMITTED isolation level(Vadim)
New TEMP tables/indexes(Bruce)
Prevent sorting if result is already sorted(Jan)
New memory allocation optimization(Jan)
Allow psql to do \p\g(Bruce)
Allow multiple rule actions(Jan)
Added LIMIT/OFFSET functionality(Jan)
Improve optimizer when joining a large number of
tables(Bruce)
New intro to SQL from S. Simkovics' Master's Thesis
(Stefan, Thomas)
New intro to backend processing from S. Simkovics'
Master's Thesis (Stefan)
Improved int8 support(Ryan Bradetich, Thomas, Tom)
New routines to convert between int8 and text/varchar
types(Thomas)
New bushy plans, where meta-tables are joined(Bruce)
Enable right-hand queries by default(Bruce)
Allow reliable maximum number of backends to be set
at configure time
(--with-maxbackends and postmaster switch (-N
backends))(Tom)
GEQO default now 10 tables because of optimizer
speedups(Tom)
Allow NULL=Var for MS-SQL portability(Michael, Bruce)
Modify contrib check_primary_key() so either
"automatic" or "dependent"(Anand)
Allow psql \d on a view show query(Ryan)
Speedup for LIKE(Bruce)
Ecpg fixes/features, see
src/interfaces/ecpg/ChangeLog file(Michael)
JDBC fixes/features, see
src/interfaces/jdbc/CHANGELOG(Peter)
Make % operator have precedence like /(Bruce)
Add new postgres -O option to allow system table
structure changes(Bruce)
Update contrib/pginterface/findoidjoins script(Tom)
Major speedup in vacuum of deleted rows with
indexes(Vadim)
Allow non-SQL functions to run different versions
based on arguments(Tom)
Add -E option that shows actual queries sent by \dt
and friends(Masaaki Sakaida)
Add version number in startup banners for
psql(Masaaki Sakaida)
New contrib/vacuumlo removes large objects not
referenced(Peter)
New initialization for table sizes so non-vacuumed
tables perform better(Tom)
Improve error messages when a connection is
rejected(Tom)
Support for arrays of char() and varchar()
fields(Massimo)
Overhaul of hash code to increase reliability and
performance(Tom)
Update to PyGreSQL 2.4(D'Arcy)
Changed debug options so -d4 and -d5 produce
different node displays(Jan)
New pg_options: pretty_plan, pretty_parse,
pretty_rewritten(Jan)
Better optimization statistics for system table
access(Tom)
Better handling of non-default block sizes(Massimo)
Improve GEQO optimizer memory consumption(Tom)
UNION now suppports ORDER BY of columns not in target
list(Jan)
Major libpq++ improvements(Vince Vielhaber)
Source Tree Changes
-------------------
Improve port matching(Tom)
Portability fixes for SunOS
Add NT/Win32 backend port and enable dynamic
loading(Magnus and Daniel Horak)
New port to Cobalt Qube(Mips) running Linux(Tatsuo)
Port to NetBSD/m68k(Mr. Mutsuki Nakajima)
Port to NetBSD/sun3(Mr. Mutsuki Nakajima)
Port to NetBSD/macppc(Toshimi Aoki)
Fix for tcl/tk configuration(Vince)
Removed CURRENT keyword for rule queries(Jan)
NT dynamic loading now works(Daniel Horak)
Add ARM32 support(Andrew McMurry)
Better support for HPUX 11 and Unixware
Improve file handling to be more uniform, prevent
file descriptor leak(Tom)
New install commands for plpgsql(Jan)
You may put the line breaks as shown above. The shell is smart
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under the
postmaster process so the parent is init.
o In RedHat Linux add a file /etc/rc.d/init.d/postgres.init which is
based on the example in contrib/linux/. Then make a softlink to
this file from /etc/rc.d/rc5.d/S98postgres.init.
* Run the regression tests. The regression tests are a test suite to
verify that PostgreSQL runs on your machine in the way the developers
expected it to. You should definitely do this before putting a server
into production use. The file
/usr/src/pgsql/postgresql-7.0.0/src/test/regress/README has detailed
instructions for running and interpreting the regression tests.
doc/src/sgml/install.sgml
View file @ 13f88750
......@@ -3,52 +3,13 @@
<Abstract>
<Para>
Complete installation instructions for
<ProductName>Postgres</ProductName> 6.5.3.
Installation instructions for
<ProductName>PostgreSQL</ProductName> 7.0.0.
</Para>
</Abstract>
<Para>
Before installing <ProductName>Postgres</ProductName>, you may wish to visit
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
for up to date information, patches, etc.
</Para>
<Para>
These installation instructions assume:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Commands are Unix-compatible. See note below.
</Para>
</ListItem>
<ListItem>
<Para>
Defaults are used except where noted.
</Para>
</ListItem>
<ListItem>
<Para>
User <literal>postgres</literal> is the
<ProductName>Postgres</ProductName> superuser.
</Para>
</ListItem>
<ListItem>
<Para>
The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
<ListItem>
<Para>
The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 5.2 using the tcsh shell.
Commands were tested on RedHat Linux version 5.2 using the bash shell.
Except where noted, they will probably work on most systems. Commands
like <command>ps</command> and <command>tar</command> may vary wildly
between platforms on what options you should use.
......@@ -56,60 +17,70 @@
</Para>
<Para>
Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs. If you
have GNU <Application>make</Application> installed under the name
<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
command <command>make</command> instead. That's OK, but
you need to have the GNU form of <Application>make</Application> to succeed with
an installation.
If you haven't gotten the <ProductName>PostgreSQL</ProductName> distribution,
get it from <ULink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ULink>,
then unpack it:
<ProgramListing>
$ gunzip postgresql-7.0.0.tar.gz
$ tar -xf postgresql-7.0.0.tar
$ mv postgresql-7.0.0 /usr/src
</ProgramListing>
Again, these commands might differ on your system.
</Para>
<Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
<Title>Before you start</Title>
<Para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/install.htm">
http://www.postgresql.org/docs/admin/install.htm</ulink>.
Building <Productname>PostgreSQL</Productname> requires <acronym>GNU</acronym>
<Application>make</Application>. It will <Emphasis>not</Emphasis>
work with other <Application>make</Application> programs. On GNU/Linux systems
GNU make is the default tool, on other systems you may find that
GNU <Application>make</Application> is installed under the name <Quote>gmake</Quote>.
We will use that name from now on to indicate <acronym>GNU</acronym>
<Application>make</Application>, no matter what name it has on your system.
To test for <acronym>GNU</acronym> <Application>make</Application> enter
<programlisting>
$ <userinput>gmake --version</userinput>
</programlisting>
If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can
find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>.
</Para>
In general, most Unix-compatible
platforms with modern libraries should be able to run
<ProductName>Postgres</ProductName>.
<Para>
Up to date information on supported platforms is at
<ulink url="http://www.postgresql.org/docs/admin/ports.htm">
http://www.postgresql.org/docs/admin/ports.htm</ulink>.
In general, most Unix-compatible platforms with modern libraries should be able to run
<ProductName>PostgreSQL</ProductName>. In the <filename>doc</filename> subdirectory
of the distribution are several platform-specific FAQ and README documents you
might wish to consult if you are having trouble.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
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.
Although the minimum required memory for running <ProductName>PostgreSQL</ProductName>
can be as little as 8MB, there are noticable speed improvements when expanding memory
up to 96MB or beyond. The rule is you can never have too much memory.
</para>
<Para>
Check that you have sufficient disk space. You will need about
30 Mbytes for <filename>/usr/src/pgsql</filename>,
about 5 Mbytes for <filename>/usr/local/pgsql</filename>
(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.
</Para>
<Para>
We therefore recommend that during installation and testing you
have well over 20 Mbytes free under <filename>/usr/local</filename> 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 <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
database, plus about five times the space you would require to
store your database data in a flat file.
30 Mbytes for the source tree during compilation and about 5 Mbytes for
the installation directory. An empty database takes about 1 Mbyte, otherwise
they take about five times the amount of space that a flat text file with the
same data would take. If you run the regression tests you will temporarily need
an extra 20MB.
</Para>
<Para>
To check for disk space, use
<programlisting>
<programlisting>
$ df -k
</programlisting>
</programlisting>
</para>
<para>
Considering today's prices for hard disks, getting a large and fast hard disk should
probably be in your plans before putting a database into production use.
</para>
</Sect1>
......@@ -117,112 +88,45 @@ $ df -k
<Title>Installation Procedure</Title>
<Procedure>
<Title><ProductName>Postgres</ProductName> Installation</Title>
<Title><ProductName>PostgreSQL</ProductName> Installation</Title>
<Para>
For a fresh install or upgrading from previous releases of
<ProductName>Postgres</ProductName>:
</Para>
<Step Performance="required">
<Para>
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 <FileName>/usr/src/pgsql/postgresql-6.5.3/doc</FileName>, including files FAQ-Irix
and FAQ-Linux. Also look in directory
<ULink url="ftp://ftp.postgresql.org/pub">ftp://ftp.postgresql.org/pub</ULink>.
If there is a file called INSTALL in this directory then this
file will contain the latest installation information.
</Para>
<Para>
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 <ProductName>Postgres</ProductName> 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
<ULink url="ftp://ftp.postgresql.org/pub/INSTALL">ftp://ftp.postgresql.org/pub/INSTALL</ULink>.
<ProductName>PostgreSQL</ProductName>:
</Para>
</Step>
<Step Performance="optional">
<Para>
Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist.
Create the <ProductName>PostgreSQL</ProductName> superuser account.
This is the user the server will run as. For production use you
should create a separate, unprivileged account (<literal>postgres</literal> is
commonly used). If you do not have root access or just want to play around,
your own user account is enough.
</para>
<para>
The owner of the Postgres files can be any unprivileged user account.
It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights, as that would create a security risk.
</para>
</Step>
<Step Performance="required">
<Para>
Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the
remaining steps in the installation will happen in this account.
Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights is a security risk and therefore
won't be allowed.
</para>
</step>
<Step Performance="required">
<Para>
Ftp file
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz">
<filename>ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz</filename></ulink>
from the Internet. Store it in your home directory.
You need not do the building and installation itself under this account
(although you can). You will be told when you need to login as the
database superuser.
</Para>
</Step>
<Step Performance="required">
<Para>
If you are not upgrading an existing system then skip to
<xref linkend="newdirs">.
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.
</para>
<tip>
<para>
Do not use the <application>pg_dumpall</application>
script from 6.0 or everything
will be owned by the <ProductName>Postgres</ProductName> super user.
</para>
</tip>
<xref linkend="continue">.
</Para>
<para>
<Para>
You now need to back up your existing database.
To dump your fairly recent post-6.0 database installation, type
<programlisting>
$ pg_dumpall > db.out
</programlisting>
</para>
<para>
To use the latest <application>pg_dumpall</application> script on your
existing older database before upgrading <productname>Postgres</productname>,
pull the most recent version of <application>pg_dumpall</application>
from the new distribution:
<ProgramListing>
$ cd
$ gunzip -c postgresql-6.5.3.tar.gz \
| tar xvf - postgresql-6.5.3/src/bin/pg_dump/pg_dumpall
$ chmod a+x postgresql-6.5.3/src/bin/pg_dump/pg_dumpall
$ postgresql-6.5.3/src/bin/pg_dump/pg_dumpall > db.out
$ rm -rf postgresql-6.5.3
</ProgramListing>
</Para>
<Para>
If you wish to preserve object id's (oids), then use the -o
option when running <application>pg_dumpall</application>.
However, unless you have a
......@@ -231,23 +135,18 @@ in tables), don't do it.
</Para>
<Para>
If the <application>pg_dumpall</application> command
seems to take a long time and you think
it might have died, then, from another terminal, type
<programlisting>
$ ls -l db.out
</programlisting>
several times to see if the size of the file is growing.
</Para>
<Para>
Please note that if you are upgrading from a version prior to
<ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
install
<ProductName>Postgres95</ProductName> v1.09, restore your database,
then back it up again.
You should also read the release notes which should cover any
release-specific issues.
Make sure to use the <application>pg_dumpall</application>
command from the version you are currently running.
However, do not use the <application>pg_dumpall</application>
script from 6.0 or everything will be owned by the
<ProductName>PostgreSQL</ProductName> super user. In that case
you should grab <application>pg_dumpall</application> from a later
6.x.x release. 7.0's <application>pg_dumpall</application>
will not work on older databases.
If you are upgrading from a version prior to
<ProductName>Postgres95</ProductName> v1.09 then you must back up your database,
install <ProductName>Postgres95</ProductName> v1.09, restore your database,
then back it up again.
</Para>
<caution>
......@@ -259,572 +158,330 @@ $ ls -l db.out
bring <application>postmaster</application> back up.
</Para>
</caution>
</Step>
<Step Performance="required">
<Para>
If you are upgrading an existing system then kill the postmaster. Type
If you are upgrading an existing system then kill the database server now. Type
<ProgramListing>
$ ps -ax | grep postmaster
$ ps ax | grep postmaster
</ProgramListing>
This should list the process numbers for a number of processes. Type
the following line, with <replaceable>pid</replaceable>
replaced by the process id for process
<literal>postmaster</literal>.
(Do not use the id for process "grep postmaster".) Type
This should list the process numbers for a number of processes, similar
to this:
<ProgramListing>
263 ? SW 0:00 (postmaster)
777 p1 S 0:00 grep postmaster
</ProgramListing>
Type the following line, with <replaceable>pid</replaceable>
replaced by the process id for process <literal>postmaster</literal>
(263 in the above case). (Do not use the id for the process "grep postmaster".)
<programlisting>
$ kill <replaceable>pid</replaceable>
</programlisting>
to actually stop the process.
</Para>
<tip>
<para>
On systems which have <productname>Postgres</productname> 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
On systems which have <productname>PostgreSQL</productname> started at boot time, there
is probably a startup file which will accomplish the same thing. For example, on a
Redhat Linux system one might find that
<programlisting>
$ /etc/rc.d/init.d/postgres.init stop
</programlisting>
to halt <productname>Postgres</productname>.
works.
</para>
</tip>
</Para>
</Step>
<Step Performance="required">
<Para>
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 <filename>/usr/local/pgsql/data</filename> directory tree. At a
minimum, save file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
</Para>
<Para>
Type the following:
Also move the old directories out of the way. Type the following:
<programlisting>
$ su -
$ cd /usr/src
$ mv pgsql pgsql.old
$ cd /usr/local
$ mv pgsql pgsql.old
$ exit
$ mv /usr/local/pgsql /usr/local/pgsql.old
</programlisting>
or replace your particular paths.
</Para>
<Para>
If you are not using <filename>/usr/local/pgsql/data</filename>
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.
</Para>
</Step>
<Step Performance="required" id="newdirs">
<Para>
Make new source and install directories. The actual paths can be
different for your installation but you must be consistent throughout this procedure.
</para>
<note>
<para>
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 <command>gmake install</command> stage
of installation.
</para>
</note>
<para>
Type
<ProgramListing>
$ su
$ cd /usr/src
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ cd /usr/local
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ exit
</ProgramListing>
</Para>
</Step>
<Step Performance="required">
<Step Performance="required" id="continue">
<Para>
Unzip and untar the new source file. Type
Configure the source code for your system. It is this step at which
you can specify your actual installation path for the build process
and make choices about what gets installed. Change into the <filename>src</filename>
subdirectory and type:
<ProgramListing>
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-6.5.3.tar.gz | tar xvf -
$ ./configure [ <replaceable>options</replaceable> ]
</ProgramListing>
</Para>
</Step>
<Step Performance="required">
<Para>
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
For a complete list of options, type:
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ ./configure [ <replaceable>options</replaceable> ]
./configure --help
</ProgramListing>
</Para>
<substeps>
Some of the more commonly used ones are:
<VariableList>
<varlistentry>
<term>--prefix=BASEDIR</term>
<listitem>
<para>
Selects a different base directory for the installation of
<ProductName>PostgreSQL</ProductName>. The default is <filename>/usr/local/pgsql</filename>.
</para>
</listitem>
</varlistentry>
<Step Performance="optional">
<Para>
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>--with-template=TEMPLATE</option> option to
make the right file be chosen.
<varlistentry>
<term>--enable-locale</term>
<listitem>
<para>
If you want to use locales.
</para>
</listitem>
</varlistentry>
<note>
<title>Please Report Problems</title>
<varlistentry>
<term>--enable-multibyte</term>
<listitem>
<para>
Allows the use of multibyte character encodings. This is primarily for
languages like Japanese, Korean, or Chinese.
</para>
</listitem>
</varlistentry>
<para>
If your system is not automatically recognized by configure and you have to do this, please
send email to
<ulink url="mailto:scrappy@hub.org">scrappy@hub.org</ulink> with the output of the program
<application>./config.guess</application>. Indicate what the template file should be.
</para>
</note>
<varlistentry>
<term>--with-perl</term>
<listitem>
<para>
Builds the Perl interface. Please note that the Perl interface will be
installed into the usual place for Perl modules (typically under
<filename>/usr/lib/perl</filename>), so you must have root access to use
this option successfully.
</para>
</listitem>
</varlistentry>
</Para>
</step>
<Step Performance="optional">
<Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config">
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.
<varlistentry>
<term>--with-odbc</term>
<listitem>
<para>
Builds the ODBC driver package.
</para>
</listitem>
</varlistentry>
The configure script accepts many additional options that you can use
if you don't like the default configuration. To see them all, type
<ProgramListing>
./configure --help
</ProgramListing>
Some of the more commonly used ones are:
<ProgramListing>
--prefix=BASEDIR Selects a different base directory for the
installation of the <ProductName>Postgres</ProductName> 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
<varlistentry>
<term>--with-tcl</term>
<listitem>
<para>
Builds 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.)
</ProgramListing>
</Para>
</step>
<Step Performance="required">
<Para>
Here is the configure script used on a Sparc Solaris 2.5 system
with <filename>/opt/postgres</filename> specified as
the installation base directory:
<ProgramListing>
$ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc --with-pgport=5432 \
--enable-hba --disable-locale
</ProgramListing>
<tip>
<para>
Of course, you may type these three lines all
on the same line.
</para>
</tip>
</para>
</listitem>
</varlistentry>
</VariableList>
</Para>
</Step>
</substeps>
</step>
<Step Performance="required">
<Para>
Install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/doc
$ gmake install
</ProgramListing>
</para>
<para>
The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory.
</para>
</step>
<Step Performance="required">
<Para>
Compile the program. Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ gmake all > make.log 2>&1 &
$ tail -f make.log
$ gmake
</ProgramListing>
The compilation process can take anywhere from 10 minutes to an hour.
Your milage will most certainly vary.
</Para>
<Para>
The last line displayed will hopefully be
The last line displayed will hopefully be
<programlisting>
All of PostgreSQL is successfully made. Ready to install.
</programlisting>
Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> 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>
<para>
You will probably find a number of warning
messages in make.log. Unless you have problems later on, these
messages may be safely ignored.
</para>
</note>
</para>
<Para>
If the compiler fails with a message stating that
the <application>flex</application> command
cannot be found then install <application>flex</application> as described earlier.
Next,
change directory back to this directory, type
<programlisting>
$ gmake clean
</programlisting>
then recompile again.
</Para>
</Step>
<Step Performance="required">
<Para>
Compiler options, such as optimization and debugging, may
be specified on the command line using the COPT variable.
For example, typing
Install the program. Type
<ProgramListing>
$ gmake COPT="-g" all > make.log 2>&1 &
$ gmake install
</ProgramListing>
would invoke your compiler's <option>-g</option> option in all steps of the
build. See <filename>src/Makefile.global.in</filename> for further details.
</Para>
</Step>
<Step Performance="required">
<Para>
Install the program. Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ gmake install > make.install.log 2>&1 &
$ tail -f make.install.log
</ProgramListing>
Tell your system how to find the new shared libraries. How to do this varies between
platforms. What tends to work everywhere is to set the environment variable
<envar>LD_LIBRARY_PATH</envar>:
<programlisting>
$ LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ export LD_LIBRARY_PATH
</programlisting>
You might want to put this into a shell startup file such as
<filename>~/.bash_profile</filename>.
</Para>
<Para>
The last line displayed will be
On some systems the following is the preferred method, but you must have root
access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
<programlisting>
Thank you for choosing PostgreSQL, the most advanced open source
database engine.
<FileName>/usr/local/pgsql/lib</FileName>
</programlisting>
At this point, or earlier if you wish,
type control-C to get out of tail.
Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> on
your system.
Then run command <Command>/sbin/ldconfig</Command>.
</Para>
</Step>
<Step Performance="required">
<Para>
If necessary, tell your system how to find the new shared libraries. You can
do <emphasis>one</emphasis> of the following, preferably the first:
</para>
<SubSteps>
<Step Performance="optional">
<Para>
As root, edit file <filename>/etc/ld.so.conf</filename>. Add a line
If in doubt, refer to the manual pages of your system. If you later on get
a message like
<programlisting>
<FileName>/usr/local/pgsql/lib</FileName>
./psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
</programlisting>
to the file. Then run command <Command>/sbin/ldconfig</Command>.
then the above was necessary. Simply do this step then.
</Para>
</Step>
<Step Performance="optional">
<Step Performance="required">
<Para>
In a bash shell, type
Create the database installation. To do this you must log in to your
<ProductName>PostgreSQL</ProductName> superuser account. It will not
work as root.
<ProgramListing>
export LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ mkdir /usr/local/pgsql/data
$ chown postgres /usr/local/pgsql/data
$ su - postgres
$ /usr/local/pgsql/initdb -D /usr/local/pgsql/data
</ProgramListing>
</Para>
</Step>
<Step Performance="optional">
<Para>
In a csh shell, type
<ProgramListing>
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</ProgramListing>
</para>
The <option>-D</option> option specifies the location where the data will be
stored. You can use any path you want, it does not have to be under
the installation directory. Just make sure that the superuser account
can write to it (or create it) before starting <command>initdb</command>.
</Para>
</Step>
</SubSteps>
<Step Performance="required">
<Para>
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.
The previous step should have told you how to start up the database server.
Do so now.
<programlisting>
$ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data
</programlisting>
This will start the server in the foreground. To make it detach to
the background, use the <option>-S</option>.
</Para>
</Step>
<Para>
If, when you create the database, you get the message
<Step Performance="optional">
<para>
If you are upgrading from an existing installation, dump your data back in:
<programlisting>
pg_id: can't load library 'libpq.so'
$ /usr/local/pgsql/bin/psql < db.out
</programlisting>
then the above step was necessary. Simply
do this step, then try to create the database again.
You also might want to copy over the old <filename>pg_hba.conf</filename>
file and any other files you might have had set up for authentication, such
as password files.
</Para>
</Step>
</Procedure>
<Step Performance="optional">
<Para>
If you used the <option>--with-perl</option> 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 <command>su</command>) and doing
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src/interfaces/perl5
$ gmake install
</ProgramListing>
</Para>
</Step>
<Step Performance="required">
<Para>
If it has not already been done, then prepare account <literal>postgres</literal>
for using <ProductName>Postgres</ProductName>.
Any account that will use <ProductName>Postgres</ProductName> must
be similarly prepared.
</para>
<para>
There are several ways to influence the runtime environment of the
<ProductName>Postgres</ProductName>
server. Refer to the <citetitle>Administrator's Guide</citetitle>
for more information.
<note>
<para>
The following instructions are for a
bash/sh shell. Adapt accordingly for other shells.
</para>
</note>
</Para>
<substeps>
<Step Performance="required">
<Para>
Add the following lines to your login environment:
shell, <filename>~/.bash_profile</filename>:
<ProgramListing>
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
</ProgramListing>
</Para>
</step>
<Step Performance="required">
<para>
Several regression tests could fail if the user's locale collation
scheme is different from that of the standard <literal>C</literal> locale.
</para>
<para>
If you configure and compile <ProductName>Postgres</ProductName>
with <option>--enable-locale</option> then you should
set the locale environment to <quote><literal>C</literal></quote>
(or unset all <quote>LC_*</quote> variables)
by putting these additional lines to your login environment
before starting <application>postmaster</application>:
<ProgramListing>
LC_COLLATE=C
LC_CTYPE=C
export LC_COLLATE LC_CTYPE
</ProgramListing>
<ProgramListing>
</ProgramListing>
</para>
</step>
<Step Performance="required">
<Para>
Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type:
<ProgramListing>
$ source ~/.bash_profile
</ProgramListing>
</Para>
</Step>
</substeps>
</step>
<para>
This concludes the installation proper. To make your life more productive and enjoyable
you should look at the following optional steps and suggestions.
</para>
<Step Performance="required">
<itemizedlist>
<listitem>
<Para>
Create the database installation from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>).
<Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole. Type
<ProgramListing>
$ initdb
</ProgramListing>
Life will be more convenient if you set up some enviroment variables. First of all
you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent)
into your <envar>PATH</envar>. To do this, add the following to your shell startup
file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>,
if you want it to affect every user):
<programlisting>
PATH=$PATH:/usr/local/pgsql/bin
</programlisting>
</Para>
</Step>
<Step Performance="required">
<Para>
Set up permissions to access the database system. Do this by editing
file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>. The instructions are
included in the file. (If your database is not located in the
default location, i.e. if <envar>PGDATA</envar> 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 6.0 or later you can copy file <filename>pg_hba.conf</filename> from
your old database on top of the one in your new database, rather than
redoing the file from scratch.
Furthermore, if you set <envar>PGDATA</envar> in the environment of the PostgreSQL
superuser, you can omit the <option>-D</option> for <filename>postmaster</filename>
and <filename>initdb</filename>.
</Para>
</Step>
<Step Performance="required">
<para>
Briefly test that the backend will start and run by running it from
the command line.
</para>
<substeps>
</listitem>
<Step Performance="required">
<para>
Start the postmaster daemon running in the background by typing
<listitem>
<Para>
You probably want to install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type
<ProgramListing>
$ cd
$ nohup postmaster -i > pgserver.log 2>&1 &
$ cd /usr/src/pgsql/postgresql-7.0.0/doc
$ gmake install
</ProgramListing>
</Para>
</Step>
This will install files under <filename>/usr/local/pgsql/doc</filename>.
</para>
<Step Performance="required">
<para>
Create a database by typing
<ProgramListing>
$ createdb test
</ProgramListing>
The documentation is also available in Postscript format. If you have
a Postscript printer, or have your machine already set up to accept
Postscript files using a print filter, then to print the User's Guide
simply type
<programlisting>
$ cd /usr/local/pgsql/doc
$ gunzip -c user.ps.tz | lpr
</programlisting>
Here is how you might do it if you have Ghostscript on your system and are
writing to a laserjet printer.
<programlisting>
$ 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
</programlisting>
If in doubt, confer your manuals or your local expert.
</para>
</step>
<Step Performance="required">
<para>
Connect to the new database:
<ProgramListing>
$ psql test
</ProgramListing>
The Adminstrator's Guide should probably be your first reading if you
are completely new to <productname>PostgreSQL</productname>, as it contains
information about how to set up database users and authentication.
</para>
</step>
<Step Performance="required">
<para>
And run a sample query:
<ProgramListing>
postgres=> SELECT datetime 'now';
</ProgramListing>
</listitem>
<listitem>
<Para>
Usually, you will want to modify your computer so that it will automatically
start the database server whenever it boots.
This is not required; the <ProductName>PostgreSQL</ProductName> server can
be run successfully from non-privileged accounts without root intervention.
</para>
</step>
<Step Performance="required">
<para>
Exit <application>psql</application>:
<ProgramListing>
postgres=> \q
</ProgramListing>
Different systems have different conventions for starting up daemons at boot time,
so you are advised to familiarize yourself with them.
Most systems have a file <filename>/etc/rc.local</filename> or
<filename>/etc/rc.d/rc.local</filename> which is almost certainly no bad place
to put such a command.
Whatever you do, postmaster must be run by the <ProductName>PostgreSQL</ProductName>
superuser (<literal>postgres</literal>) <emphasis>and not by root</emphasis> or
any other user. Therefore you probably always want to form your command lines
along the lines of <literal>su -c '...' postgres</literal>.
</para>
</step>
<Step Performance="required">
<para>
Remove the test database (unless you will want to use it later for other tests):
It might be advisable to keep a log of the server output. To start the server that way
try:
<ProgramListing>
$ dropdb test
nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
</ProgramListing>
</para>
</step>
</substeps>
</step>
<Step Performance="required">
<Para>
Run postmaster in the background from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application>
from the root account!</emphasis>
</para>
<Para>
Usually, you will want to modify
your computer so that it will automatically start postmaster whenever
it boots. It is not required; the <ProductName>Postgres</ProductName>
server can
be run successfully from non-privileged accounts without root intervention.
</para>
<para>
Here are some suggestions on how to do this, contributed by various
users.
</para>
<para>
Whatever you do, postmaster must be run by
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
<emphasis>and not by root</emphasis>.
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.
<itemizedlist mark="bullet">
<listitem>
<para>
If you are installing from a non-privileged account and have no root access, then
start the <application>postmaster</application> and send it to the background:
Here are a few more operating system specific suggestions.
<ProgramListing>
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
</para>
</listitem>
<itemizedlist>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
......@@ -867,399 +524,25 @@ Then make a softlink to this file from
</para>
</listitem>
<listitem>
<para>
In RedHat Linux edit file /etc/inittab to add the
following as a single line:
<programlisting>
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
&gt;&gt; /usr/local/pgsql/server.log 2&gt;&1 &lt;/dev/null"
</programlisting>
(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.)
</para>
</listitem>
</itemizedlist>
</Para>
</Step>
<Step Performance="required">
<Para>
Run the regression tests.
The file <filename>/usr/src/pgsql/postgresql-6.5.3/src/test/regress/README</filename> has detailed
instructions for running and interpreting the regression tests.
A short version follows here:
</Para>
<substeps>
<Step Performance="required">
<Para>
Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress
$ gmake clean
$ gmake all runtest
</ProgramListing>
</Para>
<Para>
You do not need to type <command>gmake clean</command>
if this is the first time you
are running the tests.
</Para>
<Para>
You should get on the screen (and also written to file <filename>./regress.out</filename>)
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
<ProductName>Postgres</ProductName>.
The file <filename>./regression.diffs</filename> 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.
</Para>
<para>
For example,
<itemizedlist>
<listitem>
<Para>
For a i686/Linux-ELF platform, no tests failed since this is the
6.5.3 regression testing reference platform.
</Para>
</listitem>
</itemizedlist>
</para>
<Para>
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
<type>int8</type> 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.
</Para>
<Para>
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 <ProductName>Postgres</ProductName>. The regression
tests are a helpful tool, but they may require some study to be useful.
</Para>
<Para>
After running the regression tests, type
<ProgramListing>
$ dropdb regression
$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress
$ gmake clean
</ProgramListing>
to recover the disk space used for the tests. (You may want to save
the <filename>regression.diffs</filename> file in another place before doing this.)
</Para>
</Step>
</substeps>
</step>
<Step Performance="required">
<Para>
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:
</para>
<procedure>
<title>Minimal Backup Procedure</title>
<step performance="required">
<para>
Run the <acronym>SQL</acronym> command <command>VACUUM</command>.
This will clean up your database.
</para>
</step>
<step performance="required">
<para>
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.
</para>
</step>
</procedure>
<para>
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 <application>crontab</application>
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.)
</Para>
</Step>
<Step Performance="required">
<Para>
If you are upgrading an existing system then reinstall your old database.
Type
<ProgramListing>
$ cd
$ psql -e template1 < db.out
</ProgramListing>
If your pre-6.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)
<ProgramListing>
UPDATE <replaceable>FirstTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
UPDATE <replaceable>SecondTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
...
VACUUM;
</ProgramListing>
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.
</Para>
</Step>
<Step Performance="required">
<Para>
If you are a new user, you may wish to play with <ProductName>Postgres</ProductName> as described
below.
</Para>
</Step>
<Step Performance="required">
<listitem>
<Para>
Clean up after yourself. Type
<ProgramListing>
$ rm -rf /usr/src/pgsql
$ rm -rf /usr/src/pgsql.old
# Also delete the old database directory tree if desired.
$ rm -rf /usr/local/pgsql.old
</ProgramListing>
Run the regression tests. The regression tests are a test suite to verify that
PostgreSQL runs on your machine in the way the developers expected it to.
You should definitely do this before putting a server into production use.
The file <filename>/usr/src/pgsql/postgresql-7.0.0/src/test/regress/README</filename>
has detailed
instructions for running and interpreting the regression tests.
</Para>
</Step>
<Step Performance="required">
<Para>
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
<programlisting>
$ cd /usr/local/pgsql/doc
$ gunzip user.ps.tz | lpr
</programlisting>
</para>
<para>
Here is how
you might do it if you have Ghostscript on your system and are
writing to a laserjet printer.
<programlisting>
$ 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
</programlisting>
</para>
</Step>
<Step Performance="required">
<Para>
The <ProductName>Postgres</ProductName> team wants
to keep <ProductName>Postgres</ProductName> working on all of the
supported platforms. We therefore ask you to let us know if you did
or did not get <ProductName>Postgres</ProductName> to work on you system.
Please send a
mail message to
<ulink url="mailto:pgsql-ports@postgresql.org">pgsql-ports@postgresql.org</ulink>
telling us the following:
<itemizedlist>
<listitem>
<para>
The version of <ProductName>Postgres</ProductName> (6.5.3, 6.5, beta 990318, etc.).
</para>
</listitem>
<listitem>
<para>
Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
</para>
</listitem>
<listitem>
<para>
Your hardware (SPARC, i486, etc.).
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</itemizedlist>
</Para>
</Step>
<Step Performance="required">
<Para>
Now create, access and manipulate databases as desired. Write client
programs to access the database server. In other words, <emphasis>enjoy</emphasis>!
</Para>
</Step>
</Procedure>
</sect1>
<Sect1>
<Title>Playing with <ProductName>Postgres</ProductName></Title>
<Para>
After <ProductName>Postgres</ProductName> is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to
see <ProductName>Postgres</ProductName> do something. That's easy. Invoke the interactive interface
to <ProductName>Postgres</ProductName>, <Application>psql</Application>:
<ProgramListing>
% psql template1
</ProgramListing>
(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.)
</Para>
<Para>
The response from psql is:
<ProgramListing>
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=>
</ProgramListing>
</Para>
<Para>
Create the database foo:
<ProgramListing>
template1=> create database foo;
CREATE DATABASE
</ProgramListing>
(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.)
</Para>
<Para>
Now connect to the new database:
<ProgramListing>
template1=> \c foo
connecting to new database: foo
</ProgramListing>
("slash" commands aren't SQL, so no semicolon. Use \? to see all the slash commands.)
</Para>
<Para>
And create a table:
<ProgramListing>
foo=> create table bar (i int4, c char(16));
CREATE
</ProgramListing>
</Para>
<Para>
Then inspect the new table:
<ProgramListing>
foo=> \d bar
Table = bar
+----------------------------------+----------------------------------+-------+
| Field | Type | Length|
+----------------------------------+----------------------------------+-------+
| i | int4 | 4 |
| c | (bp)char | 16 |
+----------------------------------+----------------------------------+-------+
</ProgramListing>
</Para>
<Para>
And so on. You get the idea.
</Para>
</Sect1>
<Sect1>
<Title>The Next Step</Title>
<Para>
Questions? Bugs? Feedback?
First, read the files in directory <filename>/usr/src/pgsql/postgresql-6.5.3/doc/</filename>.
The FAQ in this directory may be particularly useful.
</Para>
<Para>
If <ProductName>Postgres</ProductName> failed to compile on your computer
then fill out the form in file <filename>/usr/src/pgsql/postgresql-6.5.3/doc/bug.template</filename>
and mail it to the location indicated at the top of the form.
</Para>
<Para>
Check on the web site at
<ULink url="http://www.postgresql.org">http://www.postgresql.org</ULink>
For more information on the various support mailing lists.
</Para>
</Sect1>
<Sect1>
<Title>Porting Notes</Title>
<Para>
Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
the source distribution.
</Para>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
......
doc/src/sgml/ref/initdb.sgml
View file @ 13f88750
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.8 2000/01/18 00:03:34 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.9 2000/01/20 21:50:54 petere Exp $
Postgres documentation
-->
......@@ -28,7 +28,6 @@ initdb [ --pgdata|-D <replaceable class="parameter">dbdir</replaceable> ]
[ --pwprompt|-W ]
[ --encoding|-E <replaceable class="parameter">encoding</replaceable> ]
[ --pglib|-L <replaceable class="parameter">libdir</replaceable> ]
[ --username|-u <replaceable class="parameter">name</replaceable> ]
[ --noclean | -n ] [ --debug | -d ] [ --template | -t ]
</synopsis>
......@@ -121,20 +120,6 @@ initdb [ --pgdata|-D <replaceable class="parameter">dbdir</replaceable> ]
</listitem>
</varlistentry>
<varlistentry>
<term>--username=<replaceable class="parameter">name</replaceable></term>
<term>-u <replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The database system will be initialized with the username that is
running initdb. That is a requirement. If for some unimaginable
reason initdb cannot find out what the current user's name is,
you have to use this option. Normally, this will not be necessary
and initdb will tell you when it is.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--template</term>
<term>-t</term>
......
src/GNUmakefile.in
View file @ 13f88750
......@@ -7,7 +7,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.48 2000/01/16 20:04:51 petere Exp $
# $Header: /cvsroot/pgsql/src/Attic/GNUmakefile.in,v 1.49 2000/01/20 21:50:56 petere Exp $
#
#-------------------------------------------------------------------------
......@@ -33,7 +33,7 @@ all:
echo All of PostgreSQL is successfully made. Ready to install. ;\
fi
install:
install: installdirs
$(MAKE) -C utils install
$(MAKE) -C backend install
$(MAKE) -C interfaces install
......@@ -41,6 +41,9 @@ install:
$(MAKE) -C pl install
cat ../register.txt
installdirs: mkinstalldirs
$(SRCDIR)/mkinstalldirs $(BINDIR) $(LIBDIR) $(INCLUDEDIR)
clean:
$(MAKE) -C utils clean
$(MAKE) -C backend clean
......
src/backend/access/heap/tuptoaster.c
View file @ 13f88750
......@@ -4,11 +4,11 @@
* Support routines for external and compressed storage of
* variable size attributes.
*
* Copyright (c) 2000, PostgreSQL Development Team
* Copyright (c) 2000, PostgreSQL Global Development Group
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/src/backend/access/heap/tuptoaster.c,v 1.1 1999/12/21 00:06:40 wieck Exp $
* $Header: /cvsroot/pgsql/src/backend/access/heap/tuptoaster.c,v 1.2 2000/01/20 21:50:59 petere Exp $
*
*
* INTERFACE ROUTINES
......
src/bin/Makefile
View file @ 13f88750
......@@ -7,14 +7,14 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/bin/Makefile,v 1.24 2000/01/19 20:08:23 petere Exp $
# $Header: /cvsroot/pgsql/src/bin/Makefile,v 1.25 2000/01/20 21:51:02 petere Exp $
#
#-------------------------------------------------------------------------
SRCDIR= ..
include ../Makefile.global
DIRS = pg_version psql pg_dump pg_passwd \
DIRS = pg_id pg_version psql pg_dump pg_passwd \
scripts initdb initlocation ipcclean \
pg_ctl
......
src/bin/initdb/initdb.sh
View file @ 13f88750
......@@ -26,7 +26,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.81 2000/01/19 20:08:24 petere Exp $
# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.82 2000/01/20 21:51:05 petere Exp $
#
#-------------------------------------------------------------------------
......@@ -47,14 +47,7 @@ exit_nicely(){
CMDNAME=`basename $0`
if [ "$USER" = 'root' -o "$LOGNAME" = 'root' ]
then
echo "You cannot run $CMDNAME as root. Please log in (using, e.g., 'su')"
echo "as the (unprivileged) user that will own the server process."
exit 1
fi
EffectiveUser=`id -n -u 2>/dev/null || whoami 2>/dev/null`
if [ "$TMPDIR" ]; then
TEMPFILE="$TMPDIR/initdb.$$"
else
......@@ -95,7 +88,7 @@ else
fi
# Check if needed programs actually exist in path
for prog in postgres pg_version
for prog in postgres pg_version pg_id
do
if [ ! -x "$PGPATH/$prog" ]
then
......@@ -109,6 +102,22 @@ do
fi
done
# Gotta wait for pg_id existence check above
EffectiveUser=`$PGPATH/pg_id -n -u`
if [ -z "$EffectiveUser" ]; then
echo "Could not determine current user name. You are really hosed."
exit 1
fi
if [ `$PGPATH/pg_id -u` -eq 0 ]
then
echo "You cannot run $CMDNAME as root. Please log in (using, e.g., 'su')"
echo "as the (unprivileged) user that will own the server process."
exit 1
fi
# 0 is the default (non-)encoding
MULTIBYTEID=0
# This is placed here by configure --enable-multibyte[=XXX].
......@@ -124,12 +133,9 @@ template_only=0
# superuser be the same as the Unix user owning the server process:
# The single user postgres backend will only connect as the database
# user with the same name as the Unix user running it. That's
# a security measure. It might change in the future (why?), but for
# now the --username option is only a fallback if both id and whoami
# fail, and in that case the argument _must_ be the name of the effective
# user.
# a security measure.
POSTGRES_SUPERUSERNAME="$EffectiveUser"
POSTGRES_SUPERUSERID="`id -u 2>/dev/null || echo 0`"
POSTGRES_SUPERUSERID=`$PGPATH/pg_id -u`
while [ "$#" -gt 0 ]
do
......@@ -150,17 +156,7 @@ do
template_only=1
echo "Updating template1 database only."
;;
# The database superuser. See comments above.
--username|-u)
POSTGRES_SUPERUSERNAME="$2"
shift;;
--username=*)
POSTGRES_SUPERUSERNAME=`echo $1 | sed 's/^--username=//'`
;;
-u*)
POSTGRES_SUPERUSERNAME=`echo $1 | sed 's/^-u//'`
;;
# The sysid of the database superuser. See comments above.
# The sysid of the database superuser. Can be freely changed.
--sysid|-i)
POSTGRES_SUPERUSERID="$2"
shift;;
......@@ -284,21 +280,6 @@ then
exit 1
fi
#---------------------------------------------------------------------------
# Figure out who the Postgres superuser for the new database system will be.
#---------------------------------------------------------------------------
# This means they have neither 'id' nor 'whoami'!
if [ -z "$POSTGRES_SUPERUSERNAME" ]
then
echo "$CMDNAME: Could not the determine current username. Please use the -u option."
exit 1
fi
echo "This database system will be initialized with username \"$POSTGRES_SUPERUSERNAME\"."
echo "This user will own all the data files and must also own the server process."
echo
#-------------------------------------------------------------------------
# Find the input files
......@@ -355,6 +336,10 @@ fi
trap 'echo "Caught signal." ; exit_nicely' 1 2 3 15
# Let's go
echo "This database system will be initialized with username \"$POSTGRES_SUPERUSERNAME\"."
echo "This user will own all the data files and must also own the server process."
echo
# -----------------------------------------------------------------------
# Create the data directory if necessary
......
src/bin/pg_id/Makefile 0 → 100644
View file @ 13f88750
#-------------------------------------------------------------------------
#
# Makefile
# Makefile for bin/pg_id
#
# Copyright (C) 2000 by PostgreSQL Global Development Team
#
# $Header: /cvsroot/pgsql/src/bin/pg_id/Attic/Makefile,v 1.14 2000/01/20 21:51:07 petere Exp $
#
#-------------------------------------------------------------------------
SRCDIR= ../..
include ../../Makefile.global
OBJS= pg_id.o
all: pg_id
pg_id: $(OBJS)
$(CC) -o pg_id $(OBJS) $(LDFLAGS)
install: pg_id
$(INSTALL) $(INSTL_EXE_OPTS) pg_id$(X) $(BINDIR)/pg_id
depend dep:
$(CC) -MM $(CFLAGS) *.c >depend
clean:
rm -f pg_id $(OBJS)
ifeq (depend,$(wildcard depend))
include depend
endif
src/bin/pg_id/pg_id.c 0 → 100644
View file @ 13f88750
/*
* pg_id.c
*
* A crippled id utility for use in various shell scripts in use by PostgreSQL
* (in particular initdb)
*
* Copyright (C) 2000 by PostgreSQL Global Development Group
*
* $Header: /cvsroot/pgsql/src/bin/pg_id/Attic/pg_id.c,v 1.11 2000/01/20 21:51:07 petere Exp $
*/
#include <c.h>
#include <pwd.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
int main(int argc, char * argv[])
{
int c;
int nameflag = 0,
realflag = 0,
userflag = 0;
const char * username = NULL;
struct passwd * pw;
while ((c = getopt(argc, argv, "nru")) != -1)
{
switch(c)
{
case 'n':
nameflag = 1;
break;
case 'r':
realflag = 1;
break;
case 'u':
userflag = 1;
break;
default:
fprintf(stderr, "Usage: %s [-n] [-r] [-u] [username]\n", argv[0]);
exit(1);
}
}
if (argc - optind >= 1)
username = argv[optind];
if (nameflag && !userflag)
{
fprintf(stderr, "%s: -n must be used together with -u\n", argv[0]);
exit(1);
}
if (username && realflag)
{
fprintf(stderr, "%s: -r cannot be used when a user name is given\n", argv[0]);
exit(1);
}
if (username)
{
pw = getpwnam(username);
if (!pw)
{
fprintf(stderr, "%s: %s: no such user\n", argv[0], username);
exit(1);
}
}
else if (realflag)
pw = getpwuid(getuid());
else
pw = getpwuid(geteuid());
if (!pw)
{
perror(argv[0]);
exit(1);
}
if (!userflag)
printf("uid=%d(%s)\n", (int)pw->pw_uid, pw->pw_name);
else if (nameflag)
puts(pw->pw_name);
else
printf("%d\n", (int)pw->pw_uid);
return 0;
}
src/bin/psql/copy.c
View file @ 13f88750
......@@ -3,7 +3,7 @@
*
* Copyright 2000 by PostgreSQL Global Development Team
*
* $Header: /cvsroot/pgsql/src/bin/psql/copy.c,v 1.6 2000/01/18 23:30:23 petere Exp $
* $Header: /cvsroot/pgsql/src/bin/psql/copy.c,v 1.7 2000/01/20 21:51:09 petere Exp $
*/
#include <c.h>
#include "copy.h"
......@@ -423,7 +423,10 @@ handleCopyIn(PGconn *conn, FILE *copystream, const char *prompt)
if (firstload)
{
if (!strcmp(copybuf, "\\."))
{
copydone = true;
break;
}
firstload = false;
}
}
......
src/mkinstalldirs 0 → 100755
View file @ 13f88750
#! /bin/sh
# mkinstalldirs --- make directory hierarchy
# Author: Noah Friedman <friedman@prep.ai.mit.edu>
# Created: 1993-05-16
# Last modified: 1994-03-25
# Public domain
errstatus=0
for file in ${1+"$@"} ; do
set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'`
shift
pathcomp=
for d in ${1+"$@"} ; do
pathcomp="$pathcomp$d"
case "$pathcomp" in
-* ) pathcomp=./$pathcomp ;;
esac
if test ! -d "$pathcomp"; then
echo "mkdir $pathcomp" 1>&2
mkdir "$pathcomp" > /dev/null 2>&1 || lasterr=$?
fi
if test ! -d "$pathcomp"; then
errstatus=$lasterr
fi
pathcomp="$pathcomp/"
done
done
exit $errstatus
# mkinstalldirs ends here
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment