head	1.46;
access;
symbols
	REL7_0_PATCHES:1.41.0.2
	REL7_0:1.41
	REL6_5_PATCHES:1.24.0.2
	REL6_5:1.24
	REL6_4:1.12.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.46
date	2000.07.21.00.44.12;	author petere;	state dead;
branches;
next	1.45;

1.45
date	2000.06.05.17.07.53;	author momjian;	state Exp;
branches;
next	1.44;

1.44
date	2000.06.05.10.57.57;	author momjian;	state Exp;
branches;
next	1.43;

1.43
date	2000.06.01.05.58.42;	author momjian;	state Exp;
branches;
next	1.42;

1.42
date	2000.06.01.05.47.06;	author momjian;	state Exp;
branches;
next	1.41;

1.41
date	2000.05.02.20.01.51;	author thomas;	state Exp;
branches
	1.41.2.1;
next	1.40;

1.40
date	2000.04.14.23.04.44;	author tgl;	state Exp;
branches;
next	1.39;

1.39
date	2000.04.07.13.30.58;	author thomas;	state Exp;
branches;
next	1.38;

1.38
date	2000.03.31.15.00.14;	author tgl;	state Exp;
branches;
next	1.37;

1.37
date	2000.03.31.03.27.40;	author thomas;	state Exp;
branches;
next	1.36;

1.36
date	2000.03.28.14.35.13;	author thomas;	state Exp;
branches;
next	1.35;

1.35
date	2000.03.26.07.03.38;	author tgl;	state Exp;
branches;
next	1.34;

1.34
date	2000.03.09.12.00.08;	author petere;	state Exp;
branches;
next	1.33;

1.33
date	2000.01.23.01.27.34;	author petere;	state Exp;
branches;
next	1.32;

1.32
date	2000.01.20.22.21.30;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2000.01.20.21.50.51;	author petere;	state Exp;
branches;
next	1.30;

1.30
date	2000.01.16.20.04.50;	author petere;	state Exp;
branches;
next	1.29;

1.29
date	99.12.07.22.41.40;	author momjian;	state Exp;
branches;
next	1.28;

1.28
date	99.11.23.18.24.55;	author momjian;	state Exp;
branches;
next	1.27;

1.27
date	99.11.23.18.08.07;	author momjian;	state Exp;
branches;
next	1.26;

1.26
date	99.10.12.15.34.19;	author momjian;	state Exp;
branches;
next	1.25;

1.25
date	99.08.16.19.59.24;	author momjian;	state Exp;
branches;
next	1.24;

1.24
date	99.07.12.17.33.36;	author momjian;	state Exp;
branches;
next	1.23;

1.23
date	99.07.10.16.28.01;	author momjian;	state Exp;
branches;
next	1.22;

1.22
date	99.06.09.13.44.57;	author thomas;	state Exp;
branches;
next	1.21;

1.21
date	99.06.08.16.42.55;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	99.06.03.16.13.54;	author thomas;	state Exp;
branches;
next	1.19;

1.19
date	99.05.28.14.24.24;	author momjian;	state Exp;
branches;
next	1.18;

1.18
date	99.05.27.16.29.01;	author momjian;	state Exp;
branches;
next	1.17;

1.17
date	99.05.20.05.39.26;	author thomas;	state Exp;
branches;
next	1.16;

1.16
date	99.04.30.02.04.47;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	99.02.21.03.16.29;	author tgl;	state Exp;
branches;
next	1.14;

1.14
date	98.12.29.02.24.16;	author thomas;	state Exp;
branches;
next	1.13;

1.13
date	98.12.17.16.37.04;	author momjian;	state Exp;
branches;
next	1.12;

1.12
date	98.11.02.15.52.14;	author thomas;	state Exp;
branches
	1.12.2.1;
next	1.11;

1.11
date	98.10.30.19.36.59;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	98.10.27.06.38.13;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	98.10.25.16.59.01;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	98.10.25.00.33.01;	author thomas;	state Exp;
branches;
next	1.7;

1.7
date	98.10.24.22.05.01;	author tgl;	state Exp;
branches;
next	1.6;

1.6
date	98.10.10.03.08.02;	author momjian;	state Exp;
branches;
next	1.5;

1.5
date	98.10.09.21.41.36;	author momjian;	state Exp;
branches;
next	1.4;

1.4
date	98.10.09.19.53.10;	author momjian;	state Exp;
branches;
next	1.3;

1.3
date	98.07.29.06.49.59;	author thomas;	state Exp;
branches;
next	1.2;

1.2
date	98.04.28.14.55.45;	author thomas;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.54;	author thomas;	state Exp;
branches;
next	;

1.12.2.1
date	98.12.17.16.37.35;	author momjian;	state Exp;
branches;
next	;

1.41.2.1
date	2000.06.01.05.14.31;	author momjian;	state Exp;
branches;
next	1.41.2.2;

1.41.2.2
date	2000.06.01.05.58.56;	author momjian;	state Exp;
branches;
next	1.41.2.3;

1.41.2.3
date	2000.06.05.10.59.16;	author momjian;	state Exp;
branches;
next	1.41.2.4;

1.41.2.4
date	2000.06.05.17.02.27;	author momjian;	state Exp;
branches;
next	1.41.2.5;

1.41.2.5
date	2000.11.03.03.42.55;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.46
log
@Update installation instructions to new realities. Combined into one file.
Improved automation of INSTALL file generation.
@
text
@<!--
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.45 2000/06/05 17:07:53 momjian Exp $
-->

 <chapter id="install">
  <title>Installation</title>

  <abstract>
   <para>
    Installation instructions for 
    <productname>PostgreSQL</productname> 7.0.2.
   </para>
  </abstract>

  <para>
   If you haven't gotten the <productname>PostgreSQL</productname> distribution,
   get it from <ulink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ulink>,
   then unpack it:

   <programlisting>
&gt; gunzip postgresql-7.0.2.tar.gz
&gt; tar -xf postgresql-7.0.2.tar
&gt; mv postgresql-7.0.2 /usr/src
   </programlisting>
  </para>

  <sect1>
   <title>Before you start</title>

   <para>
    Building <productname>PostgreSQL</productname> requires <acronym>GNU</acronym>
    <application>make</application>.  It will <emphasis>not</emphasis>
    work with other <application>make</application> programs. On GNU/Linux systems
    GNU make is the default tool, on other systems you may find that
    GNU <application>make</application> is installed under the name
    <literal>gmake</literal>.
    We will use that name from now on to indicate <acronym>GNU</acronym>
    <application>make</application>, no matter what name it has on your system.
    To test for <acronym>GNU</acronym> <application>make</application> enter
    <programlisting>
&gt; <userinput>gmake --version</userinput>
    </programlisting>
    If you need to get <acronym>GNU</acronym>
    <application>make</application>, you can
    find it at <ulink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ulink>.
   </para>

   <para>
    Up to date information on supported platforms is at
    <ulink url="http://www.postgresql.org/docs/admin/ports.htm">
     http://www.postgresql.org/docs/admin/ports.htm</ulink>.
    In general, most Unix-compatible platforms with modern libraries
    should be able to run
    <productname>PostgreSQL</productname>. In the
    <filename>doc</filename> subdirectory
    of the distribution are several platform-specific FAQ and README documents you
    might wish to consult if you are having trouble.
   </para>

   <para>
    Although the minimum required memory for running
    <productname>PostgreSQL</productname> 
    can be as little as 8MB, there are noticeable speed improvements
    when expanding memory
    up to 96MB or beyond. The rule is you can never have too much memory.
   </para>
   <para>
    Check that you have sufficient disk space.  You will need about
    30 Mbytes for the source tree during compilation and about 5 Mbytes for
    the installation directory. An empty database takes about 1 Mbyte, otherwise
    they take about five times the amount of space that a flat text file with the
    same data would take. If you run the regression tests you will temporarily need
    an extra 20MB.
   </para>

   <para>
    To check for disk space, use 
<programlisting>
&gt; df -k
</programlisting>
   </para>

   <para>
    Considering today's prices for hard disks, getting a large and
    fast hard disk should
    probably be in your plans before putting a database into production use.
   </para>
  </sect1>

  <sect1>
   <title>Installation Procedure</title>

   <procedure>
    <title><productname>PostgreSQL</productname> Installation</title>

    <para>
     For a fresh install or upgrading from previous releases of
     <productname>PostgreSQL</productname>:
    </para>

    <step performance="optional">
     <para>
      Create the <productname>PostgreSQL</productname> superuser account.
      This is the user the server will run as. For production use you
      should create a separate, unprivileged account
      (<literal>postgres</literal> is commonly used).
      If you do not have root access or just want to play around,
      your own user account is enough.
     </para>
     <para>
      Running <productname>PostgreSQL</productname> as
      <literal>root</literal>, <literal>bin</literal>,
      or any other account with special access rights is a security risk;
      <emphasis>don't do it</emphasis>.  The postmaster will in fact refuse
      to start as <literal>root</literal>.
     </para>
     <para>
      You need not do the building and installation itself under this account
      (although you can). You will be told when you need to login as the
      database superuser.
     </para>
    </step>

    <step performance="required">
     <para>
      Configure the source code for your system.  It is this step at which
      you can specify your actual installation path for the build process
      and make choices about what gets installed. Change into the
      <filename>src</filename>
      subdirectory and type:
      <programlisting>
&gt; ./configure
      </programlisting>
      followed by any options you might want to give it. For a first installation
      you should be able to do fine without any.
      For a complete list of options, type:
      <programlisting>
&gt; ./configure --help
      </programlisting>
      Some of the more commonly used ones are:
      <variablelist>
       <varlistentry>
	<term>--prefix=BASEDIR</term>
	<listitem>
	 <para>
	  Selects a different base directory for the installation of
	  <productname>PostgreSQL</productname>. The default is
	  <filename>/usr/local/pgsql</filename>. 
	 </para>
	</listitem>
       </varlistentry>

       <varlistentry>
	<term>--enable-locale</term>
	<listitem>
	 <para>
	  If you want to use locales.
	 </para>
	</listitem>
       </varlistentry>

       <varlistentry>
	<term>--enable-multibyte</term>
	<listitem>
	 <para>
	  Allows the use of multibyte character encodings. This is primarily for
	  languages like Japanese, Korean, or Chinese.
	 </para>
	</listitem>
       </varlistentry>

       <varlistentry>
	<term>--with-perl</term>
	<listitem>
	 <para>
	  Builds the Perl interface and plperl extension language.
	  Please note that the Perl interface needs to be
	  installed into the usual place for Perl modules (typically under
	  <filename>/usr/lib/perl</filename>), so you must have root access
	  to perform the installation step.  (It is often easiest to leave out
	  <option>--with-perl</option> initially, and then build and install the
	  Perl interface after completing the installation of PostgreSQL
	  itself.)
	 </para>
	</listitem>
       </varlistentry>

       <varlistentry>
	<term>--with-odbc</term>
	<listitem>
	 <para>
	  Builds the ODBC driver package.
	 </para>
	</listitem>
       </varlistentry>

       <varlistentry>
	<term>--with-tcl</term>
	<listitem>
	 <para>
	  Builds interface libraries and programs requiring
	  Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
	 </para>
	</listitem>
       </varlistentry>
      </variablelist>

     </para>
    </step>

    <step performance="required">
     <para>
      Compile the program.  Type
      <programlisting>
&gt; gmake
      </programlisting>
      The compilation process can take anywhere from 10 minutes to an hour.
      Your mileage will most certainly vary. Remember to use GNU make.
     </para>

     <para>
      The last line displayed will hopefully be 
      <programlisting>
All of PostgreSQL is successfully made. Ready to install.
      </programlisting>
     </para>
    </step>

    <step performance="optional">
     <para>
      If you want to test the newly built server before you install it,
      you can run the regression tests at this point.  The regression tests
      are a test suite to verify that <productname>PostgreSQL</productname>
      runs on your machine in the way the developers expected it to.
      For detailed instructions see <xref endterm="regress-title"
       linkend="regress">.
      (Be sure to use the "parallel regress test" method, since the sequential
      method only works with an already-installed server.)
     </para>
    </step>

    <step performance="required">
     <para>
      If you are not upgrading an existing system, skip to 
      <xref linkend="continue">.
     </para>
     <para>
     If you are running 7.*, skip to step
     <xref linkend="nodump">.
      </para>
     <para>
      You now need to back up your existing database.
      To dump your database installation, type:
      <programlisting>
&gt; pg_dumpall > db.out
      </programlisting>
      If you wish to preserve object id's (oids), then use the -o
      option when running <application>pg_dumpall</application>.  
      However, unless you have a
      special reason for doing this (such as using OIDs as keys
      in tables), don't do it.
     </para>

     <para>
      Make sure to use the <application>pg_dumpall</application>
      command from the version you are currently running.
      7.0.2's <application>pg_dumpall</application> should not
      be used on older databases.
     </para>

     <caution>
      <para>
       You must make sure that your database is not updated in the middle of
       your backup.  If necessary, bring down postmaster, edit the permissions
       in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
       to allow only you on, then
       bring <application>postmaster</application> back up.
      </para>
     </caution>
     <para>
     Rather than using <application>pg_dumpall</application>,
     <application>pg_upgrade</application> can often be used.
     </para>
    </step>

    <step performance="required" id="nodump">
     <para>
      If you are upgrading an existing system, kill the database
      server now. Type
      <programlisting>
&gt; ps ax | grep postmaster
      </programlisting>
      or
      <programlisting>
&gt; ps -e | grep postmaster
      </programlisting>
      (It depends on your system which one of these two works. No harm can be done
      by typing the wrong one.)
      This should list the process numbers for a number of processes, similar
      to this:
      <programlisting>
  263  ?  SW   0:00 (postmaster)
  777  p1 S    0:00 grep postmaster
      </programlisting>
      Type the following line, with <replaceable>pid</replaceable>
      replaced by the process id for process <literal>postmaster</literal>
      (263 in the above case). (Do not use the id for the process
      "grep postmaster".) 
      <programlisting>
&gt; kill <replaceable>pid</replaceable>
      </programlisting>
     </para>

     <tip>
      <para>
       On systems which have <productname>PostgreSQL</productname>
       started at boot time, there
       is probably a startup file that will accomplish the same
       thing. For example, on a
       Redhat Linux system one might find that
       <programlisting>
&gt; /etc/rc.d/init.d/postgres.init stop
       </programlisting>
       works.
      </para>
     </tip>

     <para>
      If you used pg_dumpall, move the old directory out of the way.
      Type the following:      
<programlisting>
&gt; mv /usr/local/pgsql /usr/local/pgsql.old
      </programlisting>
      (substitute your particular paths).
     </para>

    </step>

    <step performance="required" id="continue">
     <para>
      Install the <productname>PostgreSQL</productname> executable files and
      libraries.  Type
      <programlisting>
&gt; gmake install
      </programlisting>
     </para>
     <para>
      You should do this step as the user that you want the installed executables
      to be owned by.  This does not have to be the same as the database superuser;
      some people prefer to have the installed files be owned by root.
     </para>
    </step>

    <step performance="required">
     <para>
      If necessary, tell your system how to find the new shared libraries.
      How to do this varies between platforms. The most widely usable method
      is to set the environment variable
      <envar>LD_LIBRARY_PATH</envar>:
      <programlisting>
&gt; LD_LIBRARY_PATH=/usr/local/pgsql/lib
&gt; export LD_LIBRARY_PATH
      </programlisting>
      on sh, ksh, bash, zsh or
      <programlisting>
&gt; setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
      </programlisting>
      on csh or tcsh.
      You might want to put this into a shell startup file such as
      <filename>/etc/profile</filename>.
     </para>

     <para>
      On some systems the following is the preferred method, but you must have root
      access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
      <programlisting>
