Finish commiting Bryan's patches...

INSTALL

-
 POSTGRES95 INSTALLATION INSTRUCTIONS
 Copyright (c) 1996 Regents of the University of California
 
 This directory contains the source and documentation for Postgres95
-(version 1.02)  Postgres95 is a derivative of POSTGRES 4.2 (the last
-release of the UC Berkeley research project).   For copyright terms
-for postgres95, please see the file named COPYRIGHT.   This version 
-was developed by a team of developers on the postgres developers
-mailing list.  Version 1.01 was developed by Jolly Chen and Andrew Yu.
+(version 2) Postgres95 is a derivative of POSTGRES 4.2 (the last
+release of the UC Berkeley research project).  For copyright terms for
+postgres95, 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.
+
+
+REQUIREMENTS TO RUN POSTGRES95
+------------------------------
 
 Postgres95 has been tested on the following platforms:
 
@@ -29,34 +33,42 @@ Postgres95 has been tested on the following platforms:
 	next		-	Motorola MC68K or Intel x86 on NeXTSTEP 3.2
   but these are guaranteed not to work as of yet.
 
-Postgres95 is also known to work on a number of other platforms that
-the authors have not personally tested.
+Postgres95 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.
 
-If you would like to migrate your databases from postgres 1.0 to
-postgres 1.02, see the directory called MIGRATION_1.0_TO_1.02.  People
-upgrading from version 1.01 do not have to make any database changes.
 
-----------------------------------------------------------------------
-To install Postgres95 on UNIX platforms:
+MIGRATING FROM POSTGRES VERSION 1
+---------------------------------
+
+Version 2 is mostly backward compatible with Version 1, but the database
+format is incompatible, so if you have databases that you use with Version
+1, you need to convert them before you can use them with Version 2.  Once
+you do that, you won't be able to use them with Version 1 anymore.
 
-1. Create the postgres login.
-   
-   Create a login called postgres (this requires root privileges). We 
-   recommend that you run the postmaster as the user postgres for security 
-   reasons.
+For details on how to do this conversion, see the file MIGRATION_V1_TO_V2.
+
+
+INSTALLING POSTGRES95
+---------------------
+
+Installing Postgres95 encompasses only installing the software on your system
+so you can use it to access (or create or manipulate) databases.  This
+step does not include actually creating any database or configuring your 
+system to use it.
+
+To install Postgres95 on UNIX platforms:
 
-   If you run the postmaster as yourself, be warned that you essentially
-   grant all database users the ability to execute arbitrary C functions
-   as you without your password. (In any case, DO NOT run the postmaster 
-   as root.)
+1. Unpack the source distribution into a source directory.  We'll assume
+   "/usr/src/postgres95" in this discussion.  This should be a new directory.
+  
+2. Set your current directory to the source directory:
 
-2. Compile and install Postgres95.
+   cd /usr/src/postgres95
 
-   If you have earlier versions of Postgres installed, you might want
-   to install Postgres95 in a different place.
+3. Build Postgres95:
 
    If you're installing Postgres95 on Ultrix 4.x or Linux, see the 
    porting notes at the end for additional packages that you need to install
@@ -75,139 +87,199 @@ To install Postgres95 on UNIX platforms:
    directory.  The configuration switches are fairly self-explanatory, but we
    will go over some of the more commonly-changed options:
 
-     -  PORTNAME specifies the platform on which Postgres95 is being build
-        (linux is the default). You might need to change it to reflect your 
-        platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris 2.4, 
-        ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0)
+     - PORTNAME specifies the platform on which Postgres95 is being build
+       (linux is the default). You might need to change it to reflect
+       your platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris
+       2.4, ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0)
 
-     -  SRCDIR specifies where the source files are located. (defaults
-        to $(POSTGRESDIR)/src.)
+     - SRCDIR specifies where the source files are located. (defaults to
+       $(POSTGRESDIR)/src.)
 
-     -  POSTSGRESDIR specifies the top-level directory where Postgres95
-        binaries, header files, libraries, and databases are installed.
+     - POSTGRESDIR specifies the top-level directory where Postgres95
+       binaries, header files, libraries, and databases are installed.
 
