installation.sgml

PostgreSQL7.4.6 for Linux

  <procedure>
   <step>
    <para>
     Make sure that your database is not updated during or after the
     backup. This does not affect the integrity of the backup, but the
     changed data would of course not be included. If necessary, edit
     the permissions in the file
     <filename>/usr/local/pgsql/data/pg_hba.conf</> (or equivalent) to
     disallow access from everyone except you.
    </para>
   </step>

   <step>
    <para>
     <indexterm>
      <primary>pg_dumpall</primary>
      <secondary>use during upgrade</secondary>
     </indexterm>

     To back up your database installation, type:
<screen>
<userinput>pg_dumpall &gt; <replaceable>outputfile</></userinput>
</screen>
     If you need to preserve OIDs (such as when using them as
     foreign keys), then use the <option>-o</option> option when running
     <command>pg_dumpall</>.
    </para>

    <para>
     <command>pg_dumpall</command> does not
     save large objects.  Check
     <![%standalone-include[the documentation]]>
     <![%standalone-ignore[<xref linkend="backup-dump-caveats">]]>
     if you need to do this.
    </para>

    <para>
     To make the backup, you can use the <command>pg_dumpall</command>
     command from the version you are currently running.  For best
     results, however, try to use the <command>pg_dumpall</command>
     command from <productname>PostgreSQL</productname> &version;,
     since this version contains bug fixes and improvements over older
     versions.  While this advice might seem idiosyncratic since you
     haven't installed the new version yet, it is advisable to follow
     it if you plan to install the new version in parallel with the
     old version.  In that case you can complete the installation
     normally and transfer the data later.  This will also decrease
     the downtime.
    </para>
   </step>

   <step>
    <para>
     If you are installing the new version at the same location as the
     old one then shut down the old server, at the latest before you
     install the new files:
<screen>
<userinput>kill -INT `cat /usr/local/pgsql/data/postmaster.pid | sed 1q`</>
</screen>
     Versions prior to 7.0 do not have this
     <filename>postmaster.pid</> file. If you are using such a version
     you must find out the process ID of the server yourself, for
     example by typing <userinput>ps ax | grep postmaster</>, and
     supply it to the <command>kill</> command.
    </para>

    <para>
     On systems that have <productname>PostgreSQL</> started at boot time, there is
     probably a start-up file that will accomplish the same thing. For
     example, on a <systemitem class="osname">Red Hat Linux</> system one might find that
<screen>
<userinput>/etc/rc.d/init.d/postgresql stop</userinput>
</screen>
     works.  Another possibility is <userinput>pg_ctl stop</>.
    </para>
   </step>

   <step>
    <para>
     If you are installing in the same place as the old version then
     it is also a good idea to move the old installation out of the
     way, in case you have trouble and need to revert to it.
     Use a command like this:
<screen>
<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>
</screen>
    </para>
   </step>
  </procedure>

  <para>
   After you have installed <productname>PostgreSQL</> &version;, create a new database
   directory and start the new server. Remember that you must execute
   these commands while logged in to the special database user account
   (which you already have if you are upgrading).
<programlisting>
<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
<userinput>/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data</>
</programlisting>
   Finally, restore your data with
<screen>
<userinput>/usr/local/pgsql/bin/psql -d template1 -f <replaceable>outputfile</></userinput>
</screen>
   using the <emphasis>new</> <application>psql</>.
  </para>

  <para>
   These topics are discussed at length in <![%standalone-include[the
   documentation,]]> <![%standalone-ignore[<xref
   linkend="migration">,]]> which you are encouraged to read in any
   case.
  </para>
 </sect1>


 <sect1 id="install-procedure">
  <title>Installation Procedure</title>

  <procedure>

  <step id="configure">
   <title>Configuration</>

   <indexterm zone="configure">
    <primary>configure</primary>
   </indexterm>

   <para>
    The first step of the installation procedure is to configure the
    source tree for your system and choose the options you would like.
    This is done by running the <filename>configure</> script. For a
    default installation simply enter
