postgresql/INSTALL

POSTGRESQL INSTALLATION INSTRUCTIONS
Copyright (c) 1996 Regents of the University of California

This directory contains the source and documentation for PostgreSQL
(version 6.0) PostgreSQL is a derivative of POSTGRES 4.2 (the last
release of the UC Berkeley research project).  For copyright terms for
PostgreSQL, please see the file named COPYRIGHT.  This version was
developed by a team of developers on the postgres developers mailing
list.  Version 1 (through 1.01) was developed by Jolly Chen and Andrew
Yu.


REQUIREMENTS TO RUN POSTGRESQL
------------------------------

PostgreSQL has been tested on the following platforms:

   aix            IBM on AIX 3.2.5
   alpha          DEC Alpha AXP on OSF/1 2.0
   BSD44_derived  OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
   bsdi           BSD/OS 2.0, 2.01, 2.1
   dgux           DG/UX 5.4R3.10
   hpux           HP PA-RISC on HP-UX 9.0
   i386_solaris   i386 Solaris
   irix5          SGI MIPS on IRIX 5.3
   linux          Intel x86 on Linux 1.2 and Linux ELF
                  (For non-ELF Linux, see LINUX_ELF below).
   sparc_solaris  SUN SPARC on Solaris 2.4
   sunos4          SUN SPARC on SunOS 4.1.3
   svr4           Intel x86 on Intel SVR4
   ultrix4        DEC MIPS on Ultrix 4.4

PostgreSQL has known problems/bugs on the following platforms:

   nextstep       Motorola MC68K or Intel x86 on NeXTSTEP 3.2

PostgreSQL is also known to work on a number of other platforms that the
authors have not personally tested.

You should have at least 8 MB of memory and at least 30 MB of disk space to
hold the source, binaries, and user databases.


MIGRATING FROM POSTGRES VERSION 1.*
-----------------------------------

People migrating data from earlier releases must dump the data under
1.09 and reload them under 6.0.  The pg_dump utility is designed to do
this.  It is important you use 1.09 because earlier releases may not
have the proper copy format to load into the 6.0 database.

INSTALLING POSTGRESQL
---------------------

Installing PostgreSQL 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.

Before you start, if you are using GNU flex, you should ensure that you
are not using Version 2.5.3. If you have this version, you should either
change to 2.5.2 or 2.5.4 or apply the patch in doc/README.flex

To install PostgreSQL on UNIX platforms:

1. Unpack the source distribution into a source directory.  We'll assume
   "/usr/src/pgsql" in this discussion.  This should be a new directory.
  
2. Set your current directory to the source directory:

   cd /usr/src/pgsql

