e56f1d60a5
Subject: [PATCHES] Patch for INSTALL The following patch makes a number of modifications to file INSTALL. Among other things, it restores some platform specific notes I deleted. It also no longer requires a separate compile for the regression tests. Please note that this patch already incorporates the patch Hal Snyder submitted on Monday. Do not apply Hal's patch.
554 lines
22 KiB
Plaintext
554 lines
22 KiB
Plaintext
POSTGRESQL INSTALLATION INSTRUCTIONS
|
|
Copyright (c) 1997 Regents of the University of California
|
|
|
|
This is file /usr/src/pgsql/INSTALL. It contains notes on how to install
|
|
PostgreSQL v6.1. Up to date information on PostgreSQL may be found at
|
|
http://www.postgresql.org.
|
|
|
|
PostgreSQL is a database server. It is not completely ANSI SQL
|
|
compliant, but with each release it gets closer.
|
|
|
|
PostgreSQL, formerly called Postgres95, is a derivative of Postgres 4.2
|
|
(the last release of the UC Berkeley research project). For copyright
|
|
terms for PostgreSQL, please see the file named COPYRIGHT. This version
|
|
was developed by a team of developers on the postgres developers mailing
|
|
list. Version 1 (through 1.01) was developed by Jolly Chen and Andrew
|
|
Yu.
|
|
|
|
The installation notes below assume the following (except where noted):
|
|
- Commands were tested on RedHat Linux version 4.0 using the bash
|
|
shell. Except where noted, they will probably work on most
|
|
systems. USE COMMON SENSE before typing in these commands.
|
|
Commands like ps and tar vary wildly on what options you should
|
|
use on each platform.
|
|
- Defaults are assumed.
|
|
- User postgres is the postgres superuser.
|
|
|
|
Our Makefiles require GNU make (called gmake in this document) and
|
|
also assume that "install" accepts BSD options. The INSTALL
|
|
variable in the Makefiles is set to the BSD-compatible version of
|
|
install. On some systems, you will have to find a BSD-compatible
|
|
install command (eg. bsdinst, which comes with the MIT X Window System
|
|
distribution)
|
|
|
|
|
|
REQUIREMENTS TO RUN POSTGRESQL
|
|
------------------------------
|
|
|
|
PostgreSQL has been tested on the following platforms:
|
|
|
|
aix IBM on AIX 3.2.5
|
|
alpha DEC Alpha AXP on OSF/1 2.0
|
|
BSD44_derived OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
|
|
bsdi BSD/OS 2.0, 2.01, 2.1
|
|
dgux DG/UX 5.4R3.10
|
|
hpux HP PA-RISC on HP-UX 9.0
|
|
i386_solaris i386 Solaris
|
|
irix5 SGI MIPS on IRIX 5.3
|
|
linux Intel x86 on Linux 1.2 and Linux ELF
|
|
(For non-ELF Linux, see LINUX_ELF below).
|
|
sparc_solaris SUN SPARC on Solaris 2.4
|
|
sunos4 SUN SPARC on SunOS 4.1.3
|
|
svr4 Intel x86 on Intel SVR4
|
|
ultrix4 DEC MIPS on Ultrix 4.4
|
|
|
|
PostgreSQL has known problems/bugs on the following platforms:
|
|
|
|
nextstep Motorola MC68K or Intel x86 on NeXTSTEP 3.2
|
|
|
|
PostgreSQL is also known to work on a number of other platforms that the
|
|
authors have not personally tested.
|
|
|
|
You should have at least 8 MB of memory and at least 30 MB of disk space to
|
|
hold the source, binaries, and user databases.
|
|
|
|
|
|
To upgrade to PostgreSQL v6.1 do the following:
|
|
----------------------------------------------
|
|
|
|
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.
|
|
|
|
2) Create account postgres if it does not already exist.
|
|
|
|
3) Log into account postgres.
|
|
|
|
4) Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.1.tar.gz from the
|
|
internet.
|
|
|
|
5) Some platforms use flex. If your system uses flex then make sure
|
|
you have a good version. 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.
|
|
|
|
To install it, type the following:
|
|
cd
|
|
gunzip -c flex-2.5.4.tar.gz | tar xvf -
|
|
cd flex-2.5.4
|
|
configure --prefix=/usr
|
|
make
|
|
make check
|
|
# You must be root when typing the next line.
|
|
make install
|
|
cd
|
|
rm -rf flex-2.5.4
|
|
|
|
This will update files /usr/man/man1/flex.1, /usr/bin/flex,
|
|
/usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
|
|
/usr/bin/flex++ which points to flex.
|
|
|
|
If you have flex v2.5.3 and do not have handy access to the
|
|
internet, you can apply the patch in /usr/src/pgsql/doc/README.flex
|
|
instead.
|
|
|
|
6) If you are upgrading an existing system from any version before
|
|
version 6.1 beta release 970512 then back up the current
|
|
database. Type
|
|
cd
|
|
pg_dumpall > db.out
|
|
If you wish to preserve object id's (oids), type
|
|
cd
|
|
pg_dumpall -o > db.out
|
|
instead. However, unless you have a special reason for doing this,
|
|
don't do it.
|
|
|
|
Please note that if you are upgrading from a version prior to
|
|
Postgres95 v1.09 then you must back up your database, install
|
|
Postgres95 v1.09, restore your database, then back it up again.
|
|
You should also read files /usr/src/pgsql/migration/*.
|
|
|
|
You must make sure that your database is not updated in the middle of
|
|
your backup. If necessary, bring down postmaster, edit the permissions
|
|
in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then
|
|
bring postmaster back up.
|
|
|
|
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 "???" replaced by the process id for process
|
|
"postmaster". (Do not use the id for process "grep postmaster".) Type
|
|
kill ???
|
|
with "???" modified as indicated.
|
|
|
|
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. Type
|
|
su
|
|
cd /usr/src
|
|
mkdir pgsql
|
|
chown postgres pgsql
|
|
chgrp postgres pgsql
|
|
cd /usr/local
|
|
mkdir pgsql
|
|
chown postgres pgsql
|
|
chgrp postgres pgsql
|
|
exit
|
|
|
|
10) Unzip and untar the new source file. Type
|
|
cd /usr/src/pgsql
|
|
gunzip -c ~/postgresql-v6.1.tar.gz | tar xvf -
|
|
|
|
11) Configure the source code for your system. Type
|
|
cd /usr/src/pgsql/src
|
|
./configure
|
|
|
|
The configure program will list the template files available and
|
|
ask you to choose one. A lot of times, an appropriate template
|
|
file is chosen for you, and you can just press Enter to accept the
|
|
default. If the default is not appropriate, then type in the
|
|
appropriate template file and press Enter. (If you do this, then
|
|
send email to scrappy@hub.org stating the output of the program
|
|
'./config.guess' and what the template file should be.)
|
|
|
|
Once you have entered the template file, you will be asked a
|
|
number of questions about your particular configuration. These
|
|
can be skipped by adding parameters to the configure command above.
|
|
The following parameters can be tagged onto the end of the configure
|
|
command:
|
|
|
|
--prefix=BASEDIR Selects a different base directory for the
|
|
installation of the PostgreSQL configuration.
|
|
The default is /usr/local/pgsql.
|
|
|
|
--enable-hba Enables Host Based Authentication
|
|
|
|
--disable-hba Disables Host Based Authentication
|
|
|
|
--enable-locale Enables USE_LOCALE
|
|
|
|
--disable-locale Disables USE_LOCALE
|
|
|
|
--enable-cassert Enables ASSERT_CHECKING
|
|
|
|
--disable-cassert Disables ASSERT_CHECKING
|
|
|
|
The default for ASSERT_CHECKING is normally
|
|
enabled for development versions and
|
|
disabled for release versions of PostgreSQL.
|
|
|
|
--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.
|
|
(If the configure script cannot find the
|
|
specified template file, it will ask you for
|
|
one).
|
|
|
|
--with-pgport=PORT Sets the port that the postmaster process
|
|
listens for incoming connections on. The
|
|
default for this is port 5432.
|
|
|
|
As an example, here is the configure script I use on a Sparc
|
|
Solaris 2.5 system with /opt/postgres being the install base.
|
|
|
|
% ./configure --prefix=/opt/postgres
|
|
--with-template=sparc_solaris-gcc --with-pgport=5432
|
|
--enable-hba --disable-locale
|
|
|
|
Of course, in a real shell, you would type these three lines all
|
|
on the same line.
|
|
|
|
12) Compile the program. Type
|
|
cd /usr/src/pgsql/src
|
|
gmake all &> make.log &
|
|
tail -f make.log
|
|
The last line displayed will hopefully be "All of PostgreSQL is
|
|
successfully made. Ready to install." At this point, or earlier
|
|
if you wish, type control-C to get out of tail. (If you have
|
|
problems later on you may wish to examine file make.log for
|
|
warning and error messages.)
|
|
|
|
If your computer does not have gmake (GNU make) then try running
|
|
make instead throughout the rest of these notes.
|
|
|
|
Please note that you will probably find a number of warning
|
|
messages in make.log. Unless you have problems later on, these
|
|
messages may be safely ignored.
|
|
|
|
If the compiler fails with an error stating that the flex command
|
|
cannot be found then install flex as described earlier. Next,
|
|
change directory back to this directory, type "make clean", then
|
|
recompile again.
|
|
|
|
13) Install the program. Type
|
|
cd /usr/src/pgsql/src
|
|
gmake install &> make.install.log &
|
|
tail -f make.install.log
|
|
The last line displayed will be "gmake[1]: Leaving directory
|
|
`/usr/src/pgsql/src/man'". At this point, or earlier if you wish,
|
|
type control-C to get out of tail.
|
|
|
|
14) If necessary, tell UNIX how to find your shared libraries. If you
|
|
are using Linux-ELF do ONE of the following, preferably the first:
|
|
|
|
a) As root, edit file /etc/ld.so.conf. Add 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.
|
|
|
|
15) If it has not already been done, then prepare account postgres
|
|
for using PostgreSQL. Any account that will use PostgreSQL must
|
|
be similarily prepared. (The following instructions are for a
|
|
bash shell. Adapt accordingly for other shells.)
|
|
|
|
Add the following lines to your login shell, ~/.bash_profile:
|
|
PATH=$PATH:/usr/local/pgsql/bin
|
|
MANPATH=/usr/local/pgsql/man
|
|
PGLIB=/usr/local/pgsql/lib
|
|
PGDATA=/usr/local/pgsql/data
|
|
export PATH MANPATH PGLIB PGDATA
|
|
|
|
Make sure that you have defined these variables before continuing
|
|
with the remaining steps. The easiest way to do this is to type:
|
|
source ~/.bash_profile
|
|
|
|
16) Create the database. DO NOT DO THE FOLLOWING AS ROOT! This would
|
|
be a major security hole. Type
|
|
initdb
|
|
|
|
17) 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 finsihed.
|
|
|
|
If you are upgrading from v6.0 you can copy file pg_hba.conf from
|
|
your old database on top of the one in your new database, rather than
|
|
redoing this from scratch.
|
|
|
|
18) Start the postmaster in preparation for the regression tests. First,
|
|
set the timezone for Berkley, California. On some systems you may do
|
|
this by setting environment variable TZ. I.e., using bash, type
|
|
export TZ=PST8PDT7,M04.01.0,M10.0503
|
|
Now start the postmaster daemon running in the background by typing
|
|
cd
|
|
nohup postmaster > regress.log 2>&1 &
|
|
Run postmaster from your postgres super user account (typically
|
|
account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
|
|
|
|
19) Run the regression tests. 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 is normal for some of the tests to
|
|
"fail". For the failed tests, use diff to compare the files in
|
|
directories ./results and ./expected. "Failed" tests may have
|
|
failed due to slightly different error messages, output formatting,
|
|
failure to set the timezone correctly for your platform, etc.
|
|
"Failures" of this type do not indicate a problem with PostgreSQL.
|
|
|
|
After running the tests, type
|
|
cd /usr/src/pgsql/src/test/regress
|
|
gmake clean
|
|
|
|
20) Stop the postmaster as described in step 7. Then restore the
|
|
timezone to it's normal setting. If you changed the timezone by
|
|
modifying environment variable TZ then one way to do this is to
|
|
log out of, then back into, account postgres.
|
|
|
|
21) Start the postmaster daemon running. Type
|
|
cd
|
|
nohup postmaster > server.log 2>&1 &
|
|
Run postmaster from your postgres super user account (typically
|
|
account postgres). DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
|
|
|
|
22) If you haven't already done so, this would be a good time to modify
|
|
your computer so that it will automatically start postmaster whenever
|
|
you boot your computer.
|
|
|
|
Here are some suggestions on how to do this, contributed by various
|
|
users.
|
|
|
|
Whatever you do, postmaster must be run by user postgres, AND NOT BY
|
|
ROOT. This is why all of the examples below start by switching user
|
|
(su) to postgres. These commands also take into account the fact
|
|
that environment variables like PATH and PGDATA may not be set properly.
|
|
|
|
The examples are as follows. Use them with extreme caution.
|
|
|
|
a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
|
|
2.5.1 to contain the following single line:
|
|
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
|
|
/usr/local/pgsql/data"
|
|
|
|
b) In RedHat v4.0 Linux edit file /etc/inittab to contain the
|
|
following single line:
|
|
pg:2345:respawn:/bin/su - postgres -c
|
|
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
|
|
>> /usr/local/pgsql/server.log 2>&1" /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.)
|
|
|
|
c) In FreeBSD edit /usr/local/etc/rc.d/pgsql.sh to contain the
|
|
following two lines, and make it 755 root:bin :
|
|
#!/bin/sh
|
|
[ -x /usr/local/pgsql/bin/postmaster ] &&
|
|
su -l pgsql -c '/usr/local/pgsql/bin/postmaster
|
|
-D/usr/local/pgsql/data -o -F > /usr/local/pgsql/errlog
|
|
&' && echo -n ' pgsql'
|
|
|
|
d) In RedHat v4.0 Linux create file /etc/rc.d/init.d/postgres.init to
|
|
contain the following single line:
|
|
su -c "cd ~postgres; nohup /usr/local/pgsql/bin/postmaster
|
|
-D /usr/local/pgsql/data > server.log 2>&1 &" postgres
|
|
Next, type the following:
|
|
cd /etc/rc3.d
|
|
ln -s ../init.d/postgres.init S1000postgres
|
|
Change "1000" to a number of your choice to indicate the
|
|
loading order of the various programs pointed to in directory
|
|
/etc/rc3.d. (Note that this example has not been tested yet.)
|
|
|
|
You might also want to modify your computer so that cron will run
|
|
the vacuum command nightly and do regular backups. Look at the
|
|
man page for crontab for a starting point on how to do this.
|
|
|
|
23) If you are upgrading an existing system then install your old database.
|
|
Type
|
|
cd
|
|
psql -e template1 < db.out
|
|
|
|
24) If you are a new user, you may wish to play with postgres as described
|
|
below.
|
|
|
|
25) Clean up after yourself. Type
|
|
rm -rf /usr/src/pgsql_6_0
|
|
rm -rf /usr/local/pgsql_6_0
|
|
# Also delete old database directory tree if it is not in
|
|
# /usr/local/pgsql_6_0/data
|
|
rm ~/postgresql-v6.1.tar.gz
|
|
|
|
26) You will probably want to print out the documentation. Here is how
|
|
you might do it if you have Ghostscript on your system and are
|
|
writing to a laserjet printer.
|
|
alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
|
|
export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
|
|
# Print out the man pages.
|
|
man -a -t /usr/local/pgsql/man/*/* > manpage.ps
|
|
gshp -sOUTPUTFILE=manpage.hp manpage.ps
|
|
rm manpage.ps
|
|
lpr -l -s -r manpage.hp
|
|
# Print out the Postgres95 User Manual, version 1.0,
|
|
# Sept. 5, 1996.
|
|
cd /usr/src/pgsql/doc
|
|
gshp -sOUTPUTFILE=userguide.hp userguide.ps
|
|
lpr -l -s -r userguide.hp
|
|
|
|
If you are a developer, you will probably want to also print out
|
|
the Postgres Implemention Guide, version 1.0, October 1, 1995.
|
|
This is a WWW document located at
|
|
http://www.postgresql.org/docs/impguide.
|
|
|
|
27) Now create, access and manipulate databases as desired. Write client
|
|
programs to access the database server. In other words, ENJOY!
|
|
|
|
|
|
PLAYING WITH POSTGRESQL
|
|
-----------------------
|
|
|
|
After PostgreSQL is installed, a database system is created, a postmaster
|
|
daemon is running, and the regression tests have passed, you'll want to
|
|
see PostgreSQL do something. That's easy. Invoke the interactive interface
|
|
to PostgreSQL, psql, and start typing SQL:
|
|
|
|
$ 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:
|
|
|
|
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;
|
|
INSERT 773248
|
|
|
|
(Don't ever forget those SQL semicolons. Psql won't execute anything until it
|
|
sees the semicolon.)
|
|
|
|
template1=> \c foo
|
|
closing connection to database: template1
|
|
connecting to new database: foo
|
|
|
|
(\ commands aren't SQL, so no semicolon. Use \? to see all the \ commands.)
|
|
|
|
template1=> CREATE TABLE bar (column1 int4, column2 char16);
|
|
CREATE
|
|
|
|
template1=> \d bar
|
|
|
|
...
|
|
|
|
You get the idea.
|
|
|
|
|
|
QUESTIONS? BUGS? FEEDBACK?
|
|
----------------------------
|
|
|
|
First, read the files in directory /usr/src/pgsql/doc. The FAQ in
|
|
this directory may be particularly useful.
|
|
|
|
If PostgreSQL failed to compile on your computer then fill out the form
|
|
in file /usr/src/pgsql/doc/bug.template and mail it to the location
|
|
indicated at the top of the form.
|
|
|
|
Mail questions to pgsql-questions@postgresql.org. For more information
|
|
on the various mailing lists, see http://www.postgresql.org under mailing
|
|
lists.
|
|
|
|
|
|
----------------------------------------------------------------------
|
|
|
|
Porting Notes (these notes may be out of date):
|
|
-------------
|
|
|
|
Ultrix4.x:
|
|
You need to install the libdl-1.1 package since Ultrix 4.x doesn't
|
|
have a dynamic loader. It's available in
|
|
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
|
|
|
|
Linux:
|
|
The linux port defaults to the ELF binary format. (Note that if you're
|
|
using ELF, you don't need dld because you'll be using the dl library
|
|
that comes with Linux ELF instead.)
|
|
|
|
To compile on non-ELF Linux, comment out the LINUX_ELF line in
|
|
src/mk/port/postgres.mk.linux. Also, the dld library MUST be obtained
|
|
and installed on the system. It enables dynamic link loading capability
|
|
to the postgres port. The dld library can be obtained from the sunsite
|
|
linux distributions. The current name is dld-3.2.5.
|
|
(Jalon Q. Zimmerman
|
|
<sneaker@powergrid.electriciti.com> 5/11/95)
|
|
|
|
To compile with flex, you need a recent version (2.5.2 or
|
|
later). Otherwise, you will get a 'yy_flush_buffer' undefined error.
|
|
Note, however, that flex v2.5.3 has a bug. See the FAQs.
|
|
|
|
BSD/OS:
|
|
For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2
|
|
as well as the GNU dld library. Flex version 2.5.3 has a known bug.
|
|
|
|
NeXT:
|
|
The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
|
|
It requires a SysV IPC emulation library and header files for
|
|
shared libary and semaphore stuff. Tom just happens to sell such
|
|
a product so contact him for information. He has also indicated that
|
|
binary releases of PostgreSQL for NEXTSTEP will be made available to
|
|
the general public. Contact Info@RnA.nl for information.
|
|
|