<filename>/usr/local/pgsql/lib</filename>
      </programlisting>
      Then run command <command>/sbin/ldconfig</command>.
     </para>

     <para>
      If in doubt, refer to the manual pages of your system. If you later on get
      a message like
      <programlisting>
psql: error in loading shared libraries
libpq.so.2.1: cannot open shared object file: No such file or directory
      </programlisting>
      then the above was necessary.  Simply do this step then.
     </para>
    </step>

    <step performance="required">
     <para>
      If you moved the old directory out of the way, 
      create the database installation (the working data files).
      To do this you must log in to your
      <productname>PostgreSQL</productname> superuser account. It will not
      work as root.
      <programlisting>
&gt; mkdir /usr/local/pgsql/data
&gt; chown postgres /usr/local/pgsql/data
&gt; su - postgres
&gt; /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
      </programlisting>
     </para>
     <para>
      The <option>-D</option> option specifies the location where the data will be
      stored. You can use any path you want, it does not have to be under
      the installation directory. Just make sure that the superuser account
      can write to the directory (or create it, if it doesn't already exist)
      before starting <command>initdb</command>.
      (If you have already been doing the installation up to now as the
      <productname>PostgreSQL</productname>
      superuser, you may have to log in as root temporarily to create the data
      directory underneath a root-owned directory.)
     </para>
    </step>

    <step performance="required">
     <para>
      The previous step should have told you how to start up the database server.
      Do so now.  The command should look something like
      <programlisting>
&gt; /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
      </programlisting>
      This will start the server in the foreground. To make it detach to
      the background, you can use the <option>-S</option> option, but then you won't
      see any log messages the server produces.  A better way to put the server
      in the background is
      <programlisting>
&gt; nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
    &lt;/dev/null &gt;>server.log 2&gt;>1 &amp;
      </programlisting>
     </para>
    </step>

    <step performance="optional">
     <para>
      If you did a pg_dumpall, reload your data back in:
      <programlisting>
&gt; /usr/local/pgsql/bin/psql -d template1 -f db.out
      </programlisting>
      You also might want to copy over the old <filename>pg_hba.conf</filename>
      file and any other files you might have had set up for authentication, such
      as password files.
     </para>
    </step>
   </procedure>

   <para>
    This concludes the installation proper. To make your life more
    productive and enjoyable
    you should look at the following optional steps and suggestions:
   </para>

   <itemizedlist>
    <listitem>
     <para>
      Life will be more convenient if you set up some environment
      variables. First of all
      you probably want to include
      <filename>/usr/local/pgsql/bin</filename> (or equivalent)
      into your <envar>PATH</envar>. To do this, add the following to
      your shell startup
      file, such as <filename>~/.bash_profile</filename> (or
      <filename>/etc/profile</filename>, 
      if you want it to affect every user):
      <programlisting>
&gt; PATH=$PATH:/usr/local/pgsql/bin
      </programlisting>
     </para>
     <para>
      Furthermore, if you set <envar>PGDATA</envar> in the environment
      of the PostgreSQL
      superuser, you can omit the <option>-D</option> for
      <filename>postmaster</filename> 
      and <filename>initdb</filename>.
     </para>
    </listitem>

    <listitem>
     <para>
      You probably want to install the <application>man</application> and
      <acronym>HTML</acronym> documentation. Type
      <programlisting>
&gt; cd /usr/src/pgsql/postgresql-7.0.2/doc
&gt; gmake install
      </programlisting>
      This will install files under <filename>/usr/local/pgsql/doc</filename>
      and <filename>/usr/local/pgsql/man</filename>. To enable your system
      to find the <application>man</application> documentation, you need to
      add a line like the following to a shell startup file:
      <programlisting>
&gt; MANPATH=$MANPATH:/usr/local/pgsql/man
      </programlisting>
     </para>

     <para>
      The documentation is also available in Postscript format. 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>
&gt; cd /usr/local/pgsql/doc
&gt; gunzip -c user.ps.tz | lpr
      </programlisting>
      Here is how you might do it if you have Ghostscript on your system and are
      writing to a laserjet printer.
      <programlisting>
&gt; gunzip -c user.ps.gz \
    | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- \
    | lpr
      </programlisting>
      Printer setups can vary wildly from system to system.
      If in doubt, consult your manuals or your local expert.
     </para>

     <para>
      The Adminstrator's Guide should probably be your first reading if you
      are completely new to <productname>PostgreSQL</productname>, as it contains
      information about how to set up database users and authentication.
     </para>
    </listitem>

    <listitem>
     <para>
      Usually, you will want to modify your computer so that it will automatically
      start the database server whenever it boots.
      This is not required; the <productname>PostgreSQL</productname> server can
      be run successfully from non-privileged accounts without root intervention.
     </para>
     <para>
      Different systems have different conventions for starting up
      daemons at boot time,
      so you are advised to familiarize yourself with them.
      Most systems have a file <filename>/etc/rc.local</filename> or
      <filename>/etc/rc.d/rc.local</filename> which is almost
      certainly no bad place
      to put such a command.
      Whatever you do, postmaster must be run by the
      <productname>PostgreSQL</productname> 
      superuser (<literal>postgres</literal>) <emphasis>and not by
       root</emphasis> or
      any other user. Therefore you probably always want to form your command lines
      along the lines of <literal>su -c '...' postgres</literal>.
     </para>
     <para>
      It might be advisable to keep a log of the server output. To
      start the server that way
      try:
      <programlisting>
&gt; nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
      </programlisting>
     </para>

     <para>
      Here are a few more operating system specific suggestions.

      <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:
	 <programlisting>
&gt; su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
	 </programlisting>
	</para>
       </listitem>

       <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
	 root:bin.

	 <programlisting>
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
    su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
        -D/usr/local/pgsql/data
        -S -o -F > /usr/local/pgsql/errlog' &
    echo -n ' pgsql'
}
	 </programlisting>

	 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
	 expression unfinished.  The exec saves one layer of shell under
	 the postmaster process so the parent is init.
	</para>
       </listitem>

       <listitem>
	<para>
	 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>.
	</para>
       </listitem>

      </itemizedlist>

     </para>
    </listitem>

    <listitem>
     <para>
      Run the regression tests against the installed server (using the sequential
      test method).  If you didn't run the tests before installation, you should
      definitely do it now.
      For detailed instructions see
      <xref endterm="regress-title" linkend="regress">.
     </para>
    </listitem>

   </itemizedlist>

   <para>
    To start experimenting with <productname>Postgres</productname>,
    set up the paths as explained above
    and start the server. To create a database, type

    <programlisting>
&gt; createdb testdb
    </programlisting>

    Then enter

    <programlisting>
&gt; psql testdb
    </programlisting>

    to connect to that database. At the prompt you can enter SQL commands
    and start experimenting.
   </para>

  </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
@


1.45
log
@Update for 7.0.2.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41.2.3 2000/06/05 10:59:16 momjian Exp $
@


1.44
log
@Update for 7.0.2.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41.2.2 2000/06/01 05:58:56 momjian Exp $
d329 1
a329 1
      If you used pg_dumpall, move the old directories out of the way.
d395 2
a396 1
      Create the database installation (the working data files).
@


1.43
log
@Mention pg_upgrade
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.42 2000/06/01 05:47:06 momjian Exp $
d11 1
a11 1
    <productname>PostgreSQL</productname> 7.0.1.
d21 3
a23 3
&gt; gunzip postgresql-7.0.1.tar.gz
&gt; tar -xf postgresql-7.0.1.tar
&gt; mv postgresql-7.0.1 /usr/src
d244 1
a244 1
      If you are not upgrading an existing system then skip to 
d248 1
a248 1
     If you are running 7.0 or later, skip to
d253 1
a253 1
      To dump your fairly recent post-6.0 database installation, type
d267 2
a268 12
      7.0.1's <application>pg_dumpall</application> will not work on older databases.
      However, if you are still using 6.0, do not use the
      <application>pg_dumpall</application> script from 6.0 or everything will be
      owned by the <productname>PostgreSQL</productname> superuser after you
      reload. In that case
      you should grab <application>pg_dumpall</application> from a later
      6.x.x release.
      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, restore your database,
      then back it up again.
d288 1
a288 1
      If you are upgrading an existing system then kill the database
d453 1
a453 1
    you should look at the following optional steps and suggestions.
d486 1
a486 1
&gt; cd /usr/src/pgsql/postgresql-7.0.1/doc
@


1.42
log
@Update 7.0.1
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41.2.1 2000/06/01 05:14:31 momjian Exp $
d247 4
a250 1

d290 4
d296 1
a296 1
    <step performance="required">
@


1.41
log
@Fixups in content and markup for 7.0 release.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.40 2000/04/14 23:04:44 tgl Exp $
d11 1
a11 1
    <productname>PostgreSQL</productname> 7.0.
d21 3
a23 3
&gt; gunzip postgresql-7.0.tar.gz
&gt; tar -xf postgresql-7.0.tar
&gt; mv postgresql-7.0 /usr/src
d264 1
a264 1
      7.0's <application>pg_dumpall</application> will not work on older databases.
d332 3
a334 2
      Also move the old directories  out of the way. Type the following:
      <programlisting>
d442 1
a442 1
      If you are upgrading from an existing installation, dump your data back in:
d489 1
a489 1
&gt; cd /usr/src/pgsql/postgresql-7.0/doc
@


1.41.2.1
log
@Fixups for 7.0.1
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41 2000/05/02 20:01:51 thomas Exp $
d11 1
a11 1
    <productname>PostgreSQL</productname> 7.0.1.
d21 3
a23 3
&gt; gunzip postgresql-7.0.1.tar.gz
&gt; tar -xf postgresql-7.0.1.tar
&gt; mv postgresql-7.0.1 /usr/src
d264 1
a264 1
      7.0.1's <application>pg_dumpall</application> will not work on older databases.
d332 2
a333 3
      If you used pg_dumpall, move the old directories out of the way.
      Type the following:      
<programlisting>
d441 1
a441 1
      If you did a pg_dumpall, reload your data back in:
d488 1
a488 1
&gt; cd /usr/src/pgsql/postgresql-7.0.1/doc
@


1.41.2.2
log
@Mention pg_upgrade
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.42 2000/06/01 05:47:06 momjian Exp $
d247 1
a247 4
     <para>
     If you are running 7.0 or later, skip to
     <xref linkend="nodump">.
      </para>
a286 4
     <para>
     Rather than using <application>pg_dumpall</application>,
     <application>pg_upgrade</application> can often be used.
     </para>
d289 1
a289 1
    <step performance="required" id="nodump">
@


1.41.2.3
log
@Update for 7.0.2.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41.2.2 2000/06/01 05:58:56 momjian Exp $
d11 1
a11 1
    <productname>PostgreSQL</productname> 7.0.2.
d21 3
a23 3
&gt; gunzip postgresql-7.0.2.tar.gz
&gt; tar -xf postgresql-7.0.2.tar
&gt; mv postgresql-7.0.2 /usr/src
d244 1
a244 1
      If you are not upgrading an existing system, skip to 
d248 1
a248 1
     If you are running 7.*, skip to step
d253 1
a253 1
      To dump your database installation, type:
d267 12
a278 2
      7.0.2's <application>pg_dumpall</application> should not
      be used on older databases.
d298 1
a298 1
      If you are upgrading an existing system, kill the database
d463 1
a463 1
    you should look at the following optional steps and suggestions:
d496 1
a496 1
&gt; cd /usr/src/pgsql/postgresql-7.0.2/doc
@


1.41.2.4
log
@Update install for upgraders.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.41.2.3 2000/06/05 10:59:16 momjian Exp $
d329 1
a329 1
      If you used pg_dumpall, move the old directory out of the way.
d395 1
a395 2
      If you moved the old directory out of the way, 
      create the database installation (the working data files).
@


1.41.2.5
log
@Brand 7.0.3.
@
text
@d2 1
a2 1
$Header: /home/projects/pgsql/cvsroot/pgsql/doc/src/sgml/Attic/install.sgml,v 1.41.2.4 2000/06/05 17:02:27 momjian Exp $
d11 1
a11 1
    <productname>PostgreSQL</productname> 7.0.3.
d21 3
a23 3
&gt; gunzip postgresql-7.0.3.tar.gz
&gt; tar -xf postgresql-7.0.3.tar
&gt; mv postgresql-7.0.3 /usr/src
d267 1
a267 1
      7.0.3's <application>pg_dumpall</application> should not
d487 1
a487 1
&gt; cd /usr/src/pgsql/postgresql-7.0.3/doc
@


1.40
log
@Fix busted markup.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.39 2000/04/07 13:30:58 thomas Exp $
d36 1
a36 1
    <quote>gmake</quote>.
d615 2
a616 2
      For detailed instructions see <xref endterm="regress-title"
       linkend="regress">.
d623 2
a624 1
    To start <quote>playing around</quote>, set up the paths as explained above
d626 1
d630 1
d632 1
d636 1
@


1.39
log
@Fix path to initdb in installation instructions.
General cleanup for 7.0.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.38 2000/03/31 15:00:14 tgl Exp $
d106 2
a107 2
      (<literal>postgres</literal> is
      commonly used). If you do not have root access or just want to play around,
d112 1
a112 1
      <literal>tera</literal>teral>, <literal>bin</literal>,
d115 1
a115 1
      to start as root.
@


1.38
log
@Minor copy-editing.
@
text
@d2 1
a2 1
$Header: /usr/local/cvsroot/pgsql/doc/src/sgml/install.sgml,v 1.37 2000/03/31 03:27:40 thomas Exp $
d5 2
a6 2
 <Chapter Id="install">
  <Title>Installation</Title>
d8 2
a9 2
  <Abstract>
   <Para>
d11 7
a17 7
    <ProductName>PostgreSQL</ProductName> 7.0.
   </Para>
  </Abstract>

  <Para>
   If you haven't gotten the <ProductName>PostgreSQL</ProductName> distribution,
   get it from <ULink url="ftp://ftp.postgresql.org">ftp.postgresql.org</ULink>,
d19 15
a33 14
   <ProgramListing>
gunzip postgresql-7.0.tar.gz
tar -xf postgresql-7.0.tar
mv postgresql-7.0 /usr/src
   </ProgramListing>
  </Para>

  <Sect1>
   <Title>Before you start</Title>

   <Para>
    Building <Productname>PostgreSQL</Productname> requires <acronym>GNU</acronym>
    <Application>make</Application>.  It will <Emphasis>not</Emphasis>
    work with other <Application>make</Application> programs. On GNU/Linux systems
d35 2
a36 1
    GNU <Application>make</Application> is installed under the name <Quote>gmake</Quote>.
d38 2
a39 2
    <Application>make</Application>, no matter what name it has on your system.
    To test for <acronym>GNU</acronym> <Application>make</Application> enter
d41 1
a41 1
<userinput>gmake --version</userinput>
d43 4
a46 3
    If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can
    find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>.
   </Para>
d48 1
a48 1
   <Para>
d52 4
a55 2
    In general, most Unix-compatible platforms with modern libraries should be able to run
    <ProductName>PostgreSQL</ProductName>. In the <filename>doc</filename> subdirectory
d61 4
a64 2
    Although the minimum required memory for running <ProductName>PostgreSQL</ProductName>
    can be as little as 8MB, there are noticeable speed improvements when expanding memory
d67 1
a67 1
   <Para>
d74 1
a74 1
   </Para>
d76 1
a76 1
   <Para>
d79 1
a79 1
df -k
d84 2
a85 1
    Considering today's prices for hard disks, getting a large and fast hard disk should
d88 1
a88 69
  </Sect1>

<Sect1>
<Title>Installation Procedure</Title>

<Procedure>
<Title><ProductName>PostgreSQL</ProductName> Installation</Title>

<Para>
For a fresh install or upgrading from previous releases of
<ProductName>PostgreSQL</ProductName>:
</Para>

