~ubuntu-branches/ubuntu/karmic/postgresql-8.4/karmic-proposed

<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.325.2.7 2010/07/27 18:56:22 petere Exp $ -->

<chapter id="installation">

 <title><![%standalone-include[<productname>PostgreSQL</>]]>

  Installation from Source Code</title>

 <indexterm zone="installation">

  <primary>installation</primary>

 </indexterm>

 <para>

  This <![%standalone-include;[document]]>

  <![%standalone-ignore;[chapter]]> describes the installation of

  <productname>PostgreSQL</productname> using the source code

  distribution.  (If you are installing a pre-packaged distribution,

  such as an RPM or Debian package, ignore this

  <![%standalone-include;[document]]>

  <![%standalone-ignore;[chapter]]>

  and read the packager's instructions instead.)

 </para>

 <sect1 id="install-short">

  <title>Short Version</title>

  <para>

<synopsis>

./configure

gmake

su

gmake install

adduser postgres

mkdir /usr/local/pgsql/data

chown postgres /usr/local/pgsql/data

su - postgres

/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data

/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data >logfile 2>&1 &

/usr/local/pgsql/bin/createdb test

/usr/local/pgsql/bin/psql test

</synopsis>

   The long version is the rest of this

   <![%standalone-include;[document.]]>

   <![%standalone-ignore;[chapter.]]>

  </para>

 </sect1>

 <sect1 id="install-requirements">

  <title>Requirements</title>

  <para>

   In general, a modern Unix-compatible platform should be able to run

   <productname>PostgreSQL</>.

   The platforms that had received specific testing at the

   time of release are listed in <xref linkend="supported-platforms">

   below. In the <filename>doc</> subdirectory of the distribution

   there are several platform-specific <acronym>FAQ</> documents you

   might wish to consult if you are having trouble.

  </para>

  <para>

   The following software packages are required for building

   <productname>PostgreSQL</>:

   <itemizedlist>

    <listitem>

     <para>

      <indexterm>

       <primary>make</primary>

      </indexterm>

      <acronym>GNU</> <application>make</> is required; other

      <application>make</> programs will <emphasis>not</> work.

      <acronym>GNU</> <application>make</> is often installed under

      the name <filename>gmake</filename>; this document will always

      refer to it by that name. (On some systems

      <acronym>GNU</acronym> <application>make</> is the default tool with the name

      <filename>make</>.) To test for <acronym>GNU</acronym>

      <application>make</application> enter:

<screen>

<userinput>gmake --version</userinput>

</screen>

      It is recommended to use version 3.76.1 or later.

     </para>

    </listitem>

    <listitem>

     <para>

      You need an <acronym>ISO</>/<acronym>ANSI</> C compiler (at least

      C89-compliant). Recent

      versions of <productname>GCC</> are recommendable, but

      <productname>PostgreSQL</> is known to build using a wide variety

      of compilers from different vendors.

     </para>

    </listitem>

    <listitem>

     <para>

      <application>tar</> is required to unpack the source

      distribution, in addition to either

      <application>gzip</> or <application>bzip2</>.  In

      addition, <application>gzip</> is required to install the

      documentation.

     </para>

    </listitem>

    <listitem>

     <para>

      <indexterm>

       <primary>readline</primary>

      </indexterm>

      <indexterm>

       <primary>libedit</primary>

      </indexterm>

      The <acronym>GNU</> <productname>Readline</> library is used by

      default.  It allows <application>psql</application> (the

      PostgreSQL command line SQL interpreter) to remember each

      command you type, and allows you to use arrow keys to recall and

      edit previous commands.  This is very helpful and is strongly

      recommended.  If you don't want to use it then you must specify

      the <option>--without-readline</option> option to

      <filename>configure</>. As an alternative, you can often use the

      BSD-licensed <filename>libedit</filename> library, originally

      developed on <productname>NetBSD</productname>. The

      <filename>libedit</filename> library is

      GNU <productname>Readline</productname>-compatible and is used if

      <filename>libreadline</filename> is not found, or if

      <option>--with-libedit-preferred</option> is used as an 

      option to <filename>configure</>. If you are using a package-based

      Linux distribution, be aware that you need both the 

      <literal>readline</> and <literal>readline-devel</> packages, if 

      those are separate in your distribution.

     </para>

    </listitem>

    <listitem>

     <para>

      <indexterm>

       <primary>zlib</primary>

      </indexterm>

      The <productname>zlib</productname> compression library will be

      used by default. If you don't want to use it then you must

      specify the <option>--without-zlib</option> option to

      <filename>configure</filename>. Using this option disables

      support for compressed archives in <application>pg_dump</> and

      <application>pg_restore</>.

     </para>

    </listitem>

   </itemizedlist>

  </para>

  <para>

   The following packages are optional.  They are not required in the

   default configuration, but they are needed when certain build

   options are enabled, as explained below:

   <itemizedlist>

    <listitem>

     <para>

      To build the server programming language

      <application>PL/Perl</application> you need a full

      <productname>Perl</productname> installation, including the

      <filename>libperl</filename> library and the header files.

      Since <application>PL/Perl</application> will be a shared

      library, the <indexterm><primary>libperl</primary></indexterm>

      <filename>libperl</filename> library must be a shared library

      also on most platforms.  This appears to be the default in

      recent <productname>Perl</productname> versions, but it was not

      in earlier versions, and in any case it is the choice of whomever

      installed Perl at your site.

      If you intend to make more than incidental use of

      <application>PL/Perl</application>, you should ensure that the

      <productname>Perl</productname> installation was built with the

      <literal>usemultiplicity</> option enabled (<literal>perl -V</>

      will show whether this is the case).

     </para>

     <para>

      If you don't have the shared library but you need one, a message

      like this will appear during the <productname>PostgreSQL</>

      build to point out this fact:

<screen>

*** Cannot build PL/Perl because libperl is not a shared library.

*** You might have to rebuild your Perl installation.  Refer to

*** the documentation for details.

</screen>

      (If you don't follow the on-screen output you will merely notice

      that the <application>PL/Perl</application> library object,

      <filename>plperl.so</filename> or similar, will not be

      installed.)  If you see this, you will have to rebuild and

      install <productname>Perl</productname> manually to be able to

      build <application>PL/Perl</application>.  During the

      configuration process for <productname>Perl</productname>,

      request a shared library.

     </para>

    </listitem>

    <listitem>

     <para>

      To build the <application>PL/Python</> server programming

      language, you need a <productname>Python</productname>

      installation with the header files and the <application>distutils</application> module.

      The <application>distutils</application> module is included by default with

      <productname>Python</productname> 1.6 and later; users of

      earlier versions of <productname>Python</productname> will need

      to install it.

     </para>

     <para>

      Since <application>PL/Python</application> will be a shared

      library, the <indexterm><primary>libpython</primary></indexterm>

      <filename>libpython</filename> library must be a shared library

      also on most platforms.  This is not the case in a default

      <productname>Python</productname> installation.  If after

      building and installing <productname>PostgreSQL</> you have a file called

      <filename>plpython.so</filename> (possibly a different

      extension), then everything went well.  Otherwise you should

      have seen a notice like this flying by:

<screen>

*** Cannot build PL/Python because libpython is not a shared library.

*** You might have to rebuild your Python installation.  Refer to

*** the documentation for details.

</screen>

      That means you have to rebuild (part of) your

      <productname>Python</productname> installation to create this

      shared library.

     </para>

     <para>

      If you have problems, run <productname>Python</> 2.3 or later's

      configure using the <literal>--enable-shared</> flag.  On some

      operating systems you don't have to build a shared library, but

      you will have to convince the <productname>PostgreSQL</> build

      system of this.  Consult the <filename>Makefile</filename> in

      the <filename>src/pl/plpython</filename> directory for details.

     </para>

    </listitem>

    <listitem>

     <para>

      If you want to build the <application>PL/Tcl</application>

      procedural language, you of course need a <productname>Tcl</>

      installation.  If you are using a pre-8.4 release of

      <productname>Tcl</>, ensure that it was built without multithreading

      support.

     </para>

    </listitem>

    <listitem>

     <para>

      To enable Native Language Support (<acronym>NLS</acronym>), that

      is, the ability to display a program's messages in a language

      other than English, you need an implementation of the

      <application>Gettext</> <acronym>API</acronym>.  Some operating

      systems have this built-in (e.g., <systemitem

      class="osname">Linux</>, <systemitem class="osname">NetBSD</>,

      <systemitem class="osname">Solaris</>), for other systems you

      can download an add-on package from <ulink

      url="http://www.gnu.org/software/gettext/"></ulink>.

      If you are using the <application>Gettext</> implementation in

      the <acronym>GNU</acronym> C library then you will additionally

      need the <productname>GNU Gettext</productname> package for some

      utility programs.  For any of the other implementations you will

      not need it.

     </para>

    </listitem>

    <listitem>

     <para>

      <application>Kerberos</>, <productname>OpenSSL</>, 

      <productname>OpenLDAP</>, and/or

      <application>PAM</>, if you want to support authentication or

      encryption using these services.

     </para>

    </listitem>

   </itemizedlist>

  </para>

  <para>

   If you are building from a <productname>Git</productname> tree instead of

   using a released source package, or if you want to do server development,

   you also need the following packages:

   <itemizedlist>

    <listitem>

     <para>

      <indexterm>

       <primary>flex</primary>

      </indexterm>

      <indexterm>

       <primary>lex</primary>

      </indexterm>

      <indexterm>

       <primary>bison</primary>

      </indexterm>

      <indexterm>

       <primary>yacc</primary>

      </indexterm>

      GNU <application>Flex</> and <application>Bison</>

      are needed to build from a Git checkout, or if you changed the actual

      scanner and parser definition files. If you need them, be sure

      to get <application>Flex</> 2.5.4 or later and

      <application>Bison</> 1.875 or later. Other <application>lex</>

      and <application>yacc</> programs cannot be used.

     </para>

    </listitem>

    <listitem>

     <para>

      <indexterm>

       <primary>perl</primary>

      </indexterm>

      <application>Perl</> 5.8 or later is needed to build from a Git checkout,

      or if you changed the input files for any of the build steps that

      use Perl scripts.  If building on Windows you will need

      <application>Perl</> in any case.

     </para>

    </listitem>

   </itemizedlist>

  </para>

  <para>

   If you need to get a <acronym>GNU</acronym> package, you can find

   it at your local <acronym>GNU</acronym> mirror site (see <ulink

   url="http://www.gnu.org/order/ftp.html"></>

   for a list) or at <ulink

   url="ftp://ftp.gnu.org/gnu/"></ulink>.

  </para>

  <para>

   Also check that you have sufficient disk space. You will need about

   100 MB for the source tree during compilation and about 20 MB for

   the installation directory. An empty database cluster takes about

   35 MB; databases take about five times the amount of space that a

   flat text file with the same data would take. If you are going to

   run the regression tests you will temporarily need up to an extra

   150 MB. Use the <command>df</command> command to check free disk

   space.

  </para>

 </sect1>

<![%standalone-ignore;[

 <sect1 id="install-getsource">

  <title>Getting The Source</title>

  <para>

   The <productname>PostgreSQL</> &version; sources can be obtained by

   anonymous FTP from <ulink

   url="ftp://ftp.postgresql.org/pub/source/v&version;/postgresql-&version;.tar.gz"></ulink>.

   Other download options can be found on our website:

   <ulink url="http://www.postgresql.org/download/"></ulink>. After you

   have obtained the file, unpack it:

<screen>

<userinput>gunzip postgresql-&version;.tar.gz</userinput>

<userinput>tar xf postgresql-&version;.tar</userinput>

</screen>

   This will create a directory

   <filename>postgresql-&version;</filename> under the current directory

   with the <productname>PostgreSQL</> sources.

   Change into that directory for the rest

   of the installation procedure.

  </para>

  <para>

   You can also get the source directly from the version control repository, see

   <xref linkend="sourcerepo">.

  </para>

 </sect1>

]]>

 <sect1 id="install-upgrading">

  <title>Upgrading</title>

  <indexterm zone="install-upgrading">

   <primary>upgrading</primary>

  </indexterm>

  <para>

   These instructions assume that your existing installation is under the

   <filename>/usr/local/pgsql</> directory, and that the data area is in

   <filename>/usr/local/pgsql/data</>.  Substitute your paths

   appropriately.

  </para>

  <para>

   The internal data storage format typically changes in every major

   release of <productname>PostgreSQL</>. Therefore, if you are upgrading

   an existing installation that does not have a version number of

   <quote>&majorversion;.x</quote>, you must back up and restore your

   data.  If you are upgrading from <productname>PostgreSQL</>

   <quote>&majorversion;.x</quote>, the new version can use your current

   data files so you should skip the backup and restore steps below because

   they are unnecessary.

  </para>

  <procedure>

   <step>

    <para>

     If making a backup, make sure that your database is not being updated.

     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>

    <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

     <application>pg_dumpall</>.

    </para>

    <para>

     To make the backup, you can use the <application>pg_dumpall</application>

     command from the version you are currently running.  For best

     results, however, try to use the <application>pg_dumpall</application>

     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>

     Shut down the old server:

<screen>

<userinput>pg_ctl stop</>

</screen>

     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 this works:

<screen>

<userinput>/etc/rc.d/init.d/postgresql stop</userinput>

</screen>

    </para>

   </step>

   <step>

    <para>

     If restoring from backup, rename or delete the old installation

     directory.  It is a good idea to rename the directory, rather than

     delete it, in case you have trouble and need to revert to it.  Keep

     in mind the directory might consume significant disk space.  To rename

     the directory, use a command like this:

<screen> 

<userinput>mv /usr/local/pgsql /usr/local/pgsql.old</>

</screen>

    </para>

   </step>

   <step>

    <para>

     Install the new version of <productname>PostgreSQL</productname> as

     outlined in <![%standalone-include[the next section.]]>

     <![%standalone-ignore[<xref linkend="install-procedure">.]]>

    </para>

   </step>

   <step>

    <para>

     Create a new database cluster if needed.  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</>

</programlisting>

    </para>

   </step>

   <step>

    <para>

     Restore your previous <filename>pg_hba.conf</> and any

     <filename>postgresql.conf</> modifications.

    </para>

   </step>

   <step>

    <para>

     Start the database server, again using the special database user

     account:

<programlisting>

<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>

</programlisting>

    </para>

   </step>

   <step>

    <para>

     Finally, restore your data from backup with:

<screen>

<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>

</screen>

     using the <emphasis>new</> <application>psql</>.

    </para>

   </step>

  </procedure>

  <para>

   Further discussion appears in

   <![%standalone-include[the documentation,]]>

   <![%standalone-ignore[<xref linkend="migration">,]]>

   including instructions on how the previous installation can continue

   running while the new installation is installed.

  </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 determine values for various

    system dependent variables and detect any 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. However,

         if you leave these with their defaults, the installation will be

         relocatable, meaning you can move the directory after

         installation. (The <literal>man</> and <literal>doc</>

         locations are not affected by this.)

        </para>

        <para>

         For relocatable installs, you might want to use 

         <filename>configure</filename>'s <literal>--disable-rpath</>

         option.  Also, you will need to tell the operating system how

         to find the shared libraries.

        </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>--sysconfdir=<replaceable>DIRECTORY</></option></term>

       <listitem>

        <para>

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

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

         Sets the directory for installing C and C++ header files. The

         default is <filename><replaceable>PREFIX</>/include</>.

        </para>

       </listitem>

      </varlistentry>

      <varlistentry>

       <term><option>--datarootdir=<replaceable>DIRECTORY</></option></term>

       <listitem>

        <para>

         Sets the root directory for various types of read-only data

         files.  This only sets the default for some of the following

         options.  The default is

         <filename><replaceable>PREFIX</>/share</>.

        </para>

       </listitem>

      </varlistentry>

      <varlistentry>

       <term><option>--datadir=<replaceable>DIRECTORY</></option></term>

       <listitem>

        <para>

         Sets the directory for read-only data files used by the