-     -  POSTGRESLOGIN specifies the user who will be doing initdb and
-        running the postmaster (defaults to postgres).  Do not set
-	this to root, or any users with UID = 0!
+     - NAMEDATALEN and OIDNAMELEN allows you to set the maximum length of
+       system identifiers (table names, function names, etc.)  It
+       defaults to 32.  You may alter this if you like, but be aware that
+       databases created with different NAMEDATALEN's do not
+       interoperate.
 
-     -  NAMEDATALEN and OIDNAMELEN allows you to set the maximum
-        length of system identifiers (table names, function names, etc.)
-        It defaults to 32.  You may alter this if you like, but
-        be aware that databases created with different NAMEDATALEN's
-        do not interoperate. 
+     - USE_READLINE specifies whether you want to use the GNU readline and
+       history libraries for the psql interactive frontend program.  GNU
+       readline is not supplied with postgres95 and can be found in the
+       usual ftp sites for GNU software.
 
-     -  USE_READLINE specifies whether you want to use the GNU
-        readline and history libraries for the psql interactive 
-        frontend program.
-        GNU readline is not supplied with postgres95 and can be found
-        in the usual ftp sites for GNU software.
+     - HBA specifies whether you wish to use host-based authentication
+       for postgres95.  See the section "How to Create a Database System"
+       for how to set up the HBA permissions if you decide to use HBA.
 
-      - HBA specifies whether you wish to use host-based
-        authentication for postgres95.  If you do use host-based
-        authentication, after installing, modify the file
-        $PGDATA/pg_hba accordingly. 
-
-   After editing src/Makefile.global, you are ready to compile and
-   install Postgres95 (it takes about 10 minutes on a 133Mhz Pentium
-   running linux):
+   After editing src/Makefile.global, you are ready to compile Postgres95
+   (it takes about 10 minutes on a 133Mhz Pentium running linux):
 
      % cd src
      % gmake 
-     % gmake install
 
-   The first gmake ultimately issues the message "All of Postgres95 is 
+   The gmake ultimately issues the message "All of Postgres95 is
    successfully made.  Ready to install."  If you don't get that, the make
    failed, and there should be error messages at the end detailing why.
 
-   After the installation is complete, check that you have the following files
-   in the top level Postgres95 directory (eg. /usr/local/postgres95).
+4. Install Postgres95
+
+   Installing just means placing all the files built in the previous step
+   into their live locations on your system. 
+
+     % gmake install
+
+   This will narrate all the files being installed.  You should watch and 
+   be sure the files are going to reasonable places and confirm for yourself
+   that they ended up where they belong.
+
+   Any error messages indicate something is wrong and you probably have to
+   correct it before Postgres95 will work.
+
+
+HOW TO CREATE A DATABASE SYSTEM
+-------------------------------
+
+Once you have Postgres installed, you'll need at least one database system
+on which to operate.  A database system is a collection of databases that
+are used together and fall under a single authority.  You can have as many
+database systems as you want on a single unix system.
 
-   You will find the following executables in the bin directory (which
-   should be included in the search path of your shell):
+You select a unix user to be the "postgres superuser" for a database
+system and that user, for one thing, owns all the unix files that hold
+all the data for that database system.  It is usually a good idea to create
+a user for the sole purpose of being a postgres superuser.
 
-     % ls /usr/local/postgres95/bin
-     cleardbdir*   destroydb*    pg_dump*      postgres*
-     createdb*     destroyuser*  pg_id*        postmaster@
-     createuser*   initdb*       pg_version*   psql*
+WARNING: Postgres95 is not secure.  Anyone who can connect to a database
+system can easily assume all the unix privileges of its Postgres
+superuser.  The simplest way is by creating and running a C language
+function.  There are plans to remedy this in future developent.
 
-   You will find the following in the database directory:
+The program initdb (part of Postgres) is what initializes (creates) a
+database system.  See the man page for initdb.
 
-     % ls -R /usr/local/postgres95/data
-     files/
-     pg_hba
-	
-     data/files:
-     global1.bki                   local1_template1.bki
-     global1.bki.source            local1_template1.bki.source
+Example:
 
-3. Initialize the database.
+  % initdb --pgdata=/usr/lib/postgres_data --username=postgres
 
-   After you have installed Postgres95, initialize the database by typing:
+This example creates the files for the database system in the directory
+/usr/lib/postgres_data and makes user "postgres" the Postgres superuser
+for the new database system.
 