<Step Performance="optional">
<Para>
Create the <ProductName>PostgreSQL</ProductName> superuser account.
This is the user the server will run as. For production use you
should create a separate, unprivileged account (<literal>postgres</literal> is
commonly used). If you do not have root access or just want to play around,
your own user account is enough.
</para>
<para>
Running <ProductName>PostgreSQL</ProductName> as <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights is a security risk;
<emphasis>don't do it</emphasis>.  The postmaster will in fact refuse
to start as root.
</para>
<Para>
You need not do the building and installation itself under this account
(although you can). You will be told when you need to login as the
database superuser.
</Para>
</Step>

<Step Performance="required">
<Para>
Configure the source code for your system.  It is this step at which
you can specify your actual installation path for the build process
and make choices about what gets installed. Change into the <filename>src</filename>
subdirectory and type:
<ProgramListing>
./configure
</ProgramListing>
followed by any options you might want to give it. For a first installation
you should be able to do fine without any.
For a complete list of options, type:
<ProgramListing>
./configure --help
</ProgramListing>
     Some of the more commonly used ones are:
<VariableList>
 <varlistentry>
  <term>--prefix=BASEDIR</term>
  <listitem>
   <para>
    Selects a different base directory for the installation of
    <ProductName>PostgreSQL</ProductName>. The default is <filename>/usr/local/pgsql</filename>.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term>--enable-locale</term>
  <listitem>
   <para>
    If you want to use locales.
   </para>
  </listitem>
 </varlistentry>
d90 2
a91 25
 <varlistentry>
  <term>--enable-multibyte</term>
  <listitem>
   <para>
    Allows the use of multibyte character encodings. This is primarily for
    languages like Japanese, Korean, or Chinese.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term>--with-perl</term>
  <listitem>
   <para>
    Builds the Perl interface and plperl extension language.
    Please note that the Perl interface needs to be
    installed into the usual place for Perl modules (typically under
    <filename>/usr/lib/perl</filename>), so you must have root access
    to perform the installation step.  (It is often easiest to leave out
    <option>--with-perl</option> initially, and then build and install the
    Perl interface after completing the installation of PostgreSQL
    itself.)
   </para>
  </listitem>
 </varlistentry>
d93 2
a94 32
 <varlistentry>
  <term>--with-odbc</term>
  <listitem>
   <para>
    Builds the ODBC driver package.
   </para>
  </listitem>
 </varlistentry>

 <varlistentry>
  <term>--with-tcl</term>
  <listitem>
   <para>
    Builds interface libraries and programs requiring
    Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
   </para>
  </listitem>
 </varlistentry>
</VariableList>

</Para>
</step>

<Step Performance="required">
<Para>
Compile the program.  Type
<ProgramListing>
gmake
</ProgramListing>
The compilation process can take anywhere from 10 minutes to an hour.
Your mileage will most certainly vary. Remember to use GNU make.
</Para>
d96 128
a223 3
<Para>
The last line displayed will hopefully be 
<programlisting>
d225 80
a304 77
</programlisting>
</Para>
</Step>

<Step Performance="optional">
<Para>
If you want to test the newly built server before you install it,
you can run the regression tests at this point.  The regression tests
are a test suite to verify that <ProductName>PostgreSQL</ProductName>
runs on your machine in the way the developers expected it to.
For detailed instructions see <xref linkend="regress" endterm="regress-title">.
(Be sure to use the "parallel regress test" method, since the sequential
method only works with an already-installed server.)
</Para>
</Step>

<Step Performance="required">
<Para>
If you are not upgrading an existing system then skip to 
<xref linkend="continue">.
</Para>

<Para>
You now need to back up your existing database.
To dump your fairly recent post-6.0 database installation, type
<programlisting>
pg_dumpall > db.out
</programlisting>
If you wish to preserve object id's (oids), then use the -o
option when running <application>pg_dumpall</application>.  
However, unless you have a
special reason for doing this (such as using OIDs as keys
in tables), don't do it.
</Para>

<Para>
Make sure to use the <application>pg_dumpall</application>
command from the version you are currently running.
7.0's <application>pg_dumpall</application> will not work on older databases.
However, if you are still using 6.0, do not use the
<application>pg_dumpall</application> script from 6.0 or everything will be
owned by the <ProductName>PostgreSQL</ProductName> superuser after you
reload. In that case
you should grab <application>pg_dumpall</application> from a later
6.x.x release.
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, restore your database,
then back it up again.
</Para>

<caution>
<Para>
     You must make sure that your database is not updated in the middle of
     your backup.  If necessary, bring down postmaster, edit the permissions
     in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
 to allow only you on, then
     bring <application>postmaster</application> back up.
</Para>
</caution>
</Step>

<Step Performance="required">
<Para>
If you are upgrading an existing system then kill the database server now. Type
<ProgramListing>
ps ax | grep postmaster
</ProgramListing>
or
<ProgramListing>
ps -e | grep postmaster
</ProgramListing>
(It depends on your system which one of these two works. No harm can be done
by typing the wrong one.)
This should list the process numbers for a number of processes, similar
to this:
<ProgramListing>
d307 81
a387 78
</ProgramListing>
Type the following line, with <replaceable>pid</replaceable>
replaced by the process id for process <literal>postmaster</literal>
(263 in the above case). (Do not use the id for the process "grep postmaster".)
<programlisting>
kill <replaceable>pid</replaceable>
</programlisting>
</Para>

<tip>
<para>
On systems which have <productname>PostgreSQL</productname> started at boot time, there
is probably a startup file that will accomplish the same thing. For example, on a
Redhat Linux system one might find that
<programlisting>
/etc/rc.d/init.d/postgres.init stop
</programlisting>
works.
</para>
</tip>

<Para>
Also move the old directories  out of the way. Type the following:
<programlisting>
mv /usr/local/pgsql /usr/local/pgsql.old
</programlisting>
(substitute your particular paths).
</Para>

</Step>

<Step Performance="required" id="continue">
<Para>
Install the <ProductName>PostgreSQL</ProductName> executable files and
libraries.  Type
<ProgramListing>
gmake install
</ProgramListing>
</Para>
<Para>
You should do this step as the user that you want the installed executables
to be owned by.  This does not have to be the same as the database superuser;
some people prefer to have the installed files be owned by root.
</Para>
</Step>

<Step Performance="required">
<Para>
If necessary, tell your system how to find the new shared libraries.
How to do this varies between platforms. The most widely usable method
is to set the environment variable
<envar>LD_LIBRARY_PATH</envar>:
<programlisting>
LD_LIBRARY_PATH=/usr/local/pgsql/lib
export LD_LIBRARY_PATH
</programlisting>
on sh, ksh, bash, zsh or
<programlisting>
setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</programlisting>
on csh or tcsh.
You might want to put this into a shell startup file such as
<filename>/etc/profile</filename>.
</Para>

<Para>
On some systems the following is the preferred method, but you must have root
access. Edit file <filename>/etc/ld.so.conf</filename> to add a line
<programlisting>
<FileName>/usr/local/pgsql/lib</FileName>
</programlisting>
Then run command <Command>/sbin/ldconfig</Command>.
</Para>

<Para>
If in doubt, refer to the manual pages of your system. If you later on get
a message like
<programlisting>
d390 44
a433 43
</programlisting>
then the above was necessary.  Simply do this step then.
</Para>
</Step>

<Step Performance="required">
<Para>
Create the database installation (the working data files).
To do this you must log in to your
<ProductName>PostgreSQL</ProductName> superuser account. It will not
work as root.
<ProgramListing>
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
/usr/local/pgsql/initdb -D /usr/local/pgsql/data
</ProgramListing>
</Para>
<Para>
The <option>-D</option> option specifies the location where the data will be
stored. You can use any path you want, it does not have to be under
the installation directory. Just make sure that the superuser account
can write to the directory (or create it, if it doesn't already exist)
before starting <command>initdb</command>.
(If you have already been doing the installation up to now as the <productname>PostgreSQL</productname>
superuser, you may have to log in as root temporarily to create the data
directory underneath a root-owned directory.)
</Para>
</Step>

<Step Performance="required">
<Para>
The previous step should have told you how to start up the database server.
Do so now.  The command should look something like
<programlisting>
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
</programlisting>
This will start the server in the foreground. To make it detach to
the background, you can use the <option>-S</option> option, but then you won't
see any log messages the server produces.  A better way to put the server
in the background is
<programlisting>
nohup /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data \
d435 16
a450 3
</programlisting>
</Para>
</Step>
d452 5
a456 118
<Step Performance="optional">
<para>
If you are upgrading from an existing installation, dump your data back in:
<programlisting>
/usr/local/pgsql/bin/psql -d template1 -f db.out
</programlisting>
You also might want to copy over the old <filename>pg_hba.conf</filename>
file and any other files you might have had set up for authentication, such
as password files.
</Para>
</Step>
</Procedure>

<para>
This concludes the installation proper. To make your life more productive and enjoyable
you should look at the following optional steps and suggestions.
</para>

<itemizedlist>
<listitem>
<Para>
Life will be more convenient if you set up some environment variables. First of all
you probably want to include <filename>/usr/local/pgsql/bin</filename> (or equivalent)
into your <envar>PATH</envar>. To do this, add the following to your shell startup
file, such as <filename>~/.bash_profile</filename> (or <filename>/etc/profile</filename>,
if you want it to affect every user):
<programlisting>
PATH=$PATH:/usr/local/pgsql/bin
</programlisting>
</Para>
<Para>
Furthermore, if you set <envar>PGDATA</envar> in the environment of the PostgreSQL
superuser, you can omit the <option>-D</option> for <filename>postmaster</filename>
and <filename>initdb</filename>.
</Para>
</listitem>

<listitem>
<Para>
You probably want to install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type
<ProgramListing>
cd /usr/src/pgsql/postgresql-7.0/doc
gmake install
</ProgramListing>
This will install files under <filename>/usr/local/pgsql/doc</filename>
and <filename>/usr/local/pgsql/man</filename>. To enable your system
to find the <application>man</application> documentation, you need to
add a line like the following to a shell startup file:
<ProgramListing>
MANPATH=$MANPATH:/usr/local/pgsql/man
</ProgramListing>
</para>

<para>
The documentation is also available in Postscript format. 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 -c user.ps.tz | lpr
</programlisting>
Here is how you might do it if you have Ghostscript on your system and are
writing to a laserjet printer.
<programlisting>
gunzip -c user.ps.gz | gs -sDEVICE=laserjet -r300 -q -dNOPAUSE -sOutputFile=- | lpr
</programlisting>
Printer setups can vary wildly from system to system.
If in doubt, consult your manuals or your local expert.
</para>

<para>
The Adminstrator's Guide should probably be your first reading if you
are completely new to <productname>PostgreSQL</productname>, as it contains
information about how to set up database users and authentication.
</para>
</listitem>

<listitem>
<Para>
Usually, you will want to modify your computer so that it will automatically
start the database server whenever it boots.
This is not required; the <ProductName>PostgreSQL</ProductName> server can
be run successfully from non-privileged accounts without root intervention.
</para>
<para>
Different systems have different conventions for starting up daemons at boot time,
so you are advised to familiarize yourself with them.
Most systems have a file <filename>/etc/rc.local</filename> or
<filename>/etc/rc.d/rc.local</filename> which is almost certainly no bad place
to put such a command.
Whatever you do, postmaster must be run by the <ProductName>PostgreSQL</ProductName>
superuser (<literal>postgres</literal>) <emphasis>and not by root</emphasis> or
any other user. Therefore you probably always want to form your command lines
along the lines of <literal>su -c '...' postgres</literal>.
</para>
<para>
It might be advisable to keep a log of the server output. To start the server that way
try:
<ProgramListing>
nohup su -c 'postmaster -D /usr/local/pgsql/data > server.log 2>&1' postgres &
</ProgramListing>
</para>

<para>
Here are a few more operating system specific suggestions.

<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:
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
</para>
</listitem>
d458 119
a576 5
<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
          root:bin.
d578 1
a578 1
<programlisting>
d586 33
a618 1
</programlisting>
d620 1
a620 45
          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
          expression unfinished.  The exec saves one layer of shell under
          the postmaster process so the parent is init.
</para>
</listitem>

<listitem>
<para>
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>.
</para>
</listitem>

</itemizedlist>

</Para>
</listitem>

<listitem>
<Para>
Run the regression tests against the installed server (using the sequential
test method).  If you didn't run the tests before installation, you should
definitely do it now.
For detailed instructions see <xref linkend="regress" endterm="regress-title">.
</Para>
</listitem>

</itemizedlist>

<Para>
To start <quote>playing around</quote>, set up the paths as explained above
and start the server. To create a database, type
<ProgramListing>
createdb testdb
</ProgramListing>
Then enter
<ProgramListing>
psql testdb
</ProgramListing>
to connect to that database. At the prompt you can enter SQL commands
and start experimenting.
</Para>
d622 13
a634 1
</Sect1>
d636 2
a637 1
</Chapter>
@


1.37
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d2 1
a2 1
$Header$
d57 1
a57 1
    can be as little as 8MB, there are noticable speed improvements when expanding memory
d304 1
a304 1
is probably a startup file which will accomplish the same thing. For example, on a
@


1.36
log
@Add mention of join syntax to release notes, and reformat a few lines.
Update porting info. Still need a lot of platforms tested.
Fix small errors in markup.
@
text
@d1 4
d19 1
a19 1
<ProgramListing>
d23 1
a23 1
</ProgramListing>
d29 10
a38 10
  <Para>
   Building <Productname>PostgreSQL</Productname> requires <acronym>GNU</acronym>
   <Application>make</Application>.  It will <Emphasis>not</Emphasis>
   work with other <Application>make</Application> programs. On GNU/Linux systems
   GNU make is the default tool, on other systems you may find that
   GNU <Application>make</Application> is installed under the name <Quote>gmake</Quote>.
   We will use that name from now on to indicate <acronym>GNU</acronym>
   <Application>make</Application>, no matter what name it has on your system.
   To test for <acronym>GNU</acronym> <Application>make</Application> enter
<programlisting>
d40 4
a43 4
</programlisting>
   If you need to get <acronym>GNU</acronym> <Application>make</Application>, you can
   find it at <ULink url="ftp://ftp.gnu.org">ftp://ftp.gnu.org</ULink>.
  </Para>
d607 1
a607 1
mode: sgml
d617 1
a617 1
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
@


1.35
log
@Rearrange steps in recommended install procedure to something more
reasonable, ie configure and build first, then optionally run regress
tests using new parallel (non-installed) test method, and only then
backup and kill old installation.
@
text
@d165 1
a165 1
    <term>--with-perl</term> initially, and then build and install the
@


1.34
log
@Added bug reporting guidelines
Some corrections in installation procedure
@
text
@d99 3
a101 2
or any other account with special access rights is a security risk and therefore
won't be allowed.
a111 93
If you are not upgrading an existing system then skip to 
<xref linkend="continue">.
</Para>

<Para>
You now need to back up your existing database.
To dump your fairly recent post-6.0 database installation, type
<programlisting>
pg_dumpall > db.out
</programlisting>
If you wish to preserve object id's (oids), then use the -o
option when running <application>pg_dumpall</application>.  
However, unless you have a
special reason for doing this (such as using OIDs as keys
in tables), don't do it.
</Para>

<Para>
Make sure to use the <application>pg_dumpall</application>
command from the version you are currently running.
However, do not use the <application>pg_dumpall</application> 
script from 6.0 or everything will be owned by the
<ProductName>PostgreSQL</ProductName> super user. In that case
you should grab <application>pg_dumpall</application> from a later
6.x.x release. 7.0's <application>pg_dumpall</application>
will not work on older databases.
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, restore your database,
then back it up again.
</Para>

<caution>
<Para>
     You must make sure that your database is not updated in the middle of
     your backup.  If necessary, bring down postmaster, edit the permissions
     in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>
 to allow only you on, then
     bring <application>postmaster</application> back up.
</Para>
</caution>
</Step>

<Step Performance="required">
<Para>
If you are upgrading an existing system then kill the database server now. Type
<ProgramListing>
ps ax | grep postmaster
</ProgramListing>
or
<ProgramListing>
ps -e | grep postmaster
</ProgramListing>
(It depends on your system which one of these two works. No harm can be done
by typing the wrong one.)
This should list the process numbers for a number of processes, similar
to this:
<ProgramListing>
  263  ?  SW   0:00 (postmaster)
  777  p1 S    0:00 grep postmaster
</ProgramListing>
Type the following line, with <replaceable>pid</replaceable>
replaced by the process id for process <literal>postmaster</literal>
(263 in the above case). (Do not use the id for the process "grep postmaster".)
<programlisting>
kill <replaceable>pid</replaceable>
</programlisting>
</Para>

<tip>
<para>
On systems which have <productname>PostgreSQL</productname> started at boot time, there
is probably a startup file which will accomplish the same thing. For example, on a
Redhat Linux system one might find that
<programlisting>
/etc/rc.d/init.d/postgres.init stop
</programlisting>
works.
</para>
</tip>

<Para>
Also move the old directories  out of the way. Type the following:
<programlisting>
mv /usr/local/pgsql /usr/local/pgsql.old
</programlisting>
or replace your particular paths.
</Para>

</Step>

<Step Performance="required" id="continue">
<Para>
d160 2
a161 1
    Builds the Perl interface. Please note that the Perl interface will be
d163 5
a167 2
    <filename>/usr/lib/perl</filename>), so you must have root access to use
    this option successfully.