3. Build PostgreSQL:

   If you're installing PostgreSQL on Ultrix 4.x or Linux, see the 
   porting notes at the end for additional packages that you need to install
   before installing PostgreSQL.

   If using Linux or Irix, you should also read the machine-specific FAQs.

   Our Makefiles require GNU make (called gmake in this document) and
   also assume that "install" accepts BSD options. The INSTALL
   variable in the Makefiles is set to the BSD-compatible version of
   install. On some systems, you will have to find a BSD-compatible
   install to the location of this program. (eg. bsdinst, which comes
   with the MIT X Window System distribution) 

   Customization can be done by editing src/Makefile.global. You may change
   the various configuration options here, such as where the PostgreSQL
   executable files are installed and where postgres looks for the database
   directory.  

   PostgreSQL V6.0 also supports src/Makefile.custom. This is not supplied
   with the distribution, but may be created to contain only the options 
   you wish to change in src/Makefile.global. This has the advantage that
   it will not be overwritten when you install a new version of PostgreSQL
   over the top of your current installation.

   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 PostgreSQL is being built.
       This is set to UNDEFINED. You will 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, etc.)

     - SRCDIR specifies where the source files are located. (defaults to
       $(POSTGRESDIR)/src.)

     - POSTGRESDIR specifies the top-level directory where PostgreSQL
       binaries, header files, libraries, and databases are installed.

     - 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 PostgreSQL and can be found in the
       usual ftp sites for GNU software.

   In the simplest case, you would create src/Makefile.custom containing
   just the line:

       PORTNAME= portname

   (where you replace portname with the name of the system you are using).

   Even easier is to enter the src directory and run the customize shell
   script which will prompt you with various questions and create
   Makefile.custom for you:

     % cd src
     % customize

   After editing src/Makefile.global or src/Makefile.custom, you are ready 
   to compile PostgreSQL (it takes about 10 minutes on a 133Mhz Pentium 
   running linux):

     % cd src                              ( if you're not already there )
     % gmake 

   The gmake ultimately issues the message "All of PostgreSQL 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.

4. Install PostgreSQL

   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 PostgreSQL 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 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.

WARNING: PostgreSQL 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.

The program initdb (part of Postgres) is what initializes (creates) a
database system.  Initdb uses the defaults specified in Makefile.global
or Makefile.custom. See the man page for initdb for more information.

  % initdb --pgdata=/usr/local/pgsql/data --pglib=/usr/local/pgsql/lib

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.

Setting up Permissions
----------------------

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.conf in the lib directory.  Initdb creates a sample version of
this file, which contains comments telling you how to set it up.

The Postmaster Daemon
---------------------

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.

So, for example, you can login as the Postgres superuser and issue the
command:

  $ nohup postmaster -D/usr/local/pgsql/data >server.log 2>&1 &

This says to run the postmaster against the database system created
above.

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 POSTGRESQL
------------------

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/pgsql/src/test/regress
     % gmake all runtest

This will run a whole slew of regression tests and might take an hour
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 expected.out regress.out

PLAYING WITH POSTGRESQL
-----------------------

After PostgreSQL is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to 
see PostgreSQL do something.  That's easy.  Invoke the interactive interface
to PostgreSQL, psql, and start typing SQL:

  $ psql template1

(psql has to open a particular database, but at this point the only one
that exists is the template1 database, which always exists.  We will connect
to it only long enough to create another one and switch to it).

The response from psql is:

  type \? for help on slash commands
  type \q to quit
  type \g or terminate with semicolon to execute query
You are currently connected to the database: template1

template1=> 

Create the database foo:

template1=> CREATE DATABASE FOO;
INSERT 773248

(Don't ever forget those SQL semicolons.  Psql won't execute anything until it
sees the semicolon).

template1=> \c foo
closing connection to database: template1
connecting to new database: foo

(\ commands aren't SQL, so no semicolon.  Use \? to see all the \ commands).

template1=> CREATE TABLE bar (column1 int4, column2 char16);
CREATE

template1=> \d bar

...

You get the idea.



QUESTIONS? BUGS? FEEDBACK?
--------------------------

First, please read the Frequently Asked Questions and answers in the file
called FAQ.

If you still have questions, please send them to:
questions@postgreSQL.org

If you have a bug report to make, please send a filled out version of
the file named "bug.template" to bugs@postgreSQL.org.

If you would like to help out with the development and maintenance of
PostgreSQL, send subscribe to the developers mailing list.  See
README.support for more information

----------------------------------------------------------------------

Porting Notes:
-------------
Ultrix4.x:
	You need to install the libdl-1.1 package since Ultrix 4.x doesn't
	have a dynamic loader. It's available in
	   s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z

Linux:
	The linux port defaults to the ELF binary format. (Note that if you're
	using ELF, you don't need dld because you'll be using the dl library
	that comes with Linux ELF instead.)

	To compile on non-ELF Linux, comment out the LINUX_ELF line in
	src/mk/port/postgres.mk.linux. Also, the dld library MUST be obtained
	and installed on the system. It enables dynamic link loading capability
	to the postgres port. The dld library can be obtained from the sunsite
	linux distributions. The current name is dld-3.2.5.
				(Jalon Q. Zimmerman 
				<sneaker@powergrid.electriciti.com> 5/11/95)

	To compile with flex, you need a recent version (2.5.2 or
	later). Otherwise, you will get a 'yy_flush_buffer' undefined error.
        Note, however, that flex v2.5.3 has a bug. See the FAQs.

BSD/OS:
	For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2
	as well as the GNU dld library.  Flex version 2.5.3 has a known bug.

NeXT: 
	The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
	It requires a SysV IPC emulation library and header files for 
        shared libary and semaphore stuff.   Tom just happens to sell such 
        a product so contact him for information.  He has also indicated that
        binary releases of PostgreSQL for NEXTSTEP will be made available to
        the general public.  Contact Info@RnA.nl for information.