Skip to content

P
Postgres FD Implementation
Commit ae7e19c5 authored by Thomas G. Lockhart's avatar Thomas G. Lockhart
Browse files
Options

Try to go through and get the markup right. 

Make more changes to freshen up to v6.4 conventions.
Drop mention of Postgres95 docs.
parent d79f3884
Show whitespace changes
Inline Side-by-side
Showing with 373 additions and 221 deletions
doc/src/sgml/install.sgml
View file @ ae7e19c5
...@@ -34,12 +34,12 @@ User postgres is the <ProductName>Postgres</ProductName> superuser. ...@@ -34,12 +34,12 @@ User postgres is the <ProductName>Postgres</ProductName> superuser.
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
The source path is /usr/src/pgsql (other paths are possible). The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para> </Para>
</ListItem> </ListItem>
<ListItem> <ListItem>
<Para> <Para>
The runtime path is /usr/local/pgsql (other paths are possible). The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para> </Para>
</ListItem> </ListItem>
</ItemizedList> </ItemizedList>
...@@ -47,8 +47,9 @@ The runtime path is /usr/local/pgsql (other paths are possible). ...@@ -47,8 +47,9 @@ The runtime path is /usr/local/pgsql (other paths are possible).
<Para> <Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell. Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands Except where noted, they will probably work on most systems. Commands
like ps and tar vary wildly on what options you should use on each like <command>ps</command> and <command>tar</command> may vary wildly
platform. <Emphasis>Use common sense</Emphasis> before typing in these commands. between platforms on what options you should use.
<Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para> </Para>
<Para> <Para>
...@@ -56,15 +57,21 @@ Our Makefiles require GNU <Application>make</Application> (called ...@@ -56,15 +57,21 @@ Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis> <Quote>gmake</Quote> in this document). They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs. If you work with non-GNU <Application>make</Application> programs. If you
have GNU <Application>make</Application> installed under the name have GNU <Application>make</Application> installed under the name
<Quote>make</Quote> instead of <Quote>gmake</Quote>, that's OK, but <Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
you need to have it. 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.
</Para> </Para>
<Sect1> <Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title> <Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
<Para> <Para>
Information on supported platforms is in another chapter. In general, most Unix-compatible 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>.
In general, most Unix-compatible
platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>. platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
<Para> <Para>
...@@ -114,20 +121,22 @@ Read any last minute information and platform specific porting ...@@ -114,20 +121,22 @@ Read any last minute information and platform specific porting
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
Create account postgres if it does not already exist. Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist.
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Log into account postgres. Log in to the <ProductName>Postgres</ProductName> superuser account.
</Para> </Para>
<SubSteps> <SubSteps>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Check that you have sufficient disk space. You will need about Check that you have sufficient disk space. You will need about
17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql 17 Mbytes for <filename>/usr/src/pgsql</filename>,
about 2 Mbytes for <filename>/usr/local/pgsql</filename>
(excluding your database) and 1 Mbyte for an empty database. (excluding your database) and 1 Mbyte for an empty database.
The database will temporarily grow to about 20 Mbytes during the The database will temporarily grow to about 20 Mbytes during the
regression tests. You will also need about 3 Mbytes for the regression tests. You will also need about 3 Mbytes for the
...@@ -136,69 +145,91 @@ Check that you have sufficient disk space. You will need about ...@@ -136,69 +145,91 @@ Check that you have sufficient disk space. You will need about
<Para> <Para>
We therefore recommend that during installation and testing you We therefore recommend that during installation and testing you
have well over 20 Mbytes free under /usr/local and another 25 Mbytes 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 free on the disk partition containing your database. Once you
delete the source files, tar file and regression database, you delete the source files, tar file and regression database, you
will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty 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 database, plus about five times the space you would require to
store your database data in a flat file. store your database data in a flat file.
</Para> </Para>
<Para> <Para>
To check for disk space, use <Command>df -k</Command>. To check for disk space, use
<programlisting>
$ df -k
</programlisting>
</Para> </Para>
</Step> </Step>
</SubSteps> </SubSteps>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the Ftp file
Internet. Store it in your home directory. <ulink url="ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz"><filename>ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz</filename></ulink>
from the Internet. Store it in your home directory.
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Some platforms use flex. If your system uses flex then make sure Some platforms use <application>flex</application>.
you have a good version. To check, type <Command>flex --version</Command>. If your system uses <application>flex</application> then make sure
you have a good version. To check, type
<programlisting>
$ flex --version
</programlisting>
</Para> </Para>
<Para> <Para>
If the flex command is not found then you probably do not need it. If the <application>flex</application> 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 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 is 2.5.3 or before 2.5.2 then you will have to upgrade <application>flex</application>. You may
get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz. get it at
<ulink url="ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz">ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz</ulink>.
</Para> </Para>
<Para> <Para>
If you need flex and don't have it or have the wrong version, then If you need <application>flex</application> and don't have it or have the wrong version, then
you will be told so when you attempt to compile the program. Feel 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 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 need it then you will be told to install/upgrade <application>flex</application> when you try to
compile. compile <productname>Postgres</productname>.
</Para> </Para>
<Para> <Para>
To install it, type the following: You may want to do the entire <application>flex</application> 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:
<ProgramListing> <ProgramListing>
cd $ su -
gunzip -c flex-2.5.4.tar.gz | tar xvf - $ cd /usr/local/src
cd flex-2.5.4 ftp prep.ai.mit.edu
configure --prefix=/usr ftp> cd /pub/gnu/
make ftp> binary
make check ftp> get flex-2.5.4.tar.gz
# You must be root when typing the next line. ftp> quit
make install $ gunzip -c flex-2.5.4.tar.gz | tar xvf -
cd $ cd flex-2.5.4
rm -rf 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
</ProgramListing> </ProgramListing>
</Para> </Para>
<Para> <Para>
This will update files /usr/man/man1/flex.1, /usr/bin/flex, This will update files <filename>/usr/man/man1/flex.1</filename>,
/usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link <filename>/usr/bin/flex</filename>,
/usr/bin/flex++ which points to flex. <filename>/usr/lib/libfl.a</filename>,
<filename>/usr/include/FlexLexer.h</filename> and will add a link
<filename>/usr/bin/flex++</filename> which points to flex.
</Para> </Para>
</Step> </Step>
...@@ -206,32 +237,44 @@ Some platforms use flex. If your system uses flex then make sure ...@@ -206,32 +237,44 @@ Some platforms use flex. If your system uses flex then make sure
<Para> <Para>
If you are upgrading an existing system then back up your database. If you are upgrading an existing system then back up your database.
For alpha- and beta-level releases, the database format is liable For alpha- and beta-level releases, the database format is liable
to change often every few weeks with no notice besides a quick comment 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 in the HACKERS mailing list. Full releases always require a dump/reload
from previous releases. It is therefore a bad idea to skip this from previous releases. It is therefore a bad idea to skip this
step. Also, do not use the pg_dumpall script from v6.0 or everything step.
<tip>
<para>
Do not use the <application>pg_dumpall</application>
script from v6.0 or everything
will be owned by the <ProductName>Postgres</ProductName> super user. will be owned by the <ProductName>Postgres</ProductName> super user.
Type (with the gunzip line </tip>
and the following line typed as one line):
<para>
To use the latest <application>pg_dumpall</application> script on your
existing database before upgrading <productname>Postgres</productname>, type:
<ProgramListing> <ProgramListing>
cd $ cd
gunzip -c postgresql-v6.4.tar.gz | $ gunzip -c postgresql-v6.4.tar.gz \
tar xvf - src/bin/pg_dump/pg_dumpall | tar xvf - src/bin/pg_dump/pg_dumpall
chmod a+x src/bin/pg_dump/pg_dumpall $ chmod a+x src/bin/pg_dump/pg_dumpall
src/bin/pg_dump/pg_dumpall > db.out $ src/bin/pg_dump/pg_dumpall > db.out
rm -rf src $ rm -rf src
</ProgramListing> </ProgramListing>
</Para> </Para>
<Para> <Para>
If you wish to preserve object id's (oids), then use the -o If you wish to preserve object id's (oids), then use the -o
option when running pg_dumpall. However, unless you have a option when running <application>pg_dumpall</application>. However, unless you have a
special reason for doing this, don't do it. special reason for doing this (such as using OIDs as keys
in tables), don't do it.
</Para> </Para>
<Para> <Para>
If the pg_dumpall command seems to take a long time and you think If the <application>pg_dumpall</application> command seems to take a long time and you think
it might have died, then, from another terminal, use "ls -l db.out" 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. several times to see if the size of the file is growing.
</Para> </Para>
...@@ -239,28 +282,47 @@ If you are upgrading an existing system then back up your database. ...@@ -239,28 +282,47 @@ If you are upgrading an existing system then back up your database.
Please note that if you are upgrading from a version prior to 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 then you must back up your database, install
<ProductName>Postgres95</ProductName> v1.09, restore your database, then back it up again. <ProductName>Postgres95</ProductName> v1.09, restore your database, then back it up again.
You should also read files /usr/src/pgsql/migration/*. You should also read the release notes which should cover any release-specific issues.
</Para> </Para>
<caution>
<Para> <Para>
You must make sure that your database is not updated in the middle of You must make sure that your database is not updated in the middle of
your backup. If necessary, bring down postmaster, edit the permissions 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 in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename> to allow only you on, then
bring postmaster back up. bring <application>postmaste</application>r back up.
</Para> </Para>
</caution>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
If you are upgrading an existing system then kill the postmaster. Type If you are upgrading an existing system then kill the postmaster. Type
<ProgramListing> <ProgramListing>
ps -ax | grep postmaster $ ps -ax | grep postmaster
</ProgramListing> </ProgramListing>
This should list the process numbers for a number of processes. Type This should list the process numbers for a number of processes. Type
the following line, with "???" replaced by the process id for process the following line, with <replaceable>pid</replaceable>
"postmaster". (Do not use the id for process "grep postmaster".) Type replaced by the process id for process
kill ??? <literal>postmaster</literal>.
with "???" modified as indicated. (Do not use the id for process "grep postmaster".) Type
<programlisting>
$ kill <replaceable>pid</replaceable>
</programlisting>
to actually stop the process.
<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
<programlisting>
$ /etc/rc.d/init.d/postgres.init stop
</programlisting>
to halt <productname>Postgres</productname>.
</tip>
</Para> </Para>
</Step> </Step>
...@@ -269,22 +331,25 @@ If you are upgrading an existing system then kill the postmaster. Type ...@@ -269,22 +331,25 @@ If you are upgrading an existing system then kill the postmaster. Type
If you are upgrading an existing system then move the old directories 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 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 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 old database in the <filename>/usr/local/pgsql/data</filename> directory tree. At a
minimum, save file /usr/local/pgsql/data/pg_hba.conf. minimum, save file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
</Para> </Para>
<Para> <Para>
Type the following: Type the following:
su <programlisting>
cd /usr/src $ su -
mv pgsql pgsql_6_0 $ cd /usr/src
cd /usr/local $ mv pgsql pgsql_6_0
mv pgsql pgsql_6_0 $ cd /usr/local
exit $ mv pgsql pgsql_6_0
$ exit
</programlisting>
</Para> </Para>
<Para> <Para>
If you are not using /usr/local/pgsql/data as your data directory 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 (check to see if environment variable PGDATA is set to something
else) then you will also want to move this directory in the same else) then you will also want to move this directory in the same
manner. manner.
...@@ -294,17 +359,26 @@ If you are upgrading an existing system then move the old directories ...@@ -294,17 +359,26 @@ If you are upgrading an existing system then move the old directories
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Make new source and install directories. The actual paths can be Make new source and install directories. The actual paths can be
different for your installation; be consistant throughout this procedure. different for your installation but you must be consistant throughout this procedure.
<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>make install</command> stage
of installation.
</note>
<para>
Type Type
<ProgramListing> <ProgramListing>
su $ su
cd /usr/src $ cd /usr/src
mkdir pgsql $ mkdir pgsql
chown postgres:postgres pgsql $ chown postgres:postgres pgsql
cd /usr/local $ cd /usr/local
mkdir pgsql $ mkdir pgsql
chown postgres:postgres pgsql $ chown postgres:postgres pgsql
exit $ exit
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
...@@ -313,8 +387,8 @@ If you are upgrading an existing system then move the old directories ...@@ -313,8 +387,8 @@ If you are upgrading an existing system then move the old directories
<Para> <Para>
Unzip and untar the new source file. Type Unzip and untar the new source file. Type
<ProgramListing> <ProgramListing>
cd /usr/src/pgsql $ cd /usr/src/pgsql
gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf - $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
...@@ -325,8 +399,8 @@ If you are upgrading an existing system then move the old directories ...@@ -325,8 +399,8 @@ If you are upgrading an existing system then move the old directories
you can specify your actual installation path for you can specify your actual installation path for
the build process (see the --prefix option below). Type the build process (see the --prefix option below). Type
<ProgramListing> <ProgramListing>
cd /usr/src/pgsql/src $ cd /usr/src/pgsql/src
./configure [ options as described below ] $ ./configure [ <replaceable>options as described below</replaceable> ]
</ProgramListing> </ProgramListing>
</Para> </Para>
...@@ -335,10 +409,19 @@ If you are upgrading an existing system then move the old directories ...@@ -335,10 +409,19 @@ If you are upgrading an existing system then move the old directories
"template" file from the files provided in the template subdirectory. "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 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 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 configure again, this time giving the <option>--with-template=TEMPLATE</option> option to
make the right file be chosen. (If you have to do this, please make the right file be chosen.
send email to scrappy@hub.org stating the output of the program
'./config.guess' and what the template file should be.) <note>
<title>Please Report Problems</title>
<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> showing both the output of the program
<application>./config.guess</application> and also what the template file should be.)
</note>
</Para> </Para>
<Para> <Para>
...@@ -391,54 +474,72 @@ If you are upgrading an existing system then move the old directories ...@@ -391,54 +474,72 @@ If you are upgrading an existing system then move the old directories
</Para> </Para>
<Para> <Para>
As an example, here is the configure script I use on a Sparc As an example, here is the configure script used on a Sparc
Solaris 2.5 system with /opt/postgres being the install base. Solaris 2.5 system with <filename>/opt/postgres</filename> being the install base.
<ProgramListing> <ProgramListing>
./configure --prefix=/opt/postgres \ $ ./configure --prefix=/opt/postgres \
--with-template=sparc_solaris-gcc --with-pgport=5432 \ --with-template=sparc_solaris-gcc --with-pgport=5432 \
--enable-hba --disable-locale --enable-hba --disable-locale
</ProgramListing> </ProgramListing>
Of course, in a real shell, you would type these three lines all Of course, you may type these three lines all
on the same line. on the same line.
</Para> </Para>
</Step> </Step>
<Step Performance="required">
<Para>
Install the <acronym>HTML</acronym> documentation. Type
<ProgramListing>
$ cd /usr/src/pgsql/doc
$ gmake install
</ProgramListing>
<para>
The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory.
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Compile the program. Type Compile the program. Type
<ProgramListing> <ProgramListing>
cd /usr/src/pgsql/src $ cd /usr/src/pgsql/src
gmake all >& make.log & $ gmake all >& make.log &
tail -f make.log $ tail -f make.log
</ProgramListing> </ProgramListing>
</Para> </Para>
<Para> <Para>
The last line displayed will hopefully be "All of PostgreSQL is The last line displayed will hopefully be
successfully made. Ready to install." At this point, or earlier <programlisting>
All of PostgreSQL is successfully made. Ready to install.
</programlisting>
At this point, or earlier
if you wish, type control-C to get out of tail. (If you have 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 problems later on you may wish to examine file make.log for
warning and error messages.) warning and error messages.)
</Para>
<Para>
If your computer does not have gmake (GNU make) then try running
make instead throughout the rest of these notes.
</Para>
<Para> <note>
Please note that you will probably find a number of warning <para>
You will probably find a number of warning
messages in make.log. Unless you have problems later on, these messages in make.log. Unless you have problems later on, these
messages may be safely ignored. messages may be safely ignored.
</Para> </note>
<Para> <Para>
If the compiler fails with an error stating that the flex command If the compiler fails with a message stating that
cannot be found then install flex as described earlier. Next, the <application>flex</application> command
change directory back to this directory, type "make clean", then cannot be found then install <application>flex</application> as described earlier.
recompile again. Next,
change directory back to this directory, type
<programlisting>
$ make clean
</programlisting>
then recompile again.
</Para> </Para>
<Para> <Para>
...@@ -446,10 +547,10 @@ Compile the program. Type ...@@ -446,10 +547,10 @@ Compile the program. Type
be specified on the command line using the COPT variable. be specified on the command line using the COPT variable.
For example, typing For example, typing
<ProgramListing> <ProgramListing>
gmake COPT="-g" all >& make.log & $ gmake COPT="-g" all >& make.log &
</ProgramListing> </ProgramListing>
would invoke your compiler's -g option in all steps of the would invoke your compiler's <option>-g</option> option in all steps of the
build. See src/Makefile.global.in for further details. build. See <filename>src/Makefile.global.in</filename> for further details.
</Para> </Para>
</Step> </Step>
...@@ -457,34 +558,38 @@ Compile the program. Type ...@@ -457,34 +558,38 @@ Compile the program. Type
<Para> <Para>
Install the program. Type Install the program. Type
<ProgramListing> <ProgramListing>
cd /usr/src/pgsql/src $ cd /usr/src/pgsql/src
gmake install >& make.install.log & $ gmake install >& make.install.log &
tail -f make.install.log $ tail -f make.install.log
</ProgramListing> </ProgramListing>
</Para> </Para>
<Para> <Para>
The last line displayed will be "gmake[1]: Leaving directory The last line displayed will be
`/usr/src/pgsql/src/man'". At this point, or earlier if you wish, <programlisting>
gmake[1]: Leaving directory `/usr/src/pgsql/src/man'
</programlisting>
At this point, or earlier if you wish,
type control-C to get out of tail. type control-C to get out of tail.
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
14) If necessary, tell UNIX how to find your shared libraries. You can 14) If necessary, tell your system how to find the new shared libraries. You can
do ONE of the following, preferably the first: do <emphasis>one</emphasis> of the following, preferably the first:
<SubSteps> <SubSteps>
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
As root, edit file /etc/ld.so.conf. Add a line As root, edit file <filename>/etc/ld.so.conf</filename>. Add a line
<programlisting> <programlisting>
<FileName>/usr/local/pgsql/lib</FileName> <FileName>/usr/local/pgsql/lib</FileName>
</programlisting> </programlisting>
to the file. Then run command <Command>/sbin/ldconfig</Command>. to the file. Then run command <Command>/sbin/ldconfig</Command>.
</Para> </Para>
</Step> </Step>
<Step Performance="optional"> <Step Performance="optional">
<Para> <Para>
In a bash shell, type In a bash shell, type
...@@ -509,15 +614,18 @@ to the file. Then run command <Command>/sbin/ldconfig</Command>. ...@@ -509,15 +614,18 @@ to the file. Then run command <Command>/sbin/ldconfig</Command>.
</Para> </Para>
<Para> <Para>
If, when you create the database, you get the message "pg_id: can't If, when you create the database, you get the message
load library 'libpq.so'" then the above step was necessary. Simply <programlisting>
pg_id: can't load library 'libpq.so'
</programlisting>
then the above step was necessary. Simply
do this step, then try to create the database again. do this step, then try to create the database again.
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
If it has not already been done, then prepare account postgres If it has not already been done, then prepare account <literal>postgres</literal>
for using <ProductName>Postgres</ProductName>. for using <ProductName>Postgres</ProductName>.
Any account that will use <ProductName>Postgres</ProductName> must Any account that will use <ProductName>Postgres</ProductName> must
be similarily prepared. (The following instructions are for a be similarily prepared. (The following instructions are for a
...@@ -525,13 +633,13 @@ Any account that will use <ProductName>Postgres</ProductName> must ...@@ -525,13 +633,13 @@ Any account that will use <ProductName>Postgres</ProductName> must
</Para> </Para>
<Para> <Para>
Add the following lines to your login shell, ~/.bash_profile: Add the following lines to your login shell, <filename>~/.bash_profile</filename>:
<ProgramListing> <ProgramListing>
PATH=$PATH:/usr/local/pgsql/bin PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man MANPATH=$MANPATH:/usr/local/pgsql/man
PGLIB=/usr/local/pgsql/lib PGLIB=/usr/local/pgsql/lib
PGDATA=/usr/local/pgsql/data PGDATA=/usr/local/pgsql/data
export PATH MANPATH PGLIB PGDATA export PATH MANPATH PGLIB PGDATA
</ProgramListing> </ProgramListing>
</Para> </Para>
...@@ -539,7 +647,7 @@ Any account that will use <ProductName>Postgres</ProductName> must ...@@ -539,7 +647,7 @@ Any account that will use <ProductName>Postgres</ProductName> must
Make sure that you have defined these variables before continuing Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type: with the remaining steps. The easiest way to do this is to type:
<ProgramListing> <ProgramListing>
source ~/.bash_profile $ source ~/.bash_profile
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
...@@ -549,7 +657,7 @@ Any account that will use <ProductName>Postgres</ProductName> must ...@@ -549,7 +657,7 @@ Any account that will use <ProductName>Postgres</ProductName> must
Create the database. <Emphasis>Do not do the following as root!</Emphasis> Create the database. <Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole. Type This would be a major security hole. Type
<ProgramListing> <ProgramListing>
initdb $ initdb
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
...@@ -557,13 +665,13 @@ Any account that will use <ProductName>Postgres</ProductName> must ...@@ -557,13 +665,13 @@ Any account that will use <ProductName>Postgres</ProductName> must
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Set up permissions to access the database system. Do this by editing Set up permissions to access the database system. Do this by editing
file /usr/local/pgsql/data/pg_hba.conf. The instructions are 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 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 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 location of this file will change accordingly.) This file should be
made read only again once you are finished. 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 If you are upgrading from v6.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 your old database on top of the one in your new database, rather than
redoing the file from scratch. redoing the file from scratch.
</Para> </Para>
...@@ -571,76 +679,73 @@ Any account that will use <ProductName>Postgres</ProductName> must ...@@ -571,76 +679,73 @@ Any account that will use <ProductName>Postgres</ProductName> must
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Run the regression tests.
<Para> The file <filename>/usr/src/pgsql/src/test/regress/README</filename> has detailed
The file /usr/src/pgsql/src/test/regress/README has detailed
instructions for running and interpreting the regression tests. instructions for running and interpreting the regression tests.
A short version follows here: A short version follows here:
</Para> </Para>
<substeps>
<Step Performance="required">
<Para> <Para>
Run postmaster from your <ProductName>Postgres</ProductName> superuser account (typically
account postgres).
<emphasis>Do not run <application>postmaster</application> from the root account!</emphasis>
Start the postmaster daemon running in the background by typing Start the postmaster daemon running in the background by typing
<ProgramListing> <ProgramListing>
$ cd $ cd
$ nohup postmaster > regress.log 2>&1 & $ nohup postmaster > regress.log 2>&1 &
</ProgramListing> </ProgramListing>
Run postmaster from your <ProductName>Postgres</ProductName> super user account (typically
account postgres).
<emphasis>Do not run <application>postmaster</application> from the root account!</emphasis>
</Para> </Para>
</Step> </Step>
<Step Performance="required">
<Para>
Run the regression tests.
(You can skip this step if you wish, but
we think skipping the tests is a BAD idea!)
</Para>
<Para>
The file /usr/src/pgsql/src/test/regress/README has detailed
instructions for running and interpreting the regression tests.
A short version follows here:
</Para>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
Type Type
<ProgramListing> <ProgramListing>
cd /usr/src/pgsql/src/test/regress $ cd /usr/src/pgsql/src/test/regress
gmake clean $ gmake clean
gmake all runtest $ gmake all runtest
</ProgramListing> </ProgramListing>
</Para> </Para>
<Para> <Para>
You do not need to type "gmake clean" if this is the first time you You do not need to type <command>gmake clean</command>
if this is the first time you
are running the tests. are running the tests.
</Para> </Para>
<Para> <Para>
You should get on the screen (and also written to file ./regress.out) 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 a series of statements stating which tests passed and which tests
failed. Please note that it can be normal for some of the tests to failed. Please note that it can be normal for some tests to
"fail". The script says a test has failed if there is any difference "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. 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 Thus, tests may "fail" due to minor differences in wording of error
messages, small differences in floating-point roundoff, etc, between messages, small differences in floating-point roundoff, etc, between
your system and the regression test reference platform. your system and the regression test reference platform.
"Failures" of this type do not indicate a problem with "Failures" of this type do not indicate a problem with
<ProductName>Postgres</ProductName>. <ProductName>Postgres</ProductName>.
The file ./regression.diffs contains the textual differences between The file <filename>./regression.diffs</filename> contains the textual differences between
the actual test output on your machine and the "expected" output the actual test output on your machine and the "expected" output
(which is simply what the reference system produced). You should (which is simply what the reference system produced). You should
carefully examine each difference listed to see whether it appears to carefully examine each difference listed to see whether it appears to
be a significant issue. be a significant issue.
</Para> </Para>
<para>
For example,
<itemizedlist>
<listitem>
<Para> <Para>
For a i686/Linux-ELF platform, no tests failed since this is the For a i686/Linux-ELF platform, no tests failed since this is the
v6.4 regression testing reference platform. v6.4 regression testing reference platform.
</Para> </Para>
<listitem>
<Para> <Para>
For the SPARC/Linux-ELF platform, using the 970525 beta version of For the SPARC/Linux-ELF platform, using the 970525 beta version of
<ProductName>Postgres</ProductName> v6.2 the following tests "failed": <ProductName>Postgres</ProductName> v6.2 the following tests "failed":
...@@ -648,11 +753,12 @@ $ nohup postmaster > regress.log 2>&1 & ...@@ -648,11 +753,12 @@ $ nohup postmaster > regress.log 2>&1 &
floating point numbers. select_views produces massively different output, floating point numbers. select_views produces massively different output,
but the differences are due to minor floating point differences. but the differences are due to minor floating point differences.
</Para> </Para>
</itemizedlist>
<Para> <Para>
Even if a test result clearly indicates a real failure, it may be a 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 localized problem that will not affect you. An example is that the
int8 test will fail, producing obviously incorrect output, if your <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 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 (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. something to worry about unless you need to store 64-bit integers.
...@@ -662,21 +768,25 @@ $ nohup postmaster > regress.log 2>&1 & ...@@ -662,21 +768,25 @@ $ nohup postmaster > regress.log 2>&1 &
Conclusion? If you do see failures, try to understand the nature of Conclusion? If you do see failures, try to understand the nature of
the differences and then decide if those differences will affect your the differences and then decide if those differences will affect your
intended use of <ProductName>Postgres</ProductName>. The regression intended use of <ProductName>Postgres</ProductName>. The regression
tests are a helpful tool, but they require some study to be useful. tests are a helpful tool, but they may require some study to be useful.
</Para> </Para>
<Para> <Para>
After running the regression tests, type After running the regression tests, type
<ProgramListing> <ProgramListing>
destroydb regression $ destroydb regression
cd /usr/src/pgsql/src/test/regress $ cd /usr/src/pgsql/src/test/regress
gmake clean $ gmake clean
</ProgramListing> </ProgramListing>
to recover the disk space used for the tests. (You may want to save to recover the disk space used for the tests. (You may want to save
the regression.diffs file in another place before doing this.) the <filename>regression.diffs</filename> file in another place before doing this.)
</Para> </Para>
</Step> </Step>
</substeps>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
If you haven't already done so, this would be a good time to modify If you haven't already done so, this would be a good time to modify
...@@ -686,45 +796,70 @@ $ nohup postmaster > regress.log 2>&1 & ...@@ -686,45 +796,70 @@ $ nohup postmaster > regress.log 2>&1 &
Here are some suggestions on how to do this, contributed by various Here are some suggestions on how to do this, contributed by various
users. users.
Whatever you do, postmaster must be run by user postgres AND NOT BY <para>
ROOT. This is why all of the examples below start by switching user 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 (su) to postgres. These commands also take into account the fact
that environment variables like PATH and PGDATA may not be set properly. that environment variables like PATH and PGDATA may not be set properly.
The examples are as follows. Use them with extreme caution. The examples are as follows. Use them with extreme caution.
a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris <itemizedlist>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
2.5.1 to contain the following single line: 2.5.1 to contain the following single line:
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D <programlisting>
/usr/local/pgsql/data" su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
b) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to <listitem>
<para>
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 contain the following lines and make it chmod 755 and chown
root:bin. root:bin.
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && { <programlisting>
#!/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 -D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' & -S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql' echo -n ' pgsql'
} }
</programlisting>
You may put the line breaks as shown above. The shell is smart 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 enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init. Note: Unlike most the postmaster process so the parent is init.
other examples, this one has been tested.
c) In RedHat v4.0 Linux edit file /etc/inittab to add the <listitem>
following single line: <para>
pg:2345:respawn:/bin/su - postgres -c In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
<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 "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
>> /usr/local/pgsql/server.log 2>&1 </dev/null" &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 (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 postmaster if it dies, but he doesn't know if there are other side
effects.) effects.)
d) The contrib/linux area of the <ProductName>Postgres</ProductName> distribution has an example </itemizedlist>
init.d script compatible with and tested using recent RedHat packages.
</Para> </Para>
</Step> </Step>
...@@ -739,7 +874,8 @@ $ nohup postmaster > regress.log 2>&1 & ...@@ -739,7 +874,8 @@ $ nohup postmaster > regress.log 2>&1 &
<step performance="required"> <step performance="required">
<para> <para>
Run the SQL command vacuum. This will clean up your database. Run the <acronym>SQL</acronym> command <command>VACUUM</command>.
This will clean up your database.
<step performance="required"> <step performance="required">
<para> <para>
...@@ -749,8 +885,10 @@ Back up your system. (You should probably keep the last few ...@@ -749,8 +885,10 @@ Back up your system. (You should probably keep the last few
</procedure> </procedure>
<para>
Ideally, the above tasks should be done by a shell script that is 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 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 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 e-mail us a copy of your shell script. We would like to set up
our own systems to do this too.) our own systems to do this too.)
...@@ -762,18 +900,18 @@ Back up your system. (You should probably keep the last few ...@@ -762,18 +900,18 @@ Back up your system. (You should probably keep the last few
If you are upgrading an existing system then reinstall your old database. If you are upgrading an existing system then reinstall your old database.
Type Type
<ProgramListing> <ProgramListing>
cd $ cd
psql -e template1 < db.out $ psql -e template1 < db.out
</ProgramListing> </ProgramListing>
If your pre-v6.2 database uses either path or polygon geometric data types, 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 then you will need to upgrade any columns containing those types. To
do so, type (from within psql) do so, type (from within psql)
<ProgramListing> <ProgramListing>
update YourTable set PathCol = UpgradePath(PathCol); UPDATE <replaceable>FirstTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
update YourTable set PolyCol = UpgradePoly(PolyCol); UPDATE <replaceable>SecondTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
... ...
vacuum; VACUUM;
</ProgramListing> </ProgramListing>
UpgradePath() checks to see that a path value is consistant with the UpgradePath() checks to see that a path value is consistant with the
...@@ -795,34 +933,39 @@ Back up your system. (You should probably keep the last few ...@@ -795,34 +933,39 @@ Back up your system. (You should probably keep the last few
<Para> <Para>
Clean up after yourself. Type Clean up after yourself. Type
<ProgramListing> <ProgramListing>
rm -rf /usr/src/pgsql_6_0 $ rm -rf /usr/src/pgsql_6_0
rm -rf /usr/local/pgsql_6_0 $ rm -rf /usr/local/pgsql_6_0
# Also delete old database directory tree if it is not in # Also delete old database directory tree if it is not in
# /usr/local/pgsql_6_0/data # /usr/local/pgsql_6_0/data
rm ~/postgresql-v6.2.1.tar.gz $ rm ~/postgresql-v6.2.1.tar.gz
</ProgramListing> </ProgramListing>
</Para> </Para>
</Step> </Step>
<Step Performance="required"> <Step Performance="required">
<Para> <Para>
You will probably want to print out the documentation. Here is how 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>
Here is how
you might do it if you have Ghostscript on your system and are you might do it if you have Ghostscript on your system and are
writing to a laserjet printer. writing to a laserjet printer.
<programlisting> <programlisting>
alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE' $ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts $ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
# Print out the man pages. $ gunzip user.ps.gz
man -a -t /usr/local/pgsql/man/*/* > manpage.ps $ gshp -sOUTPUTFILE=user.hp user.ps
gshp -sOUTPUTFILE=manpage.hp manpage.ps $ gzip user.ps
rm manpage.ps $ lpr -l -s -r manpage.hp
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
</programlisting> </programlisting>
</Step> </Step>
...@@ -834,7 +977,9 @@ Back up your system. (You should probably keep the last few ...@@ -834,7 +977,9 @@ Back up your system. (You should probably keep the last few
supported platforms. We therefore ask you to let us know if you did 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. or did not get <ProductName>Postgres</ProductName> to work on you system.
Please send a Please send a
mail message to pgsql-ports@postgresql.org telling us the following: mail message to
<ulink url="mailto:pgsql-ports@postgresql.org">pgsql-ports@postgresql.org</ulink>
telling us the following:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
...@@ -880,7 +1025,7 @@ see <ProductName>Postgres</ProductName> do something. That's easy. Invoke the ...@@ -880,7 +1025,7 @@ see <ProductName>Postgres</ProductName> do something. That's easy. Invoke the
to <ProductName>Postgres</ProductName>, <Application>psql</Application>: to <ProductName>Postgres</ProductName>, <Application>psql</Application>:
<ProgramListing> <ProgramListing>
% psql template1 % psql template1
</ProgramListing> </ProgramListing>
(psql has to open a particular database, but at this point the only one (psql has to open a particular database, but at this point the only one
...@@ -987,14 +1132,21 @@ and look for the mailing lists. ...@@ -987,14 +1132,21 @@ and look for the mailing lists.
<Note> <Note>
<Para> <Para>
For some ports, these notes may be out of date. Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
the source distribution. For some ports, the notes below may be out of date.
</Para> </Para>
</Note> </Note>
<Sect2> <Sect2>
<Title>Ultrix4.x</Title> <Title>Ultrix4.x</Title>
<Para> <para>
<note>
<para>
There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
</note>
<para>
You need to install the libdl-1.1 package since Ultrix 4.x doesn't You need to install the libdl-1.1 package since Ultrix 4.x doesn't
have a dynamic loader. It's available in have a dynamic loader. It's available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
...@@ -1058,7 +1210,7 @@ The linux-elf port installs cleanly. See the Linux FAQ for more details. ...@@ -1058,7 +1210,7 @@ The linux-elf port installs cleanly. See the Linux FAQ for more details.
the general public. Contact Info@RnA.nl for information. the general public. Contact Info@RnA.nl for information.
<Para> <Para>
We have no recent reports of successful NeXT installations (for v6.2.1). We have no recent reports of successful NeXT installations (as of v6.2.1).
However, the client-side libraries should work even However, the client-side libraries should work even
if the backend is not supported. if the backend is not supported.
</Para> </Para>
......
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