d202 1
a202 1
Your milage will most certainly vary. Remember to use GNU make.
d213 12
d227 96
a322 1
Install the program.  Type
d327 5
d336 3
a338 2
Tell your system how to find the new shared libraries. How to do this varies between
platforms. What tends to work everywhere is to set the environment variable
d375 2
a376 1
Create the database installation. To do this you must log in to your
d390 2
a391 1
can write to the directory (or create it) before starting <command>initdb</command>.
d393 2
a394 1
superuser, you may have to log in as root temporarily to create the data directory.)
d401 1
a401 1
Do so now.
d406 7
a412 1
the background, use the <option>-S</option>.
d437 1
a437 1
Life will be more convenient if you set up some enviroment variables. First of all
d574 4
a577 6
Run the regression tests. The regression tests are a test suite to verify that
PostgreSQL runs on your machine in the way the developers expected it to.
You should definitely do this before putting a server into production use.
The file <filename>/usr/src/pgsql/postgresql-7.0/src/test/regress/README</filename>
has detailed
instructions for running and interpreting the regression tests.
d593 2
a594 2
to connect to that database. At the prompt you can enter SQL and start
experimenting.
@


1.33
log
@updated install file
updated date/time types doc
fixed small psql bug
removed libpq code that lower-cased db names
make notice when long identifier is truncated
@
text
@a11 8
   Commands were tested on RedHat Linux version 5.2 using the bash shell.
   Except where noted, they will probably work on most systems. Commands
   like <command>ps</command> and <command>tar</command> may vary wildly 
   between platforms on what options you should use.
   <Emphasis>Use common sense</Emphasis> before typing in these commands.
  </Para>

  <Para>
d16 3
a18 3
$ gunzip postgresql-7.0.tar.gz
$ tar -xf postgresql-7.0.tar
$ mv postgresql-7.0 /usr/src
a19 1
   Again, these commands might differ on your system.
d35 1
a35 1
$ <userinput>gmake --version</userinput>
d68 1
a68 1
$ df -k
d119 1
a119 1
$ pg_dumpall > db.out
d121 2
a122 2
     If you wish to preserve object id's (oids), then use the -o
     option when running <application>pg_dumpall</application>.  
d124 1
a124 1
     special reason for doing this (such as using OIDs as keys
d158 5
a162 1
$ ps ax | grep postmaster
d164 2
d176 1
a176 1
$ kill <replaceable>pid</replaceable>
d186 1
a186 1
$ /etc/rc.d/init.d/postgres.init stop
d195 1
a195 1
$ mv /usr/local/pgsql /usr/local/pgsql.old
d209 1
a209 1
$ ./configure
d287 1
a287 1
$ gmake
d290 1
a290 1
Your milage will most certainly vary.
a297 2
Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> on
your system.
d305 1
a305 1
$ gmake install
d316 6
a321 2
$ LD_LIBRARY_PATH=/usr/local/pgsql/lib
$ export LD_LIBRARY_PATH
d323 1
d325 1
a325 1
<filename>~/.bash_profile</filename>.
d341 1
a341 1
./psql: error in loading shared libraries
d354 4
a357 4
$ mkdir /usr/local/pgsql/data
$ chown postgres /usr/local/pgsql/data
$ su - postgres
$ /usr/local/pgsql/initdb -D /usr/local/pgsql/data
d375 1
a375 1
$ /usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
d386 1
a386 1
$ /usr/local/pgsql/bin/psql < db.out
d424 2
a425 2
$ cd /usr/src/pgsql/postgresql-7.0/doc
$ gmake install
d442 2
a443 2
$ cd /usr/local/pgsql/doc
$ gunzip -c user.ps.tz | lpr
d448 1
a448 6
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
d450 2
a451 1
If in doubt, confer your manuals or your local expert.
d550 15
@


1.32
log
@Rename 7.0.0 to 7.0 to be consistent with prior release numbering.
@
text
@d212 1
a212 1
$ ./configure [ <replaceable>options</replaceable> ]
d214 2
d218 1
a218 1
     ./configure --help
d364 3
a366 1
can write to it (or create it) before starting <command>initdb</command>.
d375 1
a375 1
$ /usr/local/pgsql/initdb/postmaster -D /usr/local/pgsql/data
d427 7
a433 1
This will install files under <filename>/usr/local/pgsql/doc</filename>.
@


1.31
log
@Added new pg_id to fix initdb problems
New INSTALL file
Fixed a copyright notice
@
text
@d7 1
a7 1
    <ProductName>PostgreSQL</ProductName> 7.0.0.
d24 3
a26 3
$ gunzip postgresql-7.0.0.tar.gz
$ tar -xf postgresql-7.0.0.tar
$ mv postgresql-7.0.0 /usr/src
d420 1
a420 1
$ cd /usr/src/pgsql/postgresql-7.0.0/doc
d537 1
a537 1
The file <filename>/usr/src/pgsql/postgresql-7.0.0/src/test/regress/README</filename>
@


1.30
log
@Included all yacc and lex files into the distribution.
@
text
@d6 2
a7 2
    Complete installation instructions for 
    <ProductName>Postgres</ProductName> 6.5.3.
d12 1
a12 40
   Before installing <ProductName>Postgres</ProductName>, you may wish to visit
   <ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
   for up to date information, patches, etc.
  </Para>

  <Para>
   These installation instructions assume:

   <ItemizedList Mark="bullet" Spacing="compact">
    <ListItem>
     <Para>
      Commands are Unix-compatible. See note below.
     </Para>
    </ListItem>
    <ListItem>
     <Para>
      Defaults are used except where noted.
     </Para>
    </ListItem>
    <ListItem>
     <Para>
      User <literal>postgres</literal> is the 
      <ProductName>Postgres</ProductName> superuser.
     </Para>
    </ListItem>
    <ListItem>
     <Para>
      The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
     </Para>
    </ListItem>
    <ListItem>
     <Para>
      The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
     </Para>
    </ListItem>
   </ItemizedList>
  </para>

  <Para>
   Commands were tested on RedHat Linux version 5.2 using the tcsh shell.
d20 9
a28 8
   Our Makefiles require GNU <Application>make</Application> (called
   <Quote>gmake</Quote> in this document).  They will <Emphasis>not</Emphasis>
   work with non-GNU <Application>make</Application> programs.  If you
   have GNU <Application>make</Application> installed under the name 
   <Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
   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.
d32 17
a48 1
   <Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
d52 7
a58 2
    <ulink url="http://www.postgresql.org/docs/admin/install.htm">
     http://www.postgresql.org/docs/admin/install.htm</ulink>.
a59 4
    In general, most Unix-compatible
    platforms with modern libraries should be able to run
    <ProductName>Postgres</ProductName>.
   </para>
d61 3
a63 5
    Although the minimum required memory for running <ProductName>Postgres</ProductName>
    is as little as 8MB, there are noticable improvements in runtimes for the regression
    tests when expanding memory up to 96MB on a relatively fast dual-processor system
    running X-Windows.
    The rule is you can never have too much memory.
d67 5
a71 16
    30 Mbytes for <filename>/usr/src/pgsql</filename>, 
    about 5 Mbytes for <filename>/usr/local/pgsql</filename>
    (excluding your database) and 1 Mbyte for an empty database.
    The database will temporarily grow to about 20 Mbytes during the
    regression tests.  You will also need about 3 Mbytes for the
    distribution tar file.
   </Para>

   <Para>
    We therefore recommend that during installation and testing you
    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
    delete the source files, tar file and regression database, you
    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
    store your database data in a flat file.
d76 1
a76 1
    <programlisting>
d78 6
a83 1
    </programlisting>
d91 1
a91 1
<Title><ProductName>Postgres</ProductName> Installation</Title>
d95 1
a95 1
<ProductName>Postgres</ProductName>:
a97 25
<Step Performance="required">
<Para>
Read any last minute information and platform specific porting
     notes.  There are some platform specific notes at the end of this
     file for Ultrix4.x, Linux, BSD/OS and NeXT.  There are other
     files in directory <FileName>/usr/src/pgsql/postgresql-6.5.3/doc</FileName>, including files FAQ-Irix
     and FAQ-Linux.  Also look in directory
<ULink url="ftp://ftp.postgresql.org/pub">ftp://ftp.postgresql.org/pub</ULink>.
     If there is a file called INSTALL in this directory then this
     file will contain the latest installation information.
</Para>

<Para>
     Please note that a "tested" platform in the list given earlier
     simply means that someone went to the effort at some point of making
     sure that a <ProductName>Postgres</ProductName> distribution would compile and run on this
     platform without modifying the code.  Since the current developers
     will not have access to all of these platforms, some of them may not
     compile cleanly and pass the regression tests in the current
     release due to minor problems.  Any such known problems and their
     solutions will be posted in 
<ULink url="ftp://ftp.postgresql.org/pub/INSTALL">ftp://ftp.postgresql.org/pub/INSTALL</ULink>.
</Para>
</Step>

d100 5
a104 2
Create the <ProductName>Postgres</ProductName> superuser account
(<literal>postgres</literal> is commonly used) if it does not already exist.
d107 3
a109 3
The owner of the Postgres files can be any unprivileged user account.
It <emphasis>must not</emphasis> be <literal>root</literal>, <literal>bin</literal>,
or any other account with special access rights, as that would create a security risk.
a110 9
</Step>

<Step Performance="required">
<Para>
Log in to the <ProductName>Postgres</ProductName> superuser account. Most of the
remaining steps in the installation will happen in this account.
</para>
</step>
<Step Performance="required">
d112 3
a114 4
Ftp file 
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz">
 <filename>ftp://ftp.postgresql.org/pub/postgresql-6.5.3.tar.gz</filename></ulink>
 from the Internet.  Store it in your home directory.
d121 2
a122 19
<xref linkend="newdirs">.
If you are upgrading from 6.5, you do not need to dump/reload or initdb.
Simply compile the source code, stop the postmaster, do a "make install", and
restart the postmaster.

If you are upgrading from 6.4.* or earlier,  back up your database.
     For alpha- and beta-level releases, the database format is liable
     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
     from previous releases.  It is therefore a bad idea to skip this
     step.  
</para>
<tip>
<para>
Do not use the <application>pg_dumpall</application> 
script from 6.0 or everything
     will be owned by the <ProductName>Postgres</ProductName> super user.
</para>
</tip>
d124 2
a125 1
<para>
a126 1

a129 18
</para>
<para>
To use the latest <application>pg_dumpall</application> script on your
existing older database before upgrading <productname>Postgres</productname>,
pull the most recent version of <application>pg_dumpall</application>
from the new distribution:

<ProgramListing>
$ cd
$ gunzip -c postgresql-6.5.3.tar.gz \
    | tar xvf - postgresql-6.5.3/src/bin/pg_dump/pg_dumpall
$ chmod a+x postgresql-6.5.3/src/bin/pg_dump/pg_dumpall
$ postgresql-6.5.3/src/bin/pg_dump/pg_dumpall > db.out
$ rm -rf postgresql-6.5.3
</ProgramListing>
</Para>

<Para>
d138 12
a149 17
     If the <application>pg_dumpall</application> command
 seems to take a long time and you think
     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.
</Para>

<Para>
     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, restore your database,
 then back it up again.
     You should also read the release notes which should cover any
 release-specific issues.
a160 1

d165 1
a165 1
If you are upgrading an existing system then kill the postmaster.  Type
d167 1
a167 1
$ ps -ax | grep postmaster
d169 9
a177 6

     This should list the process numbers for a number of processes.  Type
     the following line, with <replaceable>pid</replaceable>
 replaced by the process id for process
     <literal>postmaster</literal>.  
(Do not use the id for process "grep postmaster".)  Type
d181 1
a181 1
to actually stop the process.
d185 3
a187 3
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
d191 1
a191 1
to halt <productname>Postgres</productname>.
a193 2
</Para>
</Step>
a194 1
<Step Performance="required">
d196 1
a196 9
If you are upgrading an existing system then move the old directories
     out of the way.  If you are short of disk space then you may have to
     back up and delete the directories instead.  If you do this, save the
     old database in the <filename>/usr/local/pgsql/data</filename> directory tree.  At a
     minimum, save file <filename>/usr/local/pgsql/data/pg_hba.conf</filename>.
</Para>

<Para>
     Type the following:
d198 1
a198 6
$ su -
$ cd /usr/src
$ mv pgsql pgsql.old
$ cd /usr/local
$ mv pgsql pgsql.old
$ exit
d200 1
a202 7
<Para>
     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
     else) then you will also want to move this directory in the same
     manner.
</Para>
d205 1
a205 1
<Step Performance="required" id="newdirs">
d207 4
a210 14
  Make new source and install directories.  The actual paths can be
     different for your installation but you must be consistent throughout this procedure.
</para>
<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>gmake install</command> stage
of installation.
</para>
</note>

<para>
     Type
d212 1
a212 8
$ su
$ cd /usr/src
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ cd /usr/local
$ mkdir pgsql
$ chown postgres:postgres pgsql
$ exit
d214 1
a214 6
</Para>
</Step>

<Step Performance="required">
<Para>
 Unzip and untar the new source file.  Type
d216 1
a216 2
$ cd /usr/src/pgsql
$ gunzip -c ~/postgresql-6.5.3.tar.gz | tar xvf -
d218 11
a228 2
</Para>
</Step>
d230 8
a237 10
<Step Performance="required">
<Para>
 Configure the source code for your system.  It is this step at which
     you can specify your actual installation path for
     the build process (see the --prefix option below).  Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ ./configure [ <replaceable>options</replaceable> ]
</ProgramListing>
</Para>
d239 9
a247 1
<substeps>
d249 11
a259 9
<Step Performance="optional">
<Para>
     Among other chores, the configure script selects a system-specific
     "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
     exit.  In that case you'll need to figure out which one to use and run
     configure again, this time giving the 
<option>--with-template=TEMPLATE</option> option to
     make the right file be chosen.
d261 8
a268 2
<note>
<title>Please Report Problems</title>
d270 10
a279 70
<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> with the output of the program
     <application>./config.guess</application>. Indicate what the template file should be.