-     % initdb
+By default, the user issuing the initdb command becomes the Postgres
+superuser, and only the unix superuser can specify any other user as the
+Postgres superuser.
 
-4. Start the postmaster.
+Setting up Permissions
+----------------------
 
-   Now, you are ready to make the system operational by running the
-   postmaster daemon. There are a few environment variables which affect
-   its operation:
-	PGDATA	- location of the database (eg. /usr/local/postgres95/data)
-	PGPORT	- TCP port where it listens for connection (eg. 5432)
-   You don't have to set these variables if you use the (compile time) 
-   default.
+The first thing you should do after creating a database system is set up
+the permissions for connecting to the database.  These are kept in the 
+file pg_hba in the data directory.  Initdb creates a sample version of
+this file, which contains comments telling you how to set it up.
 
-     % postmaster -S
+The Postmaster Daemon
+---------------------
 
-   
-5. Testing.
+Finally, in order to use the database system, you'll need to have a
+postmaster daemon running.  There is one postmaster process per database
+system.  The postmaster runs the program "postgres" and must run as the
+Postgres superuser.  See the postgres man page.
 
-   We suggest you run the regression tests to make sure the release
-   was installed successfully. The regression tests can be found in
-   src/test/regress. (see src/test/regress/README for more details)
+So, for example, you can login as the Postgres superuser and issue the
+command:
 
-     % cd /usr/local/postgres95/src/test/regress
+  % postgres -S -D/usr/lib/postgres/postgres_data -p5432
+
+This says to run the postmaster against the database system created above,
+to accept connections from users on the conventional TCP port 5432, and
+(-S) to run in the background without issuing messages about normal 
+execution.
+
+This is a good daemon to start via system startup scripts, using su (be
+careful NOT to run the postmaster as the unix superuser by mistake).
+
+
+TESTING POSTGRES95
+------------------
+
+We suggest you run the regression tests to make sure the release was
+installed successfully and works as designed in your environment.  The
+regression tests can be found in src/test/regress. (see
+src/test/regress/README for more details)
+
+     % cd /usr/src/postgres95/src/test/regress
      % gmake all runtest
 
-   This will run a whole slew of regression tests and might take a long
-   time to run.  When it's done, the output is in the file obj/regress.out.
-   You can compare this to a sample run that we supply in the file 
-   sample.regress.out. (You should get roughly the same output except
-   for some pathnames.) 
+This will run a whole slew of regression tests and might take a long time
+to run.  When it's done, the output is in the file obj/regress.out.  You
+can compare this to a sample run that we supply in the file
+sample.regress.out. (You should get roughly the same output except for
+some pathnames.)
 
      % diff obj/regress.out sample.regress.out
 
-   The regression test takes about half an hour to run on a Sparc 10.
-   You may want to use 'grep -v' to remove unsignificant differences.
+The regression test takes about half an hour to run on a Sparc 10.  You
+may want to use 'grep -v' to remove unsignificant differences.
+
+
+PLAYING WITH POSTGRES95
+-----------------------
 
-6. Run queries.
+After Postgres95 is installed, a database system is created, a postmaster
+daemon is running, and the regression tests have passed, you'll want to 
+see Postgres95 do something.  That's easy.  Invoke the interactive interface
+to Postgres95, psql, and start typing SQL:
 
-   After the database is initialized, you can create a new database. To
-   create a database, do the following:
+  % psql -d/usr/lib/postgres_data template1
 
-     % createdb foo
+(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).
 
-   To connect to the postmaster, you have a choice of two front-end programs.
-   ("psql" is recommended.  "monitor" is the old terminal monitor
-     supplied in earlier versions of Postgres)
-   
-     % psql foo
-Please read the file COPYRIGHT for copyright terms of POSTGRES95
+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: foo
+You are currently connected to the database: template1
 
-foo=> 
+template1=> 
 
-----------------------------------------------------------------------
-Questions? Bugs? Feedback?
+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, please read the Frequently Asked Questions and answers
-in the file called FAQ.
+First, please read the Frequently Asked Questions and answers in the file
+called FAQ.
 
 If you still have questions, please send them to
-postgres95@postgres95.vnet.net.   
+postgres95@postgres95.vnet.net.
 
 If you have a bug report to make, please send a filled out version of
 the file named "bug.template" to pg95-dev@ki.net.