<screen>
<userinput>./configure</userinput>
</screen>
    This script will run a number of tests to guess values for various
    system dependent variables and detect some quirks of your
    operating system, and finally will create several files in the
    build tree to record what it found.  (You can also run
    <filename>configure</filename> in a directory outside the source
    tree if you want to keep the build directory separate.)
   </para>

   <para>
    The default configuration will build the server and utilities, as
    well as all client applications and interfaces that require only a
    C compiler. All files will be installed under
    <filename>/usr/local/pgsql</> by default.
   </para>

   <para>
    You can customize the build and installation process by supplying one
    or more of the following command line options to
    <filename>configure</filename>:

     <variablelist>
      <varlistentry>
       <term><option>--prefix=<replaceable>PREFIX</></option></term>
       <listitem>
        <para>
         Install all files under the directory <replaceable>PREFIX</>
         instead of <filename>/usr/local/pgsql</filename>. The actual
         files will be installed into various subdirectories; no files
         will ever be installed directly into the
         <replaceable>PREFIX</> directory.
        </para>

        <para>
         If you have special needs, you can also customize the
         individual subdirectories with the following options.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--exec-prefix=<replaceable>EXEC-PREFIX</></option></term>
       <listitem>
        <para>
         You can install architecture-dependent files under a
         different prefix, <replaceable>EXEC-PREFIX</>, than what
         <replaceable>PREFIX</> was set to. This can be useful to
         share architecture-independent files between hosts. If you
         omit this, then <replaceable>EXEC-PREFIX</> is set equal to
         <replaceable>PREFIX</> and both architecture-dependent and
         independent files will be installed under the same tree,
         which is probably what you want.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--bindir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         Specifies the directory for executable programs. The default
         is <filename><replaceable>EXEC-PREFIX</>/bin</>, which
         normally means <filename>/usr/local/pgsql/bin</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--datadir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         Sets the directory for read-only data files used by the
         installed programs. The default is
         <filename><replaceable>PREFIX</>/share</>. Note that this has
         nothing to do with where your database files will be placed.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--sysconfdir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         The directory for various configuration files,
         <filename><replaceable>PREFIX</>/etc</> by default.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--libdir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         The location to install libraries and dynamically loadable
         modules. The default is
         <filename><replaceable>EXEC-PREFIX</>/lib</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--includedir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         The directory for installing C and C++ header files. The
         default is <filename><replaceable>PREFIX</>/include</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--docdir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         Documentation files, except <quote>man</> pages, will be
         installed into this directory. The default is
         <filename><replaceable>PREFIX</>/doc</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--mandir=<replaceable>DIRECTORY</></option></term>
       <listitem>
        <para>
         The man pages that come with <productname>PostgreSQL</> will be installed under
         this directory, in their respective
         <filename>man<replaceable>x</></> subdirectories.
         The default is <filename><replaceable>PREFIX</>/man</>.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>

     <note>
      <para>
       Care has been taken to make it possible to install
        <productname>PostgreSQL</> 
       into shared installation locations (such as
       <filename>/usr/local/include</filename>) without interfering
       with the namespace of the rest of the system.  First, the
       string <quote><literal>/postgresql</literal></quote> is
       automatically appended to <varname>datadir</varname>,
       <varname>sysconfdir</varname>, and <varname>docdir</varname>,
       unless the fully expanded directory name already contains the
       string <quote><literal>postgres</></quote> or <quote><literal>pgsql</></quote>.  For
       example, if you choose <filename>/usr/local</filename> as
       prefix, the documentation will be installed in
       <filename>/usr/local/doc/postgresql</filename>, but if the
       prefix is <filename>/opt/postgres</filename>, then it will be
       in <filename>/opt/postgres/doc</filename>.  The public C header files of the
       client interfaces are installed into
       <varname>includedir</varname> and are namespace-clean.  The
       internal header files and the server header files are installed
       into private directories under
       <varname>includedir</varname>.
       See the documentation of each interface for information about how to get at
       the its header files.
       Finally, a private subdirectory will also be created, if appropriate,
       under <varname>libdir</varname> for dynamically loadable modules.       
      </para>
     </note>
    </para>

    <para>
     <variablelist>
      <varlistentry>
       <term><option>--with-includes=<replaceable>DIRECTORIES</></option></term>
       <listitem>
        <para>
         <replaceable>DIRECTORIES</> is a colon-separated list of
         directories that will be added to the list the compiler
         searches for header files. If you have optional packages
         (such as GNU <application>Readline</>) installed in a non-standard
         location,
         you have to use this option and probably also the corresponding
         <option>--with-libraries</> option.
        </para>
        <para>
         Example: <literal>--with-includes=/opt/gnu/include:/usr/sup/include</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--with-libraries=<replaceable>DIRECTORIES</></option></term>
       <listitem>
        <para>
         <replaceable>DIRECTORIES</> is a colon-separated list of
         directories to search for libraries. You will probably have
         to use this option (and the corresponding
         <option>--with-includes</> option) if you have packages
         installed in non-standard locations.
        </para>
        <para>
         Example: <literal>--with-libraries=/opt/gnu/lib:/usr/sup/lib</>.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--enable-nls<optional>=<replaceable>LANGUAGES</replaceable></optional></option></term>
       <listitem>
        <para>
         Enables Native Language Support (<acronym>NLS</acronym>),
         that is, the ability to display a program's messages in a
         language other than English.
         <replaceable>LANGUAGES</replaceable> is a space separated
         list of codes of the languages that you want supported, for
         example <literal>--enable-nls='de fr'</>.  (The intersection
         between your list and the set of actually provided
         translations will be computed automatically.)  If you do not
         specify a list, then all available translations are
         installed.
        </para>

        <para>
         To use this option, you will need an implementation of the
         <application>Gettext</> API; see above.
        </para>
       </listitem>
      </varlistentry>

      <varlistentry>
       <term><option>--with-pgport=<replaceable>NUMBER</></option></term>
       <listitem>
        <para>
         Set <replaceable>NUMBER</> as the default port number for
         server and clients. The default is 5432. The port can always
         be changed later on, but if you specify it here then both
         server and clients will have the same default compiled in,
         which can be very convenient.  Usually the only good reason