</para>
</note>

</Para>
</step>
<Step Performance="optional">
<Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config">
for details. However, for a plain-vanilla first installation with no extra
options like multi-byte character support or locale collation support it may
be adequate to have chosen the installation areas and to run configure without
extra options specified.

     The configure script accepts many additional options that you can use
     if you don't like the default configuration.  To see them all, type
<ProgramListing>
     ./configure --help
</ProgramListing>
     Some of the more commonly used ones are:
<ProgramListing>
       --prefix=BASEDIR   Selects a different base directory for the
                          installation of the <ProductName>Postgres</ProductName> configuration.
                          The default is /usr/local/pgsql.
       --with-template=TEMPLATE
                          Use template file TEMPLATE - the template
                          files are assumed to be in the directory
                          src/template, so look there for proper values.
       --with-tcl         Build interface libraries and programs requiring
                          Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
       --with-perl        Build the Perl interface library.
       --with-odbc        Build the ODBC driver package.
       --enable-hba       Enables Host Based Authentication (DEFAULT)
       --disable-hba      Disables Host Based Authentication
       --enable-locale    Enables USE_LOCALE
       --enable-cassert   Enables ASSERT_CHECKING
       --with-CC=compiler
                          Use a specific C compiler that the configure
                          script cannot find.
       --with-CXX=compiler
       --without-CXX
                          Use a specific C++ compiler that the configure
                          script cannot find, or exclude C++ compilation
                          altogether.   (This only affects libpq++ at
			  present.)
</ProgramListing>
</Para>
</step>
<Step Performance="required">
<Para>
Here is the configure script used on a Sparc Solaris 2.5 system
 with <filename>/opt/postgres</filename> specified as
 the installation base directory:

<ProgramListing>
$ ./configure --prefix=/opt/postgres \
    --with-template=sparc_solaris-gcc --with-pgport=5432 \
    --enable-hba --disable-locale
</ProgramListing>

<tip>
<para>
     Of course, you may type these three lines all
     on the same line.
</para>
</tip>
a281 3
</Step>

</substeps>
a282 4
<Step Performance="required">
<Para>
Install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type
a283 10
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/doc
$ gmake install
</ProgramListing>
</para>
<para>
The documentation is also available in Postscript format. Look for files
ending with <filename>.ps.gz</filename> in the same directory.
</para>
</step>
a286 1

d288 1
a288 3
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ gmake all > make.log 2>&1 &
$ tail -f make.log
d290 2
d295 1
a295 1
     The last line displayed will hopefully be 
a300 24

  At this point, or earlier
     if you wish, type control-C to get out of tail.  (If you have
     problems later on you may wish to examine file make.log for
     warning and error messages.)

<note>
<para>
You will probably find a number of warning
     messages in make.log.  Unless you have problems later on, these
     messages may be safely ignored.
</para>
</note>
</para>
<Para>
     If the compiler fails with a message stating that 
the <application>flex</application> command
     cannot be found then install <application>flex</application> as described earlier.
  Next,
     change directory back to this directory, type 
<programlisting>
$ gmake clean
</programlisting>
then recompile again.
d302 1
d304 1
d306 1
a306 3
     Compiler options, such as optimization and debugging, may 
     be specified on the command line using the COPT variable.
     For example, typing
d308 1
a308 1
$ gmake COPT="-g" all > make.log 2>&1 &
a309 2
     would invoke your compiler's <option>-g</option> option in all steps of the
     build.  See <filename>src/Makefile.global.in</filename> for further details.
d315 9
a323 6
 Install the program.  Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src
$ gmake install > make.install.log 2>&1 &
$ tail -f make.install.log
</ProgramListing>
d327 2
a328 1
     The last line displayed will be 
d330 1
a330 2
Thank you for choosing PostgreSQL, the most advanced open source
database engine.
d332 1
a332 4
At this point, or earlier if you wish,
     type control-C to get out of tail.
Remember, <Quote>gmake</Quote> may be called <Quote>make</Quote> on
your system.
a333 1
</Step>
a334 7
<Step Performance="required">
<Para>
If necessary, tell your system how to find the new shared libraries.  You can
do <emphasis>one</emphasis> of the following, preferably the first:
</para>
<SubSteps>
<Step Performance="optional">
d336 2
a337 1
       As root, edit file <filename>/etc/ld.so.conf</filename>.  Add a line
d339 2
a340 1
<FileName>/usr/local/pgsql/lib</FileName>
d342 1
a342 1
to the file.  Then run command <Command>/sbin/ldconfig</Command>.
d346 1
a346 1
<Step Performance="optional">
d348 3
a350 1
       In a bash shell, type
d352 4
a355 1
    export LD_LIBRARY_PATH=/usr/local/pgsql/lib
a357 2
</Step>
<Step Performance="optional">
d359 5
a363 5
       In a csh shell, type
<ProgramListing>
    setenv LD_LIBRARY_PATH /usr/local/pgsql/lib
</ProgramListing>
</para>
a364 1
</SubSteps>
d366 1
d368 7
a374 3
     Please note that the above commands may vary wildly for different
     operating systems.  Check the platform specific notes, such as
     those for Ultrix4.x or and for non-ELF Linux.
d376 1
d378 3
a380 2
<Para>
     If, when you create the database, you get the message 
d382 1
a382 1
pg_id: can't load library 'libpq.so'
d384 3
a386 2
 then the above step was necessary.  Simply
     do this step, then try to create the database again.
d389 1
d391 4
a394 89
   <Step Performance="optional">
    <Para>
     If you used the <option>--with-perl</option> option to configure, check
     the install log to see whether the Perl module was actually installed.
     If you've followed our advice to make the Postgres files be owned by
     an unprivileged userid, then the Perl module won't have been installed,
     for lack of write privileges on the Perl library directories.  You can
     complete its installation, either now or later, by becoming the user that
     does own the Perl library (often root) (via <command>su</command>) and doing
     <ProgramListing>
      $ cd /usr/src/pgsql/postgresql-6.5.3/src/interfaces/perl5
      $ gmake install
     </ProgramListing>
    </Para>
   </Step>
   
   <Step Performance="required">
    <Para>
     If it has not already been done, then prepare account <literal>postgres</literal>
     for using <ProductName>Postgres</ProductName>.
     Any account that will use <ProductName>Postgres</ProductName> must
     be similarly prepared. 
    </para>
    <para>
     There are several ways to influence the runtime environment of the
     <ProductName>Postgres</ProductName>
     server. Refer to the <citetitle>Administrator's Guide</citetitle>
     for more information.
     <note>
      <para>
       The following instructions are for a
       bash/sh shell.  Adapt accordingly for other shells.
      </para>
     </note>
    </Para>
    
    <substeps>
     
     <Step Performance="required">
      <Para>
       Add the following lines to your login environment:
       
       shell, <filename>~/.bash_profile</filename>:
       <ProgramListing>
	PATH=$PATH:/usr/local/pgsql/bin
	MANPATH=$MANPATH:/usr/local/pgsql/man
	PGLIB=/usr/local/pgsql/lib
	PGDATA=/usr/local/pgsql/data
	export PATH MANPATH PGLIB PGDATA
       </ProgramListing>
      </Para>
     </step>
     <Step Performance="required">
      <para>
       Several regression tests could fail if the user's locale collation
       scheme is different from that of the standard <literal>C</literal> locale.
      </para>
      <para>
       If you configure and compile <ProductName>Postgres</ProductName>
       with <option>--enable-locale</option> then you should
       set the locale environment to <quote><literal>C</literal></quote>
	(or unset all <quote>LC_*</quote> variables)
       by putting these additional lines to your login environment
       before starting <application>postmaster</application>:

       <ProgramListing>
	LC_COLLATE=C
	LC_CTYPE=C
	export LC_COLLATE LC_CTYPE
       </ProgramListing>
       
       <ProgramListing>
	
       </ProgramListing>
      </para>
     </step>

     <Step Performance="required">
      <Para>
       Make sure that you have defined these variables before continuing
       with the remaining steps.  The easiest way to do this is to type:
       <ProgramListing>
	$ source ~/.bash_profile
       </ProgramListing>
      </Para>
     </Step>
     
    </substeps>
   </step>
d396 2
a397 1
<Step Performance="required">
d399 8
a406 8
 Create the database installation from your <ProductName>Postgres</ProductName> 
superuser account (typically account <literal>postgres</literal>).

<Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole.  Type
<ProgramListing>
$ initdb
</ProgramListing>
a407 3
</Step>

<Step Performance="required">
d409 3
a411 10
 Set up permissions to access the database system.  Do this by editing
     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
     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
     made read only again once you are finished.

     If you are upgrading from 6.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
     redoing the file from scratch.
d413 1
a413 1
</Step>
d415 4
a418 10
<Step Performance="required">
<para>
Briefly test that the backend will start and run by running it from
the command line.
</para>
<substeps>

<Step Performance="required">
<para>
     Start the postmaster daemon running in the background by typing
d420 2
a421 2
$ cd
$ nohup postmaster -i > pgserver.log 2>&1 &
d423 2
a424 2
</Para>
</Step>
a425 1
<Step Performance="required">
d427 19
a445 4
Create a database by typing
<ProgramListing>
$ createdb test
</ProgramListing>
d447 1
a447 2
</step>
<Step Performance="required">
d449 3
a451 4
Connect to the new database:
<ProgramListing>
$ psql test
</ProgramListing>
d453 8
a460 7
</step>
<Step Performance="required">
<para>
And run a sample query:
<ProgramListing>
postgres=> SELECT datetime 'now';
</ProgramListing>
a461 2
</step>
<Step Performance="required">
d463 9
a471 4
Exit <application>psql</application>:
<ProgramListing>
postgres=> \q
</ProgramListing>
a472 2
</step>
<Step Performance="required">
d474 2
a475 1
Remove the test database (unless you will want to use it later for other tests):
d477 1
a477 1
$ dropdb test
a479 28
</step>
</substeps>
</step>
<Step Performance="required">
<Para>
     Run postmaster in the background from your <ProductName>Postgres</ProductName> 
superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application> 
from the root account!</emphasis>
</para>
<Para>
Usually, you will want to modify
     your computer so that it will automatically start postmaster whenever
    it boots. It is not required; the <ProductName>Postgres</ProductName> 
server can
be run successfully from non-privileged accounts without root intervention.
</para>
<para>
     Here are some suggestions on how to do this, contributed by various
     users.
</para>
<para>
     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
     that environment variables like PATH and PGDATA may not be set properly.
a480 4
     The examples are as follows.  Use them with extreme caution.

<itemizedlist mark="bullet">
<listitem>
d482 1
a482 2
If you are installing from a non-privileged account and have no root access, then
start the <application>postmaster</application> and send it to the background:
d484 1
a484 6
<ProgramListing>
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
</para>
</listitem>
a526 17
<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
    &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
          postmaster if it dies, but he doesn't know if there are other side
          effects.)
</para>
</listitem>

d530 1
a530 46
</Step>

<Step Performance="required">
<Para>
     Run the regression tests.
     The file <filename>/usr/src/pgsql/postgresql-6.5.3/src/test/regress/README</filename> has detailed
     instructions for running and interpreting the regression tests.
     A short version follows here:
</Para>

<substeps>

<Step Performance="required">
<Para>
    Type
<ProgramListing>
$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress
$ gmake clean
$ gmake all runtest
</ProgramListing>
</Para>

<Para>
     You do not need to type <command>gmake clean</command>
 if this is the first time you
     are running the tests.
</Para>

<Para>
     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
     failed.  Please note that it can be normal for some tests to
     "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.
     Thus, tests may "fail" due to minor differences in wording of error
     messages, small differences in floating-point roundoff, etc, between
     your system and the regression test reference platform.
     "Failures" of this type do not indicate a problem with
     <ProductName>Postgres</ProductName>.
     The file <filename>./regression.diffs</filename> contains the textual differences between
     the actual test output on your machine and the "expected" output
     (which is simply what the reference system produced).  You should
     carefully examine each difference listed to see whether it appears to
     be a significant issue.
</Para>
a531 4
<para>
For example,

<itemizedlist>
d534 6
a539 34
     For a i686/Linux-ELF platform, no tests failed since this is the
     6.5.3 regression testing reference platform.
</Para>
</listitem>

</itemizedlist>
</para>
<Para>
     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
     <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
     (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.
</Para>

<Para>
     Conclusion?  If you do see failures, try to understand the nature of
     the differences and then decide if those differences will affect your
     intended use of <ProductName>Postgres</ProductName>.  The regression
     tests are a helpful tool, but they may require some study to be useful.
</Para>

<Para>
     After running the regression tests, type

<ProgramListing>
$ dropdb regression
$ cd /usr/src/pgsql/postgresql-6.5.3/src/test/regress
$ gmake clean
</ProgramListing>

    to recover the disk space used for the tests.  (You may want to save
    the <filename>regression.diffs</filename> file in another place before doing this.)
a540 150
</Step>

</substeps>
</step>
<Step Performance="required">
<Para>
 If you haven't already done so, this would be a good time to modify
      your computer to do regular maintainence.  The following should be
      done at regular intervals:
</para>
<procedure>
<title>Minimal Backup Procedure</title>

<step performance="required">
<para>
Run the <acronym>SQL</acronym> command <command>VACUUM</command>.  
This will clean up your database.
</para>
</step>
<step performance="required">
<para>
Back up your system.  (You should probably keep the last few
           backups on hand.)  Preferably, no one else should be using the
           system at the time.
</para>
</step>
</procedure>

<para>
      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 <application>crontab</application>
      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
      our own systems to do this too.)
</Para>
</Step>

<Step Performance="required">
<Para>
 If you are upgrading an existing system then reinstall your old database.
     Type
<ProgramListing>
$ cd
$ psql -e template1 < db.out
</ProgramListing>

     If your pre-6.2 database uses either path or polygon geometric data types,
     then you will need to upgrade any columns containing those types. To
     do so, type (from within psql)
<ProgramListing>
UPDATE <replaceable>FirstTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
UPDATE <replaceable>SecondTable</replaceable> SET <replaceable>PathCol</replaceable> = UpgradePath(<replaceable>PathCol</replaceable>);
...
VACUUM;
</ProgramListing>

     UpgradePath() checks to see that a path value is consistant with the
     old syntax, and will not update a column which fails that examination.
     UpgradePoly() cannot verify that a polygon is in fact from an old
     syntax, but RevertPoly() is provided to reverse the effects of a
     mis-applied upgrade.
</Para>
</Step>

<Step Performance="required">
<Para>
 If you are a new user, you may wish to play with <ProductName>Postgres</ProductName> as described
     below.
</Para>
</Step>

<Step Performance="required">
<Para>
 Clean up after yourself.  Type
<ProgramListing>
$ rm -rf /usr/src/pgsql
$ rm -rf /usr/src/pgsql.old
# Also delete the old database directory tree if desired.
$ rm -rf /usr/local/pgsql.old
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 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>
<para>
  Here is how
     you might do it if you have Ghostscript on your system and are
     writing to a laserjet printer.

<programlisting>
$ alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
$ export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
$ gunzip user.ps.gz
$ gshp -sOUTPUTFILE=user.hp user.ps
$ gzip user.ps
$ lpr -l -s -r manpage.hp
</programlisting>
</para>
</Step>

<Step Performance="required">
<Para>
 The <ProductName>Postgres</ProductName> team wants
 to keep <ProductName>Postgres</ProductName> working on all of the
     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.
  Please send a
     mail message to 
<ulink url="mailto:pgsql-ports@@postgresql.org">pgsql-ports@@postgresql.org</ulink>
 telling us the following:

<itemizedlist>
<listitem>
<para>
The version of <ProductName>Postgres</ProductName> (6.5.3, 6.5, beta 990318, etc.).
</para>
</listitem>

