.\" 
.\" POSTGRES Data Base Management System
.\" 
.\" Copyright (c) 1988 Regents of the University of California
.\" 
.\" Permission to use, copy, modify, and distribute this software and its
.\" documentation for educational, research, and non-profit purposes and
.\" without fee is hereby granted, provided that the above copyright
.\" notice appear in all copies and that both that copyright notice and
.\" this permission notice appear in supporting documentation, and that
.\" the name of the University of California not be used in advertising
.\" or publicity pertaining to distribution of the software without
.\" specific, written prior permission.  Permission to incorporate this
.\" software into commercial products can be obtained from the Campus
.\" Software Office, 295 Evans Hall, University of California, Berkeley,
.\" Ca., 94720.  The University of California makes no representations
.\" about the suitability of this software for any purpose.  It is
.\" provided "as is" without express or implied warranty.
.\" 
.\" ----------------------------------------------------------------
.\"	POSTGRES version 4.0.1 setup instructions
.\"
.\" ----------------------------------------------------------------
.de RV
.ie "\\$2"" \
\{\
.	ds VT "<No Title>
.	ds VN "<Unaudited Revision>
.	ds VD \*(td
.\}
.el \
\{\
.	ds VT \\$7
.	ds VD \\$4
.	ds VN \\$3
.\}
..
.hx
.fo ''%''
.ce 99
.ps 18
.b
POSTGRES INSTALLATION INSTRUCTIONS
.r
.ps 14
.sp 0.25v
C-Only Release 4.0.1
.sp 0.25v
.ce 0
.sp
.\" ----------------
.tm    Document Overview
.\" ----------------
.ds PG "\\s-2POSTGRES\\s+2
.sh 0 "Document Overview"
.(l
    Document Overview
    Introduction
    Site Requirements
	Hardware
	Software
	Distribution Tape
	Expertise
	Configuration
	    Operating System
	    Disk Partition
	    Swap Partition
	    Kernel
	    Lisp
    Installing \*(PG
	Overview
	Preparation
	    Finding Space for \*(PG
	    Creating /usr/postgres
	    Creating the \*(lqpostgres\*(rq user
	Loading
	    Loading \*(PG
	Configuration
	    Kernel reconfiguration
	    Configuring \*(PG
	Compiling
	    Compiling \*(PG
	    Creating the initial database
	Testing
	    Testing \*(PG
    Running \*(PG
	The \*(PG Postmaster
	The \*(PG Terminal Monitor
	The \*(PG Backend
	\*(PG Support Programs
    Optional Installation
	Installing LIBPQ, the \*(PG frontend library
	Performance Tuning
	Demo Database
	Minimal Installation
    Documentation
	Printing the Manual and Reference
	    If you do not have a Postscript printer
	Printing the Technical Reports and Tutorials
	    If the directory has a makefile
    Miscellaneous
	Bug Reports
	Known Bug List
	Consulting
	Postgres BBS
.)l
.bp
.\" ----------------
.tm    Introduction
.\" ----------------
.sh 1 "Introduction"
.pp
This document gives installation instructions for the \*(PG
database system under development at the University of
California, Berkeley.
\*(PG is distributed in source code format and is the
property of the Regents of the University of California.
However, the University will grant unlimited commercialization
rights for any derived work on the condition that it
obtain an educational license to the derived work.
For further information, consult the Berkeley Campus
Software Office, 295 Evans Hall, University of
California, Berkeley, CA 94720.
.pp
The University and the \*(PG development group
provide no warranty as to the fitness of the code for
any purpose whatsoever,
and cannot guarantee to assist in fixing problems.
This is *unsupported* software.
.\" ----------------
.tm    Site Requirements
.\" ----------------
.sh 1 "Site Requirements"
.pp
.sh 2 "Hardware"
.pp
\*(PG currently has been tested by the Postgres development team on Sun
Microsystems 3/xx family of
processors with SunOS 3.4, or 3.5, and 4.0, and Sparc architecture machines
(Sparcstation and Sun 4) running SunOS 4.0 and higher.  Postgres is also
supported on DECstations 3100's and 5000's running Ultrix 4.0 and higher.
Tested but unsupported ports for DECstation Ultrix lower than 4.0
are included.  These ports are unsupported for
the following reasons: the old Ultrix dynamic loader is quite buggy.
In order to use \*(PG,
your machine should have at least 8 megabytes of memory
and you will require at least 45 megabytes of disk space
to hold source,
binaries,
and user databases.
If you choose to compile \*(PG for source-level debugging,
you will need roughly twice as much disk space.
See the section on compilation for details.
.pp
The DECstation version requires a kernel which allows 4 megabytes of
shared memory.
.sh 2 "Software"
.pp
This implementation of \*(PG is completely in C.
The distribution contains no Lisp or C++ code.
.sh 2 "Distribution tape"
.pp
These instructions assume you have a \*(PG Version 4.0.1
distribution tape (in either 9 track, SCSI cartridge, or TK50 cartridge
format)
or a \*(PG tar file.
.sh 2 "Expertise"
.pp
Once a site is properly configured and \*(PG is properly installed,
very little UNIX expertise is required to maintain things.
However,
initially setting things up for your site to run \*(PG
may be difficult and we advise that the person installing
\*(PG be familiar with the various system administration
procedures.
Also note that various
steps require superuser authority on the system,
so we advise
that your site's system administrator read this document also.
.sh 2 "Configuration"
.pp
This section briefly describes the configuration you
need to run \*(PG.
Read this to familiarize
yourself with the procedure.
Detailed instructions for making
appropriate modifications to your system are given later in this
document.
.sh 3 "Operating System"
.pp
\*(PG expects things to be configured for BSD by default.
If the default on your site is to use the SunOS SysV compiler
and libraries then you may have to make some changes to this
procedure before compiling \*(PG.
.pp
One exception to this rule is that we use Sun's SysV-compatible
.i make
to build the system.
This is the version of
.i make
that is installed in both the BSD and SysV environments on Suns,
so this should pose no problems on these platforms.  We have no
problems on DECstations either.
.sh 3 "Disk Partition"
.pp
\*(PG requires 45 megabytes of disk space,
preferably on a single partition.
If you don't have enough space,
it is still possible to compile and run \*(PG but you will have to
modify the installation scripts.
.sh 3 "Kernel"
.pp
\*(PG makes use of the optional System V shared memory operations
provided by SunOS, DEC Ultrix, and Dynix,
which require a properly configured kernel which is in general different
than the factory-shipped "generic" kernel.
See the section on kernel configuration for details.
.\" ----------------
.tm    Installation
.\" ----------------
.sh 1 "Installing \*(PG"
.pp
\*(PG installation consists of the following steps:
.ip \0\0\0\(bu
Preparation
.ip \0\0\0\(bu
Loading
.ip \0\0\0\(bu
Configuration
.ip \0\0\0\(bu
Compilation
.ip \0\0\0\(bu
Testing
.lp
Each of these steps is described below.
It is advised that you read over
each of these steps carefully before beginning the installation.
.\" ----------------
.tm    Preparation
.\" ----------------
.sh 2 "Step 1 \- Preparation"
.pp
Some of the tasks involved in this step normally fall in
the domain of the site's system administrator and may require
superuser authority.
If possible,
we advise you to have your
system administrator perform these steps.
.sh 3 "Find a good place for \*(PG"
.pp
You should locate a disk partition with
at least 45 megabytes of free space available for \*(PG.
If you haven't any single partition with 25 megabytes free,
you might have to spread apart the \*(PG directories across several
partitions,
and glue them together with symbolic links.
.sh 3 "Creating the \*(PG directory"
.pp
Once you have located a partition with enough space,
create a directory called
.q postgres
someplace on this partition.
Then \fBcd\fR to this directory and type \fBpwd\fR.
This is the full
path of the directory you will install postgres in.
Write it down in preparation for the next step.
For example:
.sp
.(l
# \fBdf\fR
Filesystem	kbytes	used	avail	capacity  Mounted on
/dev/xy0a	  8421	  6703	  875	   88%	    /
/dev/xy0f	 10829	  6743	 3003	   69%      /pub.MC68020
/dev/xy2h	110811   81181  18548	   81%      /usr3
/dev/xy2g	221279  167405  31746	   84%      /b
/dev/xy1g	221279  138365  60786	   69%      /public
/dev/xy1a	  8179	   944	 6417	   13%      /tmp
/dev/xy0h	119999  101623	 6376	   94%      /usr.MC68020
/dev/xy0g	156033  135499	 4930	   96%      /usr2
/dev/rf0d	539421  465026  20452	   96%      /a
.i
	/public looks like a good place (it has 60 megs free) so we decide
	to create the postgres directory there...
.r
# \fBcd /public\fR
# \fBmkdir postgres\fR
# \fBcd postgres\fR
# \fBpwd\fR
/public/postgres
#
.)l
.sh 2 "Creating /usr/postgres"
.pp
\*(PG expects to be
.i logically
installed in a directory
called
.q /usr/postgres ,
so you must create a symbolic link
from /usr/postgres to whatever directory you created in the
previous step.
In our example,
we would now type:
.sp
.(l
# \fBln -s  /public/postgres  /usr/postgres\fR
.)l
.sh 2 "Creating the \*(lqpostgres\*(rq user"
.pp
Finally, we need to create a user called \*(lqpostgres\*(rq whose
shell is /bin/csh and whose home directory is /usr/postgres.
This can be done using the "adduser" procedures particular to your
platform and site.  See your system administration manual for details.
.lp
.b Note:
.pp
Due to a bug in this release, the "postgres" user must be user 6 (six).
Otherwise, you may encounter problems with backends hanging, etc.
See the 
.b Release
.b Notes
(described in Section 6.2 of this document)
for instructions on how to get around this problem
if it causes problems at your site.  If it is not convienent for you to make
the "postgres" user userid 6, complete the below instructions on
.b Loading
\*(PG,
but read the 
.b Release
.b Notes
notes on how to get around this problem
.b before
continuing on to the
.b Configuration
section.
.pp
.\" ----------------
.tm    Loading
.\" ----------------
.sh 2 "Step 2 - Loading \*(PG"
.pp
After completing step 1 (Preparation),
you should be ready to load
the \*(PG files onto your system.
To do this,
you will need either
a distribution tape or a \*(PG tar file.
.pp
If you are loading \*(PG from a tape, follow these instructions;
if you are loading from a tar file obtained via FTP, skip to the
section "Loading \*(PG from a Tar File".
.sh 3 "Loading \*(PG from a Tape"
.pp
Login as postgres.
.pp
3.  Run "tar" with the "extract, verbose, file" options:
.pp
% tar xvf <tape-device>
.sp
where <tape-device> is the name for your tape device, i.e.,
/dev/rmt0, /dev/rst8, etc.
.pp
The file "postgres-v4r0r1.tar.Z" will appear in your \*(PG home directory.
You may need to re-wind your tape to get it out of your tape
drive - see your system administrator for instructions.
.pp
Please proceed to the section "Loading \*(PG from a Tar File".
.pp
.sh 2 "Loading \*(PG from a Tar File"
.pp
If you are not logged in as \*(PG already, log in as \*(PG.
Make sure your current working directory is the \*(PG home
directory, and that the \*(PG tar file is there.
For the purpose of this discussion, the \*(PG tar file will be called
.pp
postgres-v4r0r1.tar.Z
.pp
Uncompress the tar file.
.pp
% uncompress postgres-v4r0r1.tar.Z
.pp
A larger file should now be in the \*(PG home directory, and the '.Z'
ending should be gone, so it is now named
.pp
postgres-v4r0r1.tar
.pp
Extract \*(PG from the tar file, using the "extract, verbose, file"
options:
.pp
% tar xvf postgres-v4r0r1.tar
.pp
Lots of file names and such should appear on the screen.
This step may take several minutes.
.pp
Now do an "ls":
.pp
The output of the ls should look something like:
.(l
COPYRIGHT	bench/	demo/	newconf/	src/
README	doc/	ref/	test/	sample/	video/
.)l
.pp
At this point you have loaded the \*(PG files.
Other directories will be created by the installation process.
.sp
.\" ----------------
.tm    Configuration
.\" ----------------
.sh 2 "Step 3 - Configuration"
.pp
This step requires familiarity with configuring a UNIX kernel.
If you are unfamiliar with this procedure,
we advise you to read the
section on configuring a kernel in the SunOS or DEC system administration
manual carefully.
This task requires superuser authority and should
probably not be done without the assistance of your system administrator.
We assume that whoever undergoes this procedure has an understanding
of the process and procedures involved.
.pp
\*(PG uses shared memory segments which must be compiled into the
kernel of the host which will act as the \*(PG server.
If you try to run a postgres backend process on a machine without enough
shared memory, the backend will abort with an error message.
.pp
This is by far the most complicated part of the installation
so these steps should be performed by someone with system administration
experience.  Again, we advise you to consult
the system administration section of your manual
before doing this step.
.pp
For a brief discussion of shared memory,
you may want to consult the Man pages for \fIshmget()\fR,
\fIshmop()\fR, \fIshmctl()\fR, etc.  Now proceed to the appropriate
section for your machine.
.pp
.sh 3 "Kernel reconfiguration for Suns and Sparcs"
.pp
In order to reconfigure Sun or Sparc kernel, you will have to become root
and add some lines to /usr/sys/conf (your kernel config file)
and /usr/sys/conf/param.c (your kernel parameters file).
We
.i strongly
advise you to make a spare copy of your system's original config
and parameter files before you make any changes.
.lp
The following lines should be added to /usr/sys/conf/KERNEL:
.sp
.(l
options		IPCMESSAGE		# SystemV IPC Message Facility 
options		IPCSEMAPHORE	# SystemV IPC Semaphore Facility
options		IPCSHMEM		# SystemV IPC Shared-Memory Facility
options		EMOREIPCS	# more semaphores and shared memory (for 8M)
.)l
.sp
.lp
At Berkeley, we substitute the line: 
.(l 
options		EMOREIPCS	# more semaphores and shared memory (for 8M)
.)l
.lp
with the line:
.(l
options		TTMOREIPCS	# more semaphores and shared memory (for 32M)
.)l
.lp
to allocate more shared memory so that we can run more \*(PG backends
at the same time.  Either of the lines will result in a kernel that
has enough shared memory allocated.
.lp
Also add the following lines to the \fItop\fR of /usr/sys/conf/param.c:
.sp
.(l
/*
 * LOCAL DEFINITIONS START
 */

#ifdef	EMORESEMS
#define EMOREIPCS
#endif	/* defined(EMORESEMS) */

#ifdef	TTMORESEMS
#define TTMOREIPCS
#endif	/* defined(TTMORESEMS) */

#ifdef	EMOREIPCS
#define SEMMNI		30	/* # of semaphore identifiers */
#define SEMMNS		180	/* # of semaphores in system */
#define SEMUME		10	/* max # of undo entries per process */
#define SEMMNU		30	/* # of undo structures in system */

#define SHMPOOL 	1536		/* max total shared memory system wide (in Kbytes) */
#define SHMSEG		6	/* max attached shared memory segments per process */
#define SHMMNI		100	/* # of shared memory identifiers */
#endif	/* defined(EMOREIPCS) */

#ifdef	TTMOREIPCS
#define SEMMNI		60	/* # of semaphore identifiers */
#define SEMMNS		384	/* # of semaphores in system */
#define SEMUME		10	/* max # of undo entries per process */
#define SEMMNU		30	/* # of undo structures in system */

#define SHMPOOL 	8192		/* max total shared memory system wide (in Kbytes) */
#define SHMSEG		6	/* max attached shared memory segments per process */
#define SHMMNI		100	/* # of shared memory identifiers */
#endif				/* defined(TTMOREIPCS) */

/*
 * LOCAL DEFINITIONS END
 */
.)l
.pp
After adding these lines,
run config over the config file,
install the new kernel,
and reboot.
.sp
.sh 3 "Kernel reconfiguration for DECs"
.pp
In order to reconfigure your DECstation 3100 or 5000 Ultrix kernel,
you will have to become root and add some lines to /usr/sys/conf
(your kernel config file).
.sp
The following lines should be added to /usr/sys/conf/KERNEL:
.sp
.(l
smmax           256
smseg           12
smbrk           1024
.)l
.pp
After adding these lines, run 
.i config
over the configuration file,
install the new kernel, and reboot.
.sp
.\" ----------------
.tm    Compiling
.\" ----------------
.sh 2 "Configuring \*(PG"
.pp
This release of \*(PG
may require some configuration.
For performance reasons, Postgres is by default compiled with the optimizer
enabled and internal debugging assertions disabled.  If you plan to modify
Postgres, you may want to enable debugging (note that this will take Postgres
up to about 50 megs from about 45 megs otherwise), and enable internal
debugging assertions.
.pp
To enable compiler directives, 
read the file ./newconf/CONFIG/README
for instructions on what to change.
Now to edit the configuration file,
.(l
.sp 0.5v
% \fBcd /usr/postgres/newconf/CONFIG\fP
.sp 0.5v
% \fBvi config.mk.<port>\fP
.)l
.pp
where
.i <port> is the following:
.(l
dec	\- DS3100 running Ultrix LOWER than 4.0
ultrix4	\- DS3100, 5000, 5500, etc. running Ultrix 4.0 or higher
sun	\- Sun 3 running SunOS 3.4 or 3.5
sunos4	\- Sun 3 running SunOS 4.0 or higher
sparc	\- Sparcstation or Sun 4
.)l
The
.i only
thing we recommend changing is the
GCFLAGS variable.  Remember the
.b port
.b name
used here as it is necessary for Step 4.
.pp
.sh 2 "Step 4 - Compiling and Installing \*(PG"
Now you are ready to install Postgres.  To do so,
simply execute the following commands:
.(l
% \fBcd ~postgres/newconf\fR
% \fBsetenv POSTGRESHOME ~postgres\fR
% \fB./Make install\fR
.)l
.pp
.lp
.i Make
.i install
will ask you for the port you wish to use.  Use the port name that you
used in 
.b Configuring
\*(PG.
You will also be asked for the name of the object tree directory;
the default is ~postgres/obj.<port>.  (throughout the rest of this document
obj.<port> refers to the object tree directory).  This step will take from
about 40 minutes on Sparc II or DEC 5000 class machines to several hours
on Sun 3's.
The POSTGRESHOME environment variable is the home directory of the Postgres
user.  In the course of the installation process, the Postgres
.b bin
and 
.b data
directories will be created and populated.
.pp
.i Make
is a C shell script that runs
.i make
with Makefiles that are constructed on the fly.
If you have problems at this point,
it is possible that your
.i \&.cshrc
file does strange things \*-
changes directories,
sets or unsets environment variables,
and so on.
.pp
You should see no errors during this phase, except possibly for warnings
(which can be ignored) when compiling the output of
.i yacc
and
.i lex.
.sh 3 "Creating the initial database"
.pp
\*(PG databases are stored in the directory ~postgres/data.
After you have compiled \*(PG,
you will need to create the
initial database.
To do this,
type 
.(l
% \fBsetenv POSTGRESHOME ~postgres\fR
% \fB~postgres/bin/postmaster &\fR
% \fB~postgres/bin/createdb postgres\fR
% \fBkill %~postgres/bin/postmaster\fR
.)l
This will create the bootstrap template database, from which
the database 
.q postgres
will be generated.  The
.i postmaster
program will be discussed later - however, you must have it running in order
to run 
.i createdb.
If several users wish to use \*(PG,
we advise you to create additional databases,
one for each user.
This can be done by running
.i createdb
with the username as the first argument.
For example,
to create a database for the user \*(lqbill\*(rq,
type
.(l
% \fB~postgres/bin/createdb bill\fR
.)l
.\" ----------------
.tm    Testing
.\" ----------------
.sh 2 "Step 4 - Testing"
.sh 3 "Testing \*(PG"
.pp
After compiling the \*(PG backend and support programs and
creating the initial database,
you should test your compilation
with the following.
Commands you should type appear in \fBboldface\fP.
.(l
\fB% ~postgres/bin/postgres\fR
.ft CW
	---debug info---
	Quiet =        f
	Noversion =    f
	override  =    f
	DatabaseName = [postgres]
	----------------

	**** Transaction System Active ****
	InitPostgres()..

POSTGRES backend interactive interface
$Revision: 1.25 $ $Date: 1992/08/27 06:08:25 $
	StartTransactionCommand() at Thu Nov  2 15:43:35 1989
.ft
> \fBretrieve (pg_user.all)\fP
.ft CW
 now in make_Var
relation = pg_user, attr = usecatupd
vnum = 1
	...
.ft
	\fIlots of debugging output...\fP
.ft CW

---- 	parser outputs :
((1 retrieve nil (("pg_user" 86 0 nil nil ))0 nil )((#S(resdom :resno 1
:restype 19 :reslen 16 :resname "usename" :reskey 0 :reskeyop 0)#S(var
	...
.ft
	\fIlots more debugging output...\fP

.ft CW
	ProcessQuery() at Thu Nov  2 15:43:50 1989

blank
	 1: usename	(typeid = 19, len = 16, byval = f)
	 2: usesysid	(typeid = 21, len = 2, byval = t)
	 3: usecreatedb	(typeid = 16, len = 1, byval = t)
	 4: usetrace	(typeid = 16, len = 1, byval = t)
	 5: usesuper	(typeid = 16, len = 1, byval = t)
	 6: usecatupd	(typeid = 16, len = 1, byval = t)
	----
	 1: usename = "postgres"	(typeid = 19, len = 16, byval = f)
	 2: usesysid = "6"	(typeid = 21, len = 2, byval = t)
	 3: usecreatedb = "t"	(typeid = 16, len = 1, byval = t)
	 4: usetrace = "t"	(typeid = 16, len = 1, byval = t)
	 5: usesuper = "t"	(typeid = 16, len = 1, byval = t)
	 6: usecatupd = "t"	(typeid = 16, len = 1, byval = t)
	----
	 1: usename = "goh"	(typeid = 19, len = 16, byval = f)
	 2: usesysid = "234"	(typeid = 21, len = 2, byval = t)
	 3: usecreatedb = "t"	(typeid = 16, len = 1, byval = t)
	 4: usetrace = "t"	(typeid = 16, len = 1, byval = t)
	 5: usesuper = "t"	(typeid = 16, len = 1, byval = t)
	 6: usecatupd = "t"	(typeid = 16, len = 1, byval = t)
	----
	 ...

	CommitTransactionCommand() at Thu Nov  2 15:43:51 1989

	StartTransactionCommand() at Thu Nov  2 15:43:51 1989
.ft
	\fIIt works!\fP

\fI
	The above response is an example of the raw output
	generated by the backend.  Your actual output may be slightly
	different.  Normally, you would use a
	terminal monitor to talk to the backend instead.
	To leave the backend, type <ctrl-D>:
\fR
> ^D
%
.)l
.sp
.\" ----------------
.tm    Running
.\" ----------------
.sh 1 "Running \*(PG"
.pp
\*(PG is designed to be a multiuser system.
In practice,
\*(PG consists of three (or more) processes:
.ip \0\0\0\(bu
the postmaster,
.ip \0\0\0\(bu
the terminal monitor,
and
.ip \0\0\0\(bu
the backend.
.lp
Users are expected to use the terminal monitor.
The terminal monitor
sends commands to the postmaster which forwards commands to a backend.
If you just completed step 3,
then you have already been introduced to the \*(PG backend,
so we'll talk about the other two processes now.
.sh 2 "The \*(PG Postmaster"
.pp
The postmaster is a process which manages communication between the
user's terminal monitor and a \*(PG backend.
Without a running postmaster,
the terminal monitor will not be able to connect to a backend.
To start the postmaster, type:
.(l
% \fBcd ~postgres/bin\fR
% \fBsetenv POSTGRESHOME ~postgres\fR
% \fBpostmaster &\fR
.)l
Here we are using the default parameters for the postmaster.  For more
details, consult the Reference.
.sh 2 "The \*(PG Terminal Monitor"
.pp
The \*(PG terminal monitor is a front-end user interface to the
\*(PG backend.
To start a terminal monitor,
type
.(l
% \fBmonitor <database>\fR
.)l
.pp
\fIDatabase\fR is the name of the database you want to use. 
Now we will run the monitor:
.(l
.ft CW
Welcome to the C POSTGRES terminal monitor

Go 
*
.ft

\fI
The ``*'' is the terminal monitor prompt.  We are now
talking to the backend, so let's send a simple test
query:  list the names and user ids of the postgres users.
We terminate the query with a \eg \*- the ``go'' command
to the terminal monitor.
\fR

*\fBretrieve (u.usename, u.usesysid) from u in pg_user
\eg\fP

.ft CW
Query sent to backend is "retrieve (u.usename, u.usesysid) from u in pg_user"
 -----------------------------
 | usename     | usesysid    |
 -----------------------------
 | postgres    | 6           |
 -----------------------------
 | mike        | 799         |
 -----------------------------
 | sp          | 1511        |
 -----------------------------
 | jhingran    | 943         |
 -----------------------------
 | cimarron    | 2359        |
 -----------------------------
 | goh         | 1994        |
 -----------------------------
 | ong         | 2802        |
 -----------------------------
 | hong        | 2469        |
 -----------------------------
 | mao         | 1806        |
 -----------------------------
 | margo       | 2697        |
 -----------------------------
 | sullivan    | 1517        |
 -----------------------------
 | kemnitz     | 3491        |
 -----------------------------
 | choi        | 3898        |
 -----------------------------
 | mer         | 3665        |
 -----------------------------

Go 
.ft
.ft I
.pp
	Okay, this worked, too.  Now we'll quit.
.pp
*\fB\eq\fP
.ft CW
I live to serve you.
.ft
%
.)l
.sh 2 "The \*(PG Backend"
.pp
The \*(PG backend is the process which does all the \*(lqreal\*(rq
work.
This process is started by the postmaster when the postmaster
receives a connection from a terminal monitor,
so you should not normally need to start up the backend yourself.
Should you wish to
start the backend and talk to it directly (without a terminal monitor)
you can do this by typing:
.(l
% \fB~postgres/bin/postgres\fR \fIdatabase\fR
.)l
.lp
where \fIdatabase\fR is the name of the database you wish to use.
If you run a backend in this manner,
you will be talking to the backend parser directly.
We recommend using the terminal monitor; if you are using Postgres as a
multiuser system, running the backend can result in locking failures
and corrupt databases, as the Postmaster handles shared resources such
as semaphores and shared memory.
In addition, returned tuples are displayed more usefully
and input is buffered better.  
The backend is used interactively primarily during debugging.
.sh 2 "\*(PG Support Programs"
.pp
Included in \*(PG are a handful of support programs.
Most of these are used internally by the system but here is a list of
them for your information.
.(l
initdb		\- creates the initial template database
createdb		\- creates new postgres databases
createdb.sh	\- creates new postgres databases - old version
destroydb	\- destroys postgres databases
ipcclean		\- frees up garbage shared memory from failed backends
pg_version	\- make version numbers for createdb
pg_id		\- gets user id's for createdb
pg_uid		\- gets postgres user id for initializing the template database
pagedoc		\- disk page doctor
shmemdoc		\- shared memory buffer pool doctor
.)l
.sh 1 "Optional Installation"
.sh 2 "Installing LIBPQ, the \*(PG frontend library"
.pp
The file ~postgres/obj.<port>/libpq.a is created when you
compile the system.
This library contains various 
routines intended for use by frontend programs.
You use this library if you want to execute Postgres queries
from a C program.  If you plan on doing software development,
you may wish to copy this file to
/usr/lib so that the C compiler can reference it with -lpq.
To do this,
type:
.(l
# \fBcp ~postgres/obj.<port>/libpq.a   /usr/lib\fR
.)l
.sh 2 "Demo Database"
.pp
In ~postgres/demo are files to be included by the terminal monitor
to set up a demo database.
Additional files demonstrate inheritance,
historical queries,
abstract data types,
and various other features
of \*(PG.
A description of the demo database can be found
in ~postgres/demo/DEMO-README.
.sh 2 "Video Demo Database"
.pp
In ~postgres/video are files that were used in the 1991 Postgres SIGMOD
video.  These files demonstrate both the instance level and query rewrite
rule systems, views, versions, and spatial queries using R-Tree indices.
A description of the video database can be found in
~postgres/video/VIDEO-README.
.sh 2 "Wisconsin Benchmark Database"
.pp
In ~postgres/bench are files which are the queries used in the Postgres
version of the Wisconsin benchmark.  The Wisconsin benchmark illustrates
"basic" relational performance using B-Tree indices on nontrivial amounts
of data.  Instructions for running the benchmark are in
~postgres/bench/WISC-README.
.pp
.sh 2 "Minimal Installation"
.pp
The directories (in ~postgres) necessary
for a minimal running system are:
.(l
bin/		the binary programs comprising \*(PG
data/		support files and user created databases
files/		database initialization scripts
.)l
When compiled using the "default" compilation options as shipped, (ie
optimization and no debugging), these directories will take up about 5 Mbytes.
The following directories are necessary if Postgres is to ever be recompiled.
.(l
newconf/	the \*(PG configuration directory
obj.<port>/	compiled \*(PG object files
src/		\*(PG source files
.)l
.pp
When compiled using the "defaults", these directories will use about 16
Mbytes.
Additional Postgres directories are as follows:
.(l
demo/		demo database scripts
video/		video demo database scripts
bench/		Wisconsin benchmark database scripts
sample/		Sample LIBPQ application
doc/		postgres technical reports and the \*(PG Manual
ref/		\*(PG Reference source
.)l
.pp
These directories take up about 2 Mbytes, and can be reduced to about
200 Kbytes if the Postscript files in doc and ref are deleted. 
.pp
We do not recommend deleting these unless absolutely necessary.
.\" ----------------
.tm    Documentation
.\" ----------------
.sh 1 "Documentation"
.sh 2 "Printing the Manual"
.pp
The \*(PG manual is now in the file
.(l
\fB~postgres/doc/manual.me\fR
.)l
This manual replaces the old tutorials, which are no longer distributed.  It
is recommended that you read this manual before making extensive use of 
\*(PG.  A Postscript version of this manual is in
.(l
\fB~postgres/doc/psdump/manual.ps\fR
.)l
.pp
.sh 2 "Printing the Reference"
.pp
The Reference is the document which details the exact syntax used by
\*(PG commands, and provides interface definitions for LIBPQ and large
objects.  It is intended as a reference and should not be read cover to
cover.
.pp
If you have a Postscript printer, you can print the Reference by
changing directory to the 
.(l
\fB~postgres/ref\fR
.)l
directory, where you will find a Postscript file called \fBref.t\fR.
This file can be simply sent to the printer in whatever fashion your site
uses to print Postscript files.
.pp
If you do not have a Postscript printer, or you have font problems, etc.,
the \fBref\fR directory contains a /bin/sh script called "genref".  Edit
this script and set the appropriate parameters for printing at your site
in this script, and then execute it by typing
.(l
% \fBgenref\fR
.)l
This script will not actually try to send the job to the printer - rather
it will create the \fBref.t\fR output file.  You can then print the
manual by sending this file directly to the printer with the regular printing
commands used by your site.
.pp
If \fBgenref\fR fails, you may not have the \fBgrn\fR preprocessor.  This
preprocessor for troff allows pictures drawn with the \fBgremlin\fR graphics
editor to be printed using a "troff" command.  A script called \fBeatgrn\fR is
provided, which will cause \fBgenref\fR to ignore \fBgrn\fR directives and
print anyway - this will result in the reference being printed without
illustrations.  There is only one illustration, so this should not be too
much of a problem.
.pp
.sh 3 "If you do not have a Postscript printer"
.pp
If you do not have a Postscript printer, change the \fBpsroff\fR command in
the \fBgenref\fR script to the
text formatting command you use at your site, typically \fBnroff\fR,
\fBtroff\fR, or \fBditroff\fR.
As stated above, use the \fBeatgrn\fR script if you do not have \fBgrn\fR.
Output suitable
for a line-printer can be created using \fBnroff\fR.  
.pp
.sh 2 "Printing the Technical Reports and Tutorials"
.pp
Postscript versions of the Postgres technical reports, tutorials, and
release notes are in the directory \fB~postgres/doc/psdump\fR.  Some files
are not
included in Postscript form and are simply regular files - read the file
\fB~postgres/doc/README\fR for details.
.pp
The /bin/sh script
\fB~postgres/doc/print\fR
contains site-specific printing parameters, and understands the file extension
protocol used
in the \fBdoc\fR directory.  Once you set the site-specific parameters for
printing in this script, you should be able to print all the files in the
\fBdoc\fR easily, by executing
.(l
% \fBprint <filename>\fR
.)l
from the \fB~postgres/doc\fR directory.
.pp
Unlike the \fBgenref\fR script described above, this
script will send the job directly to the printer.  If you do not have the
\fBgrn\fR utility described above, you should use the \fBeatgrn\fR script here
as well.  For technical reports which require \fBmake\fR, continue to
the following section.
.pp
.sh 3 "If the directory has a makefile"
.pp
A couple of the technical reports use makefiles to generate their printable
versions rather than the \fBprint\fR script.  If the subdirectory has
a makefile, you will have
to change the site-specific parameters in the
makefile, run 
.(l
% \fBmake\fR
.)l
and then it will either print or create a printable file.  Note that if the
makefile uses \fBgrn\fR and you do not have access to this utility, you can
use the \fBeatgrn\fR script here as well.
.sh 2 "The 4.0.1 Release Notes"
.pp
The Postgres 4.0.1 Release Notes are in the file
\fB~postgres/doc/release4.0.1.me\fR.
Before working extensively with Postgres, you should read this file to
find new features, known bugs, and other useful information about this
release.
.pp
As described above, you can print this file by typing
.pp
.(l
% \fBprint ~postgres/doc/release4.0.1.me\fR
.)l
.\" ----------------
.tm    Miscellaneous
.\" ----------------
.sh 1 "Miscellaneous"
.sh 2 "Bug reports"
.pp
If you find a bug with \*(PG,
please send mail to
.(l
\0\0\0\0\0bug-postgres@postgres.Berkeley.EDU
or
\0\0\0\0\0(ucbvax!postgres!bug-postgres)
.)l
describing as precisely as possible the command that caused
the problem,
instructions on how to repeat the bug,
and a script showing the bug. 
.sh 2 "Known Bugs List"
.pp
A Known Bugs List with suggested workarounds is maintained on the machine
\fBpostgres.berkeley.edu\fR in the file \fBpub/postgres-v4r0r1.bugs\fR.  The
Internet address of this machine is \fB128.32.149.1\fR, and if you cannot
access Postgres, this file can be sent to you via e-mail.
.sh 2 "Consulting"
.pp
This software is unsupported,
public domain software.
Although we are interested in feedback,
it is impossible for us to make any
commitment to support in a research environment. 
.pp
If you do want to talk directly to the Postgres
group, electronic mail is strongly preferred.
We can be reached via the Internet as
.(l
\0\0\0\0\0post_questions@postgres.Berkeley.EDU
or
\0\0\0\0\0(ucbvax!postgres!post_questions)
.)l
We can also be reached at (415) 642-7520,
Monday through Friday,
between 1 and 4 PM Pacific Time.
.pp
.sh 2 "Postgres BBS"
A mailing list for Postgres announcements and discussion
is available for anyone who is interested.  If you wish
to subscribe to this mailing list, send mail to
.(l
\0\0\0\0\0postgres-request@postgres.Berkeley.EDU
.)l
with "Add" as the subject.  Note that mail sent to this address is processed
.b electronically.
.pp
The mailing list itself is called 
.(l
\0\0\0\0\0postgres@postgres.Berkeley.EDU
.)l
and all mail sent to this address will be 
will be routed to the mailing list membership.