<listitem>
<para>
Your operating system (i.e. RedHat v5.1 Linux v2.0.34).
</para>
</listitem>

<listitem>
<para>
Your hardware (SPARC, i486, etc.).
</para>
</listitem>

<listitem>
<para>
Did you compile, install and run the regression tests cleanly?
         If not, what source code did you change (i.e. patches you
         applied, changes you made, etc.), what tests failed, etc.
         It is normal to get many warning when you compile.  You do
         not need to report these.
</para>
a543 99

</Para>
</Step>

<Step Performance="required">
<Para>
 Now create, access and manipulate databases as desired.  Write client
     programs to access the database server.  In other words, <emphasis>enjoy</emphasis>!
</Para>
</Step>
</Procedure>
</sect1>

<Sect1>
<Title>Playing with <ProductName>Postgres</ProductName></Title>

<Para>
After <ProductName>Postgres</ProductName> is installed, a database system is created, a postmaster
daemon is running, and the regression tests have passed, you'll want to 
see <ProductName>Postgres</ProductName> do something.  That's easy.  Invoke the interactive interface
to <ProductName>Postgres</ProductName>, <Application>psql</Application>:

<ProgramListing>
% psql template1
</ProgramListing>

(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.)
</Para>

<Para>
The response from psql is:

<ProgramListing>
Welcome to the POSTGRESQL interactive sql monitor:
  Please read the file COPYRIGHT for copyright terms of POSTGRESQL

   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=>
</ProgramListing>
</Para>

<Para>
Create the database foo:

<ProgramListing>
template1=> create database foo;
CREATE DATABASE
</ProgramListing>

(Get in the habit of including those SQL semicolons.  Psql won't execute
anything until it sees the semicolon or a "\g" and the semicolon is required
to delimit multiple statements.)
</Para>

<Para>
Now connect to the new database:

<ProgramListing>
template1=> \c foo
connecting to new database: foo
</ProgramListing>

("slash" commands aren't SQL, so no semicolon.  Use \? to see all the slash commands.)
</Para>

<Para>
And create a table:

<ProgramListing>
foo=> create table bar (i int4, c char(16));
CREATE
</ProgramListing>
</Para>

<Para>
Then inspect the new table:

<ProgramListing>
foo=> \d bar

Table    = bar
+----------------------------------+----------------------------------+-------+
|              Field               |              Type                | Length|
+----------------------------------+----------------------------------+-------+
| i                                | int4                             |     4 |
| c                                | (bp)char                         |    16 |
+----------------------------------+----------------------------------+-------+
</ProgramListing>
</Para>

<Para>
And so on.  You get the idea.
</Para>
a544 31

<Sect1>
<Title>The Next Step</Title>

<Para>
Questions? Bugs? Feedback?
First, read the files in directory <filename>/usr/src/pgsql/postgresql-6.5.3/doc/</filename>.  
The FAQ in this directory may be particularly useful.
</Para>

<Para>
If <ProductName>Postgres</ProductName> failed to compile on your computer 
then fill out the form in file <filename>/usr/src/pgsql/postgresql-6.5.3/doc/bug.template</filename>
 and mail it to the location indicated at the top of the form.
</Para>

<Para>
Check on the web site at
<ULink url="http://www.postgresql.org">http://www.postgresql.org</ULink>
For more information on the various support mailing lists.
</Para>
</Sect1>

  <Sect1>
   <Title>Porting Notes</Title>

   <Para>
    Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
    the source distribution.
   </Para>
  </sect1>
@


1.29
log
@Okay, that should put us back in sync. These two patches (src & doc) are
against the sources from one hour ago and contain all the portable and
up
to date stuff.

A few other CVS "householding" things you might want to take care of:

* Remove the src/bin/cleardbdir directory

* Remove the file src/bin/psql/sql_help.h from the repository, as it is
a derived file and is build by the release_prep.

Peter Eisentraut
@
text
@a180 61
Some platforms use <application>flex</application>.  
If your system uses <application>flex</application> then make sure
     you have a good version.  To check, type 
<programlisting>
$ flex --version
</programlisting>

</Para>

<Para>
     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
     is 2.5.3 or before 2.5.2 then you will have to upgrade <application>flex</application>.  You may
     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>
     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
     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 <application>flex</application> when you try to
     compile <productname>Postgres</productname>.
</Para>

<Para>
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>
$ su -
$ cd /usr/local/src
ftp prep.ai.mit.edu
ftp> cd /pub/gnu/
ftp> binary
ftp> get flex-2.5.4.tar.gz
ftp> quit
$ gunzip -c flex-2.5.4.tar.gz | tar xvf -
$ cd 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>
</Para>

<Para>
     This will update files <filename>/usr/man/man1/flex.1</filename>,
 <filename>/usr/bin/flex</filename>,
     <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>
</Step>

<Step Performance="required">
<Para>
@


1.28
log
@Cleanup paths in install files.
@
text
@d811 1
a811 1
$ createdb
d819 1
a819 1
$ psql
d843 1
a843 1
$ destroydb
d1031 1
a1031 1
$ destroydb regression
d1244 1
a1244 1
CREATEDB
@


1.27
log
@Change v6.5.2 to 6.5.2.
@
text
@d132 1
a132 1
     files in directory <FileName>/usr/src/pgsql/doc</FileName>, including files FAQ-Irix
d279 4
a282 4
    | tar xvf - src/bin/pg_dump/pg_dumpall
$ chmod a+x src/bin/pg_dump/pg_dumpall
$ src/bin/pg_dump/pg_dumpall > db.out
$ rm -rf src
d371 1
a371 1
$ mv pgsql pgsql_6_0
d373 1
a373 1
$ mv pgsql pgsql_6_0
d432 1
a432 1
$ cd /usr/src/pgsql/src
d534 1
a534 1
$ cd /usr/src/pgsql/doc
d548 1
a548 1
$ cd /usr/src/pgsql/src
d603 1
a603 1
$ cd /usr/src/pgsql/src
d612 2
a613 1
gmake[1]: Leaving directory `/usr/src/pgsql/src/man'
d682 1
a682 1
      $ cd /usr/src/pgsql/src/interfaces/perl5
d956 1
a956 1
     The file <filename>/usr/src/pgsql/src/test/regress/README</filename> has detailed
d967 1
a967 1
$ cd /usr/src/pgsql/src/test/regress
d1032 1
a1032 1
$ cd /usr/src/pgsql/src/test/regress
d1115 4
a1118 5
$ rm -rf /usr/src/pgsql_6_5
$ rm -rf /usr/local/pgsql_6_5
# Also delete old database directory tree if it is not in
#  /usr/local/pgsql_6_5/data
$ rm ~/postgresql-6.5.3.tar.gz
d1298 1
a1298 1
First, read the files in directory <filename>/usr/src/pgsql/doc/</filename>.  
d1304 1
a1304 1
then fill out the form in file <filename>/usr/src/pgsql/doc/bug.template</filename>
@


1.26
log
@Update for 6.5.3, including new INSTALL file and updated HISTORY.
@
text
@d7 1
a7 1
    <ProductName>Postgres</ProductName> v6.5.3.
d173 2
a174 2
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-v6.5.3.tar.gz">
 <filename>ftp://ftp.postgresql.org/pub/postgresql-v6.5.3.tar.gz</filename></ulink>
d258 1
a258 1
script from v6.0 or everything
d264 1
a264 1
To dump your fairly recent post-v6.0 database installation, type
d278 1
a278 1
$ gunzip -c postgresql-v6.5.3.tar.gz \
d421 1
a421 1
$ gunzip -c ~/postgresql-v6.5.3.tar.gz | tar xvf -
d783 1
a783 1
     If you are upgrading from v6.0 or later you can copy file <filename>pg_hba.conf</filename> from
d1004 1
a1004 1
     v6.5.3 regression testing reference platform.
d1085 1
a1085 1
     If your pre-v6.2 database uses either path or polygon geometric data types,
d1118 1
a1118 1
$ rm ~/postgresql-v6.5.3.tar.gz
d1165 1
a1165 1
The version of <ProductName>Postgres</ProductName> (v6.5.3, 6.5, beta 990318, etc.).
@


1.25
log
@Change >& to > and 2>&1.
@
text
@d7 1
a7 1
    <ProductName>Postgres</ProductName> v6.5.1.
d173 2
a174 2
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.tar.gz">
 <filename>ftp://ftp.postgresql.org/pub/postgresql-v6.5.1.tar.gz</filename></ulink>
d278 1
a278 1
$ gunzip -c postgresql-v6.5.1.tar.gz \
d421 1
a421 1
$ gunzip -c ~/postgresql-v6.5.1.tar.gz | tar xvf -
d1004 1
a1004 1
     v6.5.1 regression testing reference platform.
d1118 1
a1118 1
$ rm ~/postgresql-v6.5.1.tar.gz
d1165 1
a1165 1
The version of <ProductName>Postgres</ProductName> (v6.5.1, 6.5, beta 990318, etc.).
@


1.24
log
@Update install file.
@
text
@d549 1
a549 1
$ gmake all >& make.log &
d592 1
a592 1
$ gmake COPT="-g" all >& make.log &
d604 1
a604 1
$ gmake install >& make.install.log &
@


1.23
log
@Update stuff for 6.5.1 release.
@
text
@d801 1
a801 1
$ postmaster -i
@


1.22
log
@Add mention of hot backups to the release notes.
Add id tags to chapter and section headings to ensure good labels
 on output html files.
@
text
@d7 1
a7 1
    <ProductName>Postgres</ProductName> v6.5.
d173 2
a174 2
<ulink url="ftp://ftp.postgresql.org/pub/postgresql-v6.5.tar.gz">
 <filename>ftp://ftp.postgresql.org/pub/postgresql-v6.5.tar.gz</filename></ulink>
d244 5
a248 1
If you are upgrading an existing system then back up your database.
d278 1
a278 1
$ gunzip -c postgresql-v6.5.tar.gz \
d421 1
a421 1
$ gunzip -c ~/postgresql-v6.5.tar.gz | tar xvf -
d1004 1
a1004 1
     v6.5 regression testing reference platform.
d1118 1
a1118 1
$ rm ~/postgresql-v6.5.tar.gz
d1165 1
a1165 1
The version of <ProductName>Postgres</ProductName> (v6.5, 6.4.2, beta 981014, etc.).
@


1.21
log
@Fix for duplicate LC_COLLATE
@
text
@d722 1
a722 1
       scheme is different from that of standard C locale.
d726 3
a728 2
       with the <option>--enable-locale</option> option then
       set locale environment to C (or unset all LC_* variables)
d730 2
a731 1
       before starting postmaster:
@


1.20
log
@Minor markup fixes.
@
text
@d733 1
a733 2
	LC_COLLATE=C
	export LC_COLLATE LC_CTYPE LC_COLLATE
@


1.19
log
@Clean up mention of gmake vs. make.
@
text
@d33 2
a34 1
      User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
@


1.18
log
@Make pg_dump dump ACL's by default, print warning on use of -z, and add
new -x option to skip acl dump.
@
text
@d391 1
a391 1
Usually it is sufficient to specify these at the <command>make install</command> stage
d554 2
d577 1
a577 1
$ make clean
d611 2
@


1.17
log
@Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
 integrated with the User's Guide.
Break up the former chapter on pg_options
 into Admin and Programmer's Guides.
@
text
@d262 1
a262 1
$ pg_dumpall -z > db.out
d276 1
a276 1
$ src/bin/pg_dump/pg_dumpall -z > db.out
@


1.16
log
@Prevent priority inversion in locking by checking for existing locks
before going into queue behind person with higher piority.
@
text
@d1 2
a2 2
<Chapter Id="install">
<Title>Installation</Title>
d4 6
a9 6
<Abstract>
<Para>
Complete installation instructions for 
<ProductName>Postgres</ProductName> v6.5.
</Para>
</Abstract>
d11 85
a95 5
<Para>
Before installing <ProductName>Postgres</ProductName>, you may wish to visit
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
for up to date information, patches, etc.
</Para>
d97 9
a105 77
<Para>
These installation instructions assume:

<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
Commands are Unix-compatible. See note below.
</Para>
</ListItem>
<ListItem>
<Para>
Defaults are used except where noted.
</Para>
</ListItem>
<ListItem>
<Para>
User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
</Para>
</ListItem>
<ListItem>
<Para>
The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
<ListItem>
<Para>
The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
</Para>
</ListItem>
</ItemizedList>
</para>
<Para>
Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
Except where noted, they will probably work on most systems. Commands
like <command>ps</command> and <command>tar</command> may vary wildly 
between platforms on what options you should use.
<Emphasis>Use common sense</Emphasis> before typing in these commands.
</Para>

<Para>
Our Makefiles require GNU <Application>make</Application> (called
<Quote>gmake</Quote> in this document).  They will <Emphasis>not</Emphasis>
work with non-GNU <Application>make</Application> programs.  If you
have GNU <Application>make</Application> installed under the name 
<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
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>

<Sect1>
<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>

<Para>
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>.
</para>
<para>
Although the minimum required memory for running <ProductName>Postgres</ProductName>
is as little as 8MB, there are noticable improvements in runtimes for the regression
tests when expanding memory up to 96MB on a relatively fast dual-processor system
running X-Windows.
The rule is you can never have too much memory.
</para>
<Para>
Check that you have sufficient disk space.  You will need about
      30 Mbytes for <filename>/usr/src/pgsql</filename>, 
about 5 Mbytes for <filename>/usr/local/pgsql</filename>
      (excluding your database) and 1 Mbyte for an empty database.
      The database will temporarily grow to about 20 Mbytes during the
      regression tests.  You will also need about 3 Mbytes for the
      distribution tar file.
</Para>
d107 3
a109 13
<Para>
      We therefore recommend that during installation and testing you
      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
      delete the source files, tar file and regression database, you
      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
      store your database data in a flat file.
</Para>

<Para>
      To check for disk space, use 
<programlisting>
d111 3
a113 3
</programlisting>
</para>
</Sect1>
d1305 2
a1306 2
<Sect1>
<Title>Porting Notes</Title>
d1308 3
a1310 21
<Note>
<Para>
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>
</Note>

  <Sect2>
   <Title>Ultrix4.x</Title>
   
   <para>
    <note>
     <para>
      There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
     </para>
    </note>
   </para>
   <para>
    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
d1312 1
a1312 21
  </Sect2>
  
  <Sect2>
   <Title>Linux</Title>
   
   <Sect3>
    <Sect3Info>
     <Author>
      <FirstName>Thomas G.</FirstName>
      <SurName>Lockhart</SurName>
     </Author>
     <Date>1998-02-19</Date>
    </Sect3Info>
    <Title>Linux ELF</Title>
    
    <Para>
     The regression test reference machine is
     a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
     The linux-elf port installs cleanly. See the Linux FAQ for more details.
    </Para>
   </Sect3>
d1314 1
a1314 26
<Sect3>
<Sect3Info>
<Date>1995-05-11</Date>
</Sect3Info>
<Title>Linux a.out</Title>

<Para>
        For non-ELF Linux, the dld library MUST be obtained and installed on
        the system. It enables dynamic link loading capability to the <ProductName>Postgres</ProductName>
        port. The dld library can be obtained from the sunsite linux
        distributions. The current name is dld-3.2.5.
<ULink url="sneaker@@powergrid.electriciti.com">Jalon Q. Zimmerman</ULink>
</Para>
</Sect3>
</Sect2>

<Sect2>
<Title>BSD/OS</Title>

<Para>
        For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
</Para>
</Sect2>

<Sect2>
<Title>NeXT</Title>
d1316 16
a1331 18
<Para>
        The NeXT port for v1.09 was supplied by 
<ULink url="mailto:tom@@basil.icce.rug.nl">Tom R. Hageman</ULink>.
        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 <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to
        the general public.  Contact Info@@RnA.nl for information.
</para>
<Para>
We have no recent reports of successful NeXT installations (as of v6.2.1). 
However, the client-side libraries should work even
if the backend is not supported.
</Para>
</Sect2>
</Sect1>

</Chapter>
@


1.15
log
@Document configure's --with-maxbackends switch.
Fix a few small typos.
@
text
@d7 1
a7 1
<ProductName>Postgres</ProductName> v6.4.
d170 2
a171 2
<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>
d271 1
a271 1
$ gunzip -c postgresql-v6.4.tar.gz \
d414 1
a414 1
$ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
d992 1
a992 11
     v6.4 regression testing reference platform.
</Para>
</listitem>

<listitem>
<Para>
     For the SPARC/Linux-ELF platform, using the 970525 beta version of
     <ProductName>Postgres</ProductName> v6.2 the following tests "failed":
     float8 and geometry "failed" due to minor precision differences in
     floating point numbers.  select_views produces massively different output,
     but the differences are due to minor floating point differences.
d1102 2
a1103 2
$ rm -rf /usr/src/pgsql_6_0
$ rm -rf /usr/local/pgsql_6_0
d1105 2
a1106 2
#  /usr/local/pgsql_6_0/data
$ rm ~/postgresql-v6.2.1.tar.gz
d1153 1
a1153 1
The version of <ProductName>Postgres</ProductName> (v6.4, 6.3.2, beta 981014, etc.).
@


1.14
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d313 1
a313 1
     bring <application>postmaste</application>r back up.
d383 1
a383 1
     different for your installation but you must be consistant throughout this procedure.
d714 1
a714 1
       Several regression tests could failed if the user's locale collation
@


1.13
log
@Remove need for doc 'install man' in INSTALL file.  install does both
html and man.
@
text
@d47 1
a47 1

d77 1
a77 1

d84 1
a84 1

d110 1
a110 1

a115 1
<Para>
d153 1
a153 1

d158 1
a158 1

d165 2
a166 1

d247 1
a247 1

d253 1
d262 1
a262 1

d345 1
d384 1
d391 1
d450 1
d454 1
a454 1

d496 1
a496 1

d513 1
d520 1
a520 1

d530 1
a530 1

d534 2
a535 1

d563 1
d565 1
a565 1

d614 1
a614 1

d640 1
d660 19
a678 19
<Step Performance="optional">
<Para>
If you used the <option>--with-perl</option> option to configure, check
the install log to see whether the Perl module was actually installed.
If you've followed our advice to make the Postgres files be owned by
an unprivileged userid, then the Perl module won't have been installed,
for lack of write privileges on the Perl library directories.  You can
complete its installation, either now or later, by becoming the user that
does own the Perl library (often root) (via <command>su</command>) and doing
<ProgramListing>
$ cd /usr/src/pgsql/src/interfaces/perl5
$ gmake install
</ProgramListing>
</Para>
</Step>

<Step Performance="required">
<Para>
 If it has not already been done, then prepare account <literal>postgres</literal>
d680 1
a680 1
Any account that will use <ProductName>Postgres</ProductName> must
d682 66
a747 65

<para>
There are several ways to influence the runtime environment of the
 <ProductName>Postgres</ProductName>
server. Refer to the <citetitle>Administrator's Guide</citetitle>
 for more information.

<note>
<para>
The following instructions are for a
 bash/sh shell.  Adapt accordingly for other shells.
</note>

</Para>

<substeps>

<Step Performance="required">
<Para>
     Add the following lines to your login environment:

 shell, <filename>~/.bash_profile</filename>:
<ProgramListing>
PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
PGLIB=/usr/local/pgsql/lib
PGDATA=/usr/local/pgsql/data
export PATH MANPATH PGLIB PGDATA
</ProgramListing>
</Para>

<Step Performance="required">
<para>
Several regression tests could failed if the user's locale collation
scheme is different from that of standard C locale.

<para>
If you configure and compile <ProductName>Postgres</ProductName>
 with the <option>--enable-locale</option> option then
 set locale environment to C (or unset all LC_* variables)
by putting these additional lines to your login environment
 before starting postmaster:
<ProgramListing>
LC_COLLATE=C
LC_CTYPE=C
LC_COLLATE=C
export LC_COLLATE LC_CTYPE LC_COLLATE
</ProgramListing>

<ProgramListing>

</ProgramListing>


<Step Performance="required">
<Para>
     Make sure that you have defined these variables before continuing
     with the remaining steps.  The easiest way to do this is to type:
<ProgramListing>
$ source ~/.bash_profile
</ProgramListing>
</Para>
</Step>

</substeps>
d781 1
a781 1

d800 2
a801 1

d808 2
a809 1

d816 2
a817 1

d824 2
a825 1

d832 2
a833 1

d835 1
a835 1

d842 1
a842 1

d849 1
a849 1

d853 1
a853 1

d874 2
a875 1

d883 2
d906 2
d915 2
d932 2
d994 1
d1004 2
d1007 1
a1007 1

d1039 1
a1039 1

d1045 1
a1045 1

d1053 2
a1054 1

d1060 2
a1061 1

d1132 1
a1132 1

d1146 1
a1146 1

d1164 2
d1170 2
d1176 2
d1186 2
d1201 1
d1323 36
a1358 35
<Sect2>
<Title>Ultrix4.x</Title>

<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
        have a dynamic loader. It's available in
           s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
</Para>
</Sect2>

<Sect2>
<Title>Linux</Title>

<Sect3>
<Sect3Info>
<Author>
<FirstName>Thomas G.</FirstName>
<SurName>Lockhart</SurName>
</Author>
<Date>1998-02-19</Date>
</Sect3Info>
<Title>Linux ELF</Title>

<Para>
The regression test reference machine is
a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
The linux-elf port installs cleanly. See the Linux FAQ for more details.
</Para>
</Sect3>
d1395 1
a1395 1

@


1.12
log
@Include instructions on perl installation.
 Already in product docs since they were built on my machine.
@
text
@d517 2
a518 1
Install the <acronym>HTML</acronym> documentation. Type
a527 9

<Step Performance="optional">
<Para>
Install the man page documentation. Type

<ProgramListing>
$ cd /usr/src/pgsql/doc
$ gmake man
</ProgramListing>
@


1.12.2.1
log
@Remove need for doc 'install man' in INSTALL file.  install does both
html and man.
@
text
@d517 1
a517 2
Install the <application>man</application> and
<acronym>HTML</acronym> documentation. Type
d527 9
@


1.11
log
@Minor editing and markup changes as a result of preparing the Postscript
 documentation for v6.4.
Bigger updates to the installation instructions (install and config).
@
text
@d287 2
a288 1
     If the <application>pg_dumpall</application> command seems to take a long time and you think
d298 6
a303 3
     <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.
     You should also read the release notes which should cover any release-specific issues.
d310 2
a311 1
     in file <filename>/usr/local/pgsql/data/pg_hba.conf</filename> to allow only you on, then
d659 16
d1266 2
a1267 2
First, read the files in directory /usr/src/pgsql/doc.  The FAQ in
this directory may be particularly useful.
d1271 3
a1273 3
If <ProductName>Postgres</ProductName> failed to compile on your computer then fill out the form
in file /usr/src/pgsql/doc/bug.template and mail it to the location
indicated at the top of the form.
d1277 1
a1277 3
Mail questions to
<ULink url="pgsql-questions@@postgresql.org">pgsql-questions@@postgresql.org</ULink>.
For more information on the various mailing lists, see 
d1279 1
a1279 1
and look for the mailing lists.
@


1.10
log
@Incorporate changes suggested by Tom Lane.
Update storage space estimates.
Continue cleanup.
Still need to consolidate configure parameters with new config.sgml info.
@
text
@d417 1
a417 1
$ ./configure [ <replaceable>options as described below</replaceable> ]
d421 3
d429 2
a430 1
     configure again, this time giving the <option>--with-template=TEMPLATE</option> option to
d445 1
d447 6
a462 1

a466 5

       --with-pgport=PORT Sets the port that the postmaster process
                          listens for incoming connections on.  The
                          default is port 5432.

a468 1

a469 1

a470 1

a471 1

a472 1

a473 1

a474 1

a477 1

d487 1
d489 3
a491 2
As an example, here is the configure script used on a Sparc Solaris 2.5 system
 with <filename>/opt/postgres</filename> being the installation base directory:
d499 2
d503 2
d508 2
d661 6
a668 3
There are several ways to influence the runtime environment of the <ProductName>Postgres</ProductName>
server. Refer to the chapter on <citetitle>Administrator's Guide</citetitle> for more information.
<para>
d675 3
d679 3
a681 1
     Add the following lines to your login shell, <filename>~/.bash_profile</filename>:
d691 24
d724 2
d728 5
a732 2
 Create the database.  <Emphasis>Do not do the following as root!</Emphasis>
 This would be a major security hole.  Type
d755 54
d810 32
a841 4
     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
d846 54
a998 76

<Step Performance="required">
<Para>
 If you haven't already done so, this would be a good time to modify
     your computer so that it will automatically start postmaster whenever
     you boot your computer.

     Here are some suggestions on how to do this, contributed by various
     users.

<para>
     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
     that environment variables like PATH and PGDATA may not be set properly.

     The examples are as follows.  Use them with extreme caution.

<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:
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>

<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
          root:bin.

<programlisting>
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
    su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
        -D/usr/local/pgsql/data
        -S -o -F > /usr/local/pgsql/errlog' &
    echo -n ' pgsql'
}
</programlisting>

          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
          expression unfinished.  The exec saves one layer of shell under
          the postmaster process so the parent is init.

<listitem>
<para>
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
    &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
          postmaster if it dies, but he doesn't know if there are other side
          effects.)

</itemizedlist>

</Para>
</Step>
@


1.9
log
@Try to go through and get the markup right.
Make more changes to freshen up to v6.4 conventions.
Drop mention of Postgres95 docs.
@
text
@d6 2
a7 2
Complete installation instructions for <ProductName>Postgres</ProductName>
v6.4.
d18 2
a19 1
The installation notes below assume the following (except where noted):
d33 1
a33 1
User postgres is the <ProductName>Postgres</ProductName> superuser.
d78 7
d86 7
a92 3
You should have at least 8 MB of memory and at least 45 MB of disk space
to hold the source, binaries, and user databases.  After installation
you may reduce this to about 3 Mbytes plus space for user databases.
d95 16
d154 6
a159 1
</Para>
d164 2
a165 35
Log in to the <ProductName>Postgres</ProductName> superuser account.
</Para>

<SubSteps>
<Step Performance="required">
<Para>
Check that you have sufficient disk space.  You will need about
      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.
      The database will temporarily grow to about 20 Mbytes during the
      regression tests.  You will also need about 3 Mbytes for the
      distribution tar file.
</Para>

<Para>
      We therefore recommend that during installation and testing you
      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
      delete the source files, tar file and regression database, you
      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
      store your database data in a flat file.
</Para>

<Para>
      To check for disk space, use 
<programlisting>
$ df -k
</programlisting>
</Para>
</Step>
</SubSteps>

</Step>
d170 2
a171 1
<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>
d239 2
d256 7
d264 4
a267 1
existing database before upgrading <productname>Postgres</productname>, type:
d273 1
a273 1
$ src/bin/pg_dump/pg_dumpall > db.out
d280 2
a281 1
     option when running <application>pg_dumpall</application>.  However, unless you have a
d373 1
a373 1
<Step Performance="required">
d435 2
a436 2
<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.)
d491 2
a492 2
     As an example, here is the configure script used on a Sparc
     Solaris 2.5 system with <filename>/opt/postgres</filename> being the install base.
d518 9
d602 2
a603 2
 14) If necessary, tell your system how to find the new shared libraries.  You can
     do <emphasis>one</emphasis> of the following, preferably the first:
d652 1
a652 1
     for using <ProductName>Postgres</ProductName>.  
d654 11
a664 2
     be similarily prepared.  (The following instructions are for a
     bash shell.  Adapt accordingly for other shells.)
a713 10
     Run the regression tests.
     The file <filename>/usr/src/pgsql/src/test/regress/README</filename> has detailed
     instructions for running and interpreting the regression tests.
     A short version follows here:
</Para>

<substeps>

<Step Performance="required">
<Para>
d724 10
@


1.8
log
@Update info for v6.4. Fix markup of some examples which should
 have been <programlisting> blocks.
@
text
@d37 1
a37 1
The source path is /usr/src/pgsql (other paths are possible).
d42 1
a42 1
The runtime path is /usr/local/pgsql (other paths are possible).
d50 3
a52 2
like ps and tar vary wildly on what options you should use on each
platform. <Emphasis>Use common sense</Emphasis> before typing in these commands.
d60 4
a63 2
<Quote>make</Quote> instead of <Quote>gmake</Quote>, that's OK, but
you need to have it.
d70 5
a74 1
Information on supported platforms is in another chapter. In general, most Unix-compatible
d124 2
a125 1
Create account postgres if it does not already exist.
d131 1
a131 1
Log into account postgres.
d138 2
a139 1
      17 Mbytes for /usr/src/pgsql, about 2 Mbytes for /usr/local/pgsql
d148 1
a148 1
      have well over 20 Mbytes free under /usr/local and another 25 Mbytes
d151 1
a151 1
      will need 2 Mbytes for /usr/local/pgsql, 1 Mbyte for the empty
d157 4
a160 1
      To check for disk space, use <Command>df -k</Command>.
d164 1
d169 3
a171 2
Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.4.tar.gz from the
     Internet.  Store it in your home directory.
d177 7
a183 2
Some platforms use flex.  If your system uses flex then make sure
     you have a good version.  To check, type <Command>flex --version</Command>.
d187 1
a187 1
     If the flex command is not found then you probably do not need it.
d189 3
a191 2
     is 2.5.3 or before 2.5.2 then you will have to upgrade flex.  You may
     get it at ftp://prep.ai.mit.edu/pub/gnu/flex-2.5.4.tar.gz.
d195 1
a195 1
     If you need flex and don't have it or have the wrong version, then
d198 2
a199 2
     need it then you will be told to install/upgrade flex when you try to
     compile.
d203 21
a223 12
     To install it, type the following:
<ProgramListing>
    cd
    gunzip -c flex-2.5.4.tar.gz | tar xvf -
    cd flex-2.5.4
    configure --prefix=/usr
    make
    make check
    # You must be root when typing the next line.
    make install
    cd
    rm -rf flex-2.5.4
d228 5
a232 3
     This will update files /usr/man/man1/flex.1, /usr/bin/flex,
     /usr/lib/libfl.a, /usr/include/FlexLexer.h and will add link
     /usr/bin/flex++ which points to flex.
d240 1
a240 1
     to change often every few weeks with no notice besides a quick comment
d243 6
a248 1
     step.  Also, do not use the pg_dumpall script from v6.0 or everything
d250 5
a254 2
  Type (with the gunzip line
     and the following line typed as one line):
d256 6
a261 6
    cd
    gunzip -c postgresql-v6.4.tar.gz |
    tar xvf - src/bin/pg_dump/pg_dumpall
    chmod a+x src/bin/pg_dump/pg_dumpall
    src/bin/pg_dump/pg_dumpall > db.out
    rm -rf src
d267 3
a269 2
     option when running pg_dumpall.  However, unless you have a
     special reason for doing this, don't do it.
d273 5
a277 2
     If the pg_dumpall command seems to take a long time and you think
     it might have died, then, from another terminal, use "ls -l db.out"
d285 1
a285 1
     You should also read files /usr/src/pgsql/migration/*.
d288 1
d292 2
a293 2
     in file /usr/local/pgsql/data/pg_hba.conf to allow only you on, then
     bring postmaster back up.
d295 2
d303 1
a303 1
    ps -ax | grep postmaster
d305 1
d307 19
a325 4
     the following line, with "???" replaced by the process id for process
     "postmaster".  (Do not use the id for process "grep postmaster".)  Type
       kill ???
     with "???" modified as indicated.
d334 2
a335 2
     old database in the /usr/local/pgsql/data directory tree.  At a
     minimum, save file /usr/local/pgsql/data/pg_hba.conf.
d340 8
a347 6
        su
        cd /usr/src
        mv pgsql pgsql_6_0
        cd /usr/local
        mv pgsql pgsql_6_0
        exit
d351 2
a352 1
     If you are not using /usr/local/pgsql/data as your data directory
d362 10
a371 1
     different for your installation; be consistant throughout this procedure.
d374 8
a381 8
    su
    cd /usr/src
    mkdir pgsql
    chown postgres:postgres pgsql
    cd /usr/local
    mkdir pgsql
    chown postgres:postgres pgsql
    exit
d390 2
a391 2
    cd /usr/src/pgsql
    gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
d402 2
a403 2
    cd /usr/src/pgsql/src
    ./configure  [ options as described below ]
d412 13
a424 4
     configure again, this time giving the --with-template=TEMPLATE option to
     make the right file be chosen.  (If you have to do this, please
     send email to scrappy@@hub.org stating the output of the program
     './config.guess' and what the template file should be.)
d477 2
a478 2
     As an example, here is the configure script I use on a Sparc
     Solaris 2.5 system with /opt/postgres being the install base.
d481 3
a483 3
    ./configure --prefix=/opt/postgres \
	--with-template=sparc_solaris-gcc --with-pgport=5432 \
	--enable-hba --disable-locale
d486 1
a486 1
     Of course, in a real shell, you would type these three lines all
d493 13
d507 1
d509 3
a511 3
    cd /usr/src/pgsql/src
    gmake all >& make.log &
    tail -f make.log
d516 6
a521 2
     The last line displayed will hopefully be "All of PostgreSQL is
     successfully made. Ready to install."  At this point, or earlier
a524 1
</Para>
d526 3
a528 7
<Para>
     If your computer does not have gmake (GNU make) then try running
     make instead throughout the rest of these notes.
</Para>

<Para>
     Please note that you will probably find a number of warning
d531 1
a531 1
</Para>
d534 9
a542 4
     If the compiler fails with an error stating that the flex command
     cannot be found then install flex as described earlier.  Next,
     change directory back to this directory, type "make clean", then
     recompile again.
d550 1
a550 1
     gmake COPT="-g" all >& make.log &
d552 2
a553 2
     would invoke your compiler's -g option in all steps of the
     build.  See src/Makefile.global.in for further details.
d561 3
a563 3
    cd /usr/src/pgsql/src
    gmake install >& make.install.log &
    tail -f make.install.log
d568 5
a572 2
     The last line displayed will be "gmake[1]: Leaving directory
     `/usr/src/pgsql/src/man'".  At this point, or earlier if you wish,
d579 2
a580 2
 14) If necessary, tell UNIX how to find your shared libraries.  You can
     do ONE of the following, preferably the first:
d585 1
a585 1
       As root, edit file /etc/ld.so.conf.  Add a line
d592 1
d617 5
a621 2
     If, when you create the database, you get the message "pg_id: can't
     load library 'libpq.so'" then the above step was necessary.  Simply
d628 1
a628 1
 If it has not already been done, then prepare account postgres
d636 1
a636 1
     Add the following lines to your login shell, ~/.bash_profile:
d638 5
a642 5
    PATH=$PATH:/usr/local/pgsql/bin
    MANPATH=$MANPATH:/usr/local/pgsql/man
    PGLIB=/usr/local/pgsql/lib
    PGDATA=/usr/local/pgsql/data
    export PATH MANPATH PGLIB PGDATA
d650 1
a650 1
    source ~/.bash_profile
d660 1
a660 1
    initdb
d668 1
a668 1
     file /usr/local/pgsql/data/pg_hba.conf.  The instructions are
d670 1
a670 1
     default location, i.e. if PGDATA is set to point elsewhere, then the
d674 1
a674 1
     If you are upgrading from v6.0 or later you can copy file pg_hba.conf from
d682 2
a683 3

<Para>
     The file /usr/src/pgsql/src/test/regress/README has detailed
d688 3
d692 3
a699 3
     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>
a704 13
     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">
<Para>
d707 3
a709 3
    cd /usr/src/pgsql/src/test/regress
    gmake clean
    gmake all runtest
d714 2
a715 1
     You do not need to type "gmake clean" if this is the first time you
d720 1
a720 1
     You should get on the screen (and also written to file ./regress.out)
d722 3
a724 2
     failed.  Please note that it can be normal for some of the tests to
     "fail".  The script says a test has failed if there is any difference
d731 1
a731 1
     The file ./regression.diffs contains the textual differences between
d738 5
d748 1
d756 1
d761 1
a761 1
     int8 test will fail, producing obviously incorrect output, if your
d771 1
a771 1
     tests are a helpful tool, but they require some study to be useful.
d776 1
d778 3
a780 3
    destroydb regression
    cd /usr/src/pgsql/src/test/regress
    gmake clean
d782 1
d784 1
a784 1
    the regression.diffs file in another place before doing this.)
d788 2
d799 5
a803 2
     Whatever you do, postmaster must be run by user postgres AND NOT BY
     ROOT.  This is why all of the examples below start by switching user
d809 4
a812 1
       a) Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
d814 3
a816 2
             su postgres -c "/usr/local/pgsql/bin/postmaster -S -D
                     /usr/local/pgsql/data"
d818 3
a820 1
       b) In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
d823 11
a833 7
             #!/bin/sh
             [ -x /usr/local/pgsql/bin/postmaster ] && {
               su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
                       -D/usr/local/pgsql/data
                       -S -o -F > /usr/local/pgsql/errlog' &
               echo -n ' pgsql'
             }
d837 19
a855 2
          the postmaster process so the parent is init.  Note:  Unlike most
          other examples, this one has been tested.
a856 5
       c) In RedHat v4.0 Linux edit file /etc/inittab to add the
          following single line:
             pg:2345:respawn:/bin/su - postgres -c
                     "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
                     >> /usr/local/pgsql/server.log 2>&1 </dev/null"
d861 2
a862 2
       d) The contrib/linux area of the <ProductName>Postgres</ProductName> distribution has an example
          init.d script compatible with and tested using recent RedHat packages.
d877 2
a878 1
Run the SQL command vacuum.  This will clean up your database.
d888 1
d890 2
a891 1
      run nightly or weekly by cron.  Look at the man page for crontab
d903 2
a904 2
    cd
    psql -e template1 < db.out
d911 4
a914 4
    update YourTable set PathCol = UpgradePath(PathCol);
    update YourTable set PolyCol = UpgradePoly(PolyCol);
    ...
    vacuum;
d936 5
a940 5
    rm -rf /usr/src/pgsql_6_0
    rm -rf /usr/local/pgsql_6_0
    # Also delete old database directory tree if it is not in
    #  /usr/local/pgsql_6_0/data
    rm ~/postgresql-v6.2.1.tar.gz
d947 12
a958 1
 You will probably want to print out the documentation.  Here is how
d963 6
a968 12
        alias gshp='gs -sDEVICE=laserjet -r300 -dNOPAUSE'
        export GS_LIB=/usr/share/ghostscript:/usr/share/ghostscript/fonts
        # Print out the man pages.
        man -a -t /usr/local/pgsql/man/*/* > manpage.ps
        gshp -sOUTPUTFILE=manpage.hp manpage.ps
        rm manpage.ps
        lpr -l -s -r manpage.hp
        # Print out the Postgres95 User Manual, version 1.0,
        #  Sept. 5, 1996.
        cd /usr/src/pgsql/doc
        gshp -sOUTPUTFILE=userguide.hp userguide.ps
        lpr -l -s -r userguide.hp
d980 3
a982 1
     mail message to pgsql-ports@@postgresql.org telling us the following:
d1028 1
a1028 1
    % psql template1
d1135 2
a1136 1
For some ports, these notes may be out of date.
d1143 7
a1149 1
<Para>
d1213 1
a1213 1
We have no recent reports of successful NeXT installations (for v6.2.1). 
@


1.7
log
@Update instructions for running configure (the old ones
seem to date from some pre-autoconf interactive configure script).
Revise sequence of instructions to allow you to start the regular
postmaster run before running regression tests; there's no need to
start and kill a special postmaster for regression tests.
Update the description of interpreting regression test results.
@
text
@d477 1
d481 5
a485 3
       As root, edit file /etc/ld.so.conf.  Add line
             <FileName>/usr/local/pgsql/lib</FileName>
          to the file.  Then run command <Command>/sbin/ldconfig</Command>.
d521 2
a522 1
     for using <ProductName>Postgres</ProductName>.  Any account that will use <ProductName>Postgres</ProductName> must
d575 8
a582 1
 Start the postmaster daemon running.  Type
d584 2
a585 2
    cd
    nohup postmaster > server.log 2>&1 &
d588 2
a589 1
     account postgres).  DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
d737 11
a747 3
        a) Run the SQL command vacuum.  This will clean up your database.
        b) Back up your system.  (You should probably keep the last few
           backups on hand.)  Ideally, no one else should be using the
d750 2
d812 2
d826 1
a827 5
     If you are a developer, you will probably want to also print out
     the Postgres Implemention Guide, version 1.0, October 1, 1995.
     This is a WWW document located at
     http://www.postgresql.org/docs/impguide.
</Para>
d832 2
a833 1
 The <ProductName>Postgres</ProductName> team wants to keep <ProductName>Postgres</ProductName> working on all of the
d835 2
a836 1
     or did not get <ProductName>Postgres</ProductName> to work on you system.  Please send a
d838 17
a854 4
       - The version of <ProductName>Postgres</ProductName> (v6.2.1, 6.1.1, beta 970703, etc.).
       - Your operating system (i.e. RedHat v4.0 Linux v2.0.26).
       - Your hardware (SPARC, i486, etc.).
       - Did you compile, install and run the regression tests cleanly?
d859 3
d868 1
a868 1
     programs to access the database server.  In other words, ENJOY!
@


1.6
log
@shared library instructions.
@
text
@d6 2
a7 1
Complete installation instructions for <ProductName>Postgres</ProductName> v6.3.
d12 3
a14 6
  This procedure is
This is based on the installation instructions 
for <ProductName>Postgres</ProductName> v6.3
found in <FileName>&dollar;PGROOT/INSTALL</FileName>.
  Up to date information on <ProductName>Postgres</ProductName> may be found at
<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>.
d55 6
a60 6
Our Makefiles require GNU <Application>make</Application> (called <Quote>gmake</Quote> in this document) and
also assume that <Application>install</Application> accepts BSD options. The INSTALL
variable in the Makefiles is set to the BSD-compatible version of
<Application>install</Application>. On some systems, you will have to find a BSD-compatible
<Application>install</Application> (eg. <Application>bsdinst</Application>, which comes with the MIT X Window System
distribution).
d67 1
a67 1
Information on supported platforms is another chapter. In general, most Unix-compatible
d156 1
a156 1
Ftp file ftp://ftp.postgresql.org/pub/postgresql-v6.3.tar.gz from the
d218 1
a218 1
    gunzip -c postgresql-v6.3.tar.gz |
d317 1
a317 1
    gunzip -c ~/postgresql-v6.3.tar.gz | tar xvf -
d325 1
a325 1
     you can specify your actual source path and installation paths for
d329 1
a329 1
    ./configure
d334 6
a339 5
     The configure program will list the template files available and
     ask you to choose one.  A lot of times, an appropriate template
     file is chosen for you, and you can just press Enter to accept the
     default.  If the default is not appropriate, then type in the
     appropriate template file and press Enter.  (If you do this, then
d345 6
a350 6
     Once you have entered the template file, you will be asked a
     number of questions about your particular configuration.  These
     can be skipped by adding parameters to the configure command above.
     The following parameters can be tagged onto the end of the configure
     command:

d356 16
a377 2
       --disable-locale   Disables USE_LOCALE (DEFAULT)

d380 10
a389 13
       --disable-cassert  Disables ASSERT_CHECKING (DEFAULT)

       --with-template=TEMPLATE
                          Use template file TEMPLATE - the template
                          files are assumed to be in the directory
                          src/template, so look there for proper values.
                          (If the configure script cannot find the
                          specified template file, it will ask you for
                          one).

       --with-pgport=PORT Sets the port that the postmaster process
                          listens for incoming connections on.  The
                          default for this is port 5432.
d560 1
a560 1
     made read only again once you are finsihed.
d562 1
a562 1
     If you are upgrading from v6.0 you can copy file pg_hba.conf from
d564 1
a564 1
     redoing this from scratch.
a569 3
You may wish to skip the regression tests.
     However, we think skipping the tests is a BAD idea!
</Para>
d571 1
a571 8
<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>

<Para>
     Start the postmaster daemon running in the background by typing
d574 1
a574 1
    nohup postmaster > regress.log 2>&1 &
a575 3
</Para>

<Para>
d583 4
d588 5
a592 1
 Run the regression tests.  Type
d594 3
a597 1
    cd
a604 1

a609 1

d613 6
a618 14
     "fail".  For the failed tests, use diff to compare the files in
     directories ./results and ./expected.  If float8 failed, type
     something like:
<ProgramListing>
    cd /usr/src/pgsql/src/test/regress
    diff -w expected/float8.out results
</ProgramListing>
</Para>

<Para>

    "Failed" tests may have failed due to slightly different error messages,
     output formatting, failure to set the timezone correctly for your
     platform, etc.  "Failures" of this type do not indicate a problem with
d620 5
a627 1

d629 1
a629 1
     v6.3 regression testing reference platform.
d641 9
d652 2
a653 4
     intended use of <ProductName>Postgres</ProductName>.  However, keep in mind that this is likely
     to be the most solid release of <ProductName>Postgres</ProductName> to date, incorporating many
     bug fixes from v6.2.1, and that previous versions of <ProductName>Postgres</ProductName> have been
     in use successfully for some time now.
d657 1
a657 1
     After running the tests, type
d663 2
a664 23
</Para>
</Step>

<Step Performance="required">
<Para>

 Stop the postmaster as described in step 7.  Then restore the
     timezone to it's normal setting.  If you changed the timezone by
     modifying environment variable TZ then one way to do this is to
     log out of, then back into, account postgres.
</Para>
</Step>

<Step Performance="required">
<Para>

 Start the postmaster daemon running.  Type
<ProgramListing>
    cd
    nohup postmaster > server.log 2>&1 &
</ProgramListing>
     Run postmaster from your <ProductName>Postgres</ProductName> super user account (typically
     account postgres).  DO NOT RUN POSTMASTER FROM THE ROOT ACCOUNT.
d705 1
a705 1
       c) In RedHat v4.0 Linux edit file /etc/inittab to contain the
d709 1
a709 1
                     >> /usr/local/pgsql/server.log 2>&1" /dev/null
d740 1
a740 1
 If you are upgrading an existing system then install your old database.
@


1.5
log
@New shared library mentions.
@
text
@d465 2
a466 3
 If necessary, tell UNIX how to find your shared libraries.  If you
     are using an ELF-based system, such as Linux, do ONE of the following,
     preferably the first:
@


1.4
log
@Recommend ldconfig on any ELF.
@
text
@d466 1
a466 1
     are using Linux/ELF or any ELF-based system, do ONE of the following,
@


1.3
log
@Add id field to chapter and book tags to allow output file names
 to be meaningful.
@
text
@d466 2
a467 1
     are using Linux-ELF do ONE of the following, preferably the first:
@


1.2
log
@Include info on setting compiler options  on the command line
 when building executables.
@
text
@d1 1
a1 1
<Chapter>
@


1.1
log
@SGML source for new documentation.
@
text
@d433 11
@
