glfs/server/databases/postgresql.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY postgresql-download-http " ">
  <!ENTITY postgresql-download-ftp  "ftp://ftp5.us.postgresql.org/pub/PostgreSQL/source/v&postgresql-version;/postgresql-&postgresql-version;.tar.bz2">
  <!ENTITY postgresql-md5sum        "6ee5bb53b97da7c6ad9cb0825d3300dd">
  <!ENTITY postgresql-size          "16.0 MB">
  <!ENTITY postgresql-buildsize     "181 MB (additional 151 MB to run the testsuite)">
  <!ENTITY postgresql-time          "1.4 SBU (additional 0.2 SBU to run the testsuite)">
]>

<sect1 id="postgresql" xreflabel="PostgreSQL-&postgresql-version;">
  <?dbhtml filename="postgresql.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>PostgreSQL-&postgresql-version;</title>

  <indexterm zone="postgresql">
    <primary sortas="a-PostgreSQL">PostgreSQL</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to PostgreSQL</title>

    <para><application>PostgreSQL</application> is an advanced
    object-relational database management system (ORDBMS), derived
    from the Berkeley Postgres database management system.</para>

    <para>There may be a more recent release available from the
    <application>PostgreSQL</application> home page. You can check
    <ulink url="http://www.postgresql.org/"/> and probably use the
    existing BLFS instructions. Note that versions other than the one shown
    in the download URLs have not been tested in a BLFS environment.</para>

    &lfs72_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&postgresql-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&postgresql-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &postgresql-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &postgresql-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &postgresql-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &postgresql-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">PostgreSQL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="python2"/>,
    <xref linkend="tcl"/>,
    <xref linkend="openssl"/>,
    <xref linkend="libxml2"/>,
    <xref linkend="libxslt"/>,
    <xref linkend="openldap"/>,
    <xref linkend="linux-pam"/>,
    <xref linkend="mitkrb"/> and
    <ulink url="http://developer.apple.com/networking/bonjour/">Bonjour</ulink></para>

    <bridgehead renderas="sect4">Optional (To Regenerate Documentation)</bridgehead>
    <para role="optional"><xref linkend="sgml-dtd"/>,
    <xref linkend="docbook-dsssl"/>,
    <xref linkend="openjade"/>, and
    <xref linkend="perl-sgmlspm"/></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/postgresql"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of PostgreSQL</title>

    <para>Install <application>PostgreSQL</application> with the
    following commands: </para>

<screen><userinput>./configure --prefix=/usr          \
            --enable-thread-safety \
            --docdir=/usr/share/doc/postgresql-&postgresql-version; &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make check</command>.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install      &amp;&amp;
make install-docs</userinput></screen>

    <!-- 'Upgrading' seems to only ever exist in the docs for *previous* version -->
    <note>
      <para>If you are upgrading an existing system and are going to install
      the new files over the old ones, then you should back up your data, shut
      down the old server and follow the instructions in <ulink
      url="http://www.postgresql.org/docs/9.0/static/install-upgrading.html">the
      official <application>PostgreSQL</application> documentation</ulink>.</para>
    </note>

    <para>Initialize a database cluster with the following commands issued by the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m700 -d /srv/pgsql/data &amp;&amp;
groupadd -g 41 postgres &amp;&amp;
useradd -c "PostgreSQL Server" -g postgres -d /srv/pgsql/data \
        -u 41 postgres &amp;&amp;
chown -v postgres /srv/pgsql/data &amp;&amp;
su - postgres -c '/usr/bin/initdb -D /srv/pgsql/data'</userinput></screen>

    <para>As the <systemitem class="username">root</systemitem> user, start the
    database server with the following command:</para>

<screen role="root"><userinput>su - postgres -c '/usr/bin/postmaster -D /srv/pgsql/data > \
    /srv/pgsql/data/logfile 2&gt;&amp;1 &amp;'</userinput></screen>

    <para>Still as user <systemitem class="username">root</systemitem>, create
    a database and verify the installation:</para>

<screen role="root"><userinput>su - postgres -c '/usr/bin/createdb test' &amp;&amp;
echo "create table t1 ( name varchar(20), state_province varchar(20) );" \
    | (su - postgres -c '/usr/bin/psql test ') &amp;&amp;
echo "insert into t1 values ('Billy', 'NewYork');" \
    | (su - postgres -c '/usr/bin/psql test ') &amp;&amp;
echo "insert into t1 values ('Evanidus', 'Quebec');" \
    | (su - postgres -c '/usr/bin/psql test ') &amp;&amp;
echo "insert into t1 values ('Jesse', 'Ontario');" \
    | (su - postgres -c '/usr/bin/psql test ') &amp;&amp;
echo "select * from t1;" | (su - postgres -c '/usr/bin/psql test')</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>--docdir=/usr/share/doc/postgresql-&postgresql-version;</parameter>:
    This switch puts the documentation in a versioned directory.</para>

    <para><parameter>--enable-thread-safety</parameter>: This switch makes the
    client libraries thread-safe by allowing concurrent threads in
    <filename class='libraryfile'>libpq</filename> and ECPG programs to safely
    control their private connection handles.</para>

    <para><option>--with-openssl</option>: build with support for
    <application>OpenSSL</application> encrypted connections.</para>

    <para><option>--with-perl</option>: build the PL/Perl server-side language.
    </para>

    <para><option>--with-python</option>: build the PL/Python server-side
    language.</para>

    <para><option>--with-tcl</option>: build the PL/Tcl server-side language.</para>

    <para><command>groupadd ...</command>; <command>useradd ...</command>:
    These commands add an unprivileged user and group to run the database
    server.</para>

    <para><command>createdb test; create table t1; insert into t1 values...;
    select * from t1</command>: Create a database, add a table to it, insert
    some rows into the table and select them to verify that the installation
    is working properly.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring PostgreSQL</title>

    <sect3 id="postgresql-config">
      <title>Config Files</title>

      <para><filename>$PGDATA/pg_ident.con</filename>,
      <filename>$PGDATA/pg_hba.conf</filename> and
      <filename>$PGDATA/postgresql.conf</filename></para>

      <indexterm zone="postgresql postgresql-config">
        <primary sortas="e-A.PGDATA-pg_ident.con">$PGDATA/pg_indent.con</primary>
      </indexterm>

      <indexterm zone="postgresql postgresql-config">
        <primary sortas="e-A.PGDATA-pg_hba.conf">$PGDATA/pg_hba_conf</primary>
      </indexterm>

      <indexterm zone="postgresql postgresql-config">
        <primary sortas="e-A.PGDATA-postgresql.conf">$PGDATA/postgresql.conf</primary>
      </indexterm>

      <para>The <envar>PGDATA</envar> environment variable is used to
      distinguish database clusters from one another by setting it to
      the value of the directory which contains the cluster desired.
      The three configuration files exist in every <filename
      class="directory">PGDATA/</filename> directory. Details on the
      format of the files and the options that can be set in each can
      be found in <ulink
      url="file:///usr/share/doc/postgresql-&postgresql-version;/html/index.html"/>.</para>

    </sect3>

    <sect3  id="postgresql-init">
      <title>Boot Script</title>

      <para>Install the <filename>/etc/rc.d/init.d/postgresql</filename>
      init script included in the
      <xref linkend="bootscripts"/> package.</para>

      <indexterm zone="postgresql postgresql-init">
        <primary sortas="f-postgresql">postgresql</primary>
      </indexterm>

<screen role="root"><userinput>make install-postgresql</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>clusterdb, createdb, createlang, createuser, dropdb, droplang,
        dropuser, ecpg, initdb, pg_basebackup, pg_config, pg_controldata, pg_ctl,
        pg_dump, pg_dumpall, pg_resetxlog, pg_restore, pltcl_delmod,
        pltcl_listmod, pltcl_loadmod, postgres, postmaster, psql,
        reindexdb, and vacuumdb</seg>
        <seg>libecpg.{so,a}, libecpg_compat.{so,a}, libpgport.a, libpgtypes.{so,a},
        libpq.{so,a}, and various charset (and optionally, programming language)
        modules.</seg>
        <seg>/srv/pgsql, /usr/include/libpq, /usr/include/postgresql,
        /usr/lib/postgresql, /usr/share/doc/postgresql-&postgresql-version;, and
        /usr/share/postgresql</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="clusterdb">
        <term><command>clusterdb</command></term>
        <listitem>
          <para>is a utility for reclustering tables in a
          <application>PostgreSQL</application> database.</para>
          <indexterm zone="postgresql clusterdb">
            <primary sortas="b-clusterdb">clusterdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="createdb">
        <term><command>createdb</command></term>
        <listitem>
          <para> creates a new <application>PostgreSQL</application>
          database.</para>
          <indexterm zone="postgresql createdb">
            <primary sortas="b-createdb">createdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="createlang">
        <term><command>createlang</command></term>
        <listitem>
          <para>defines a new <application>PostgreSQL</application> procedural
          language.</para>
          <indexterm zone="postgresql createlang">
            <primary sortas="b-createlang">createlang</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="createuser">
        <term><command>createuser</command></term>
        <listitem>
          <para>defines a new <application>PostgreSQL</application>
          user account.</para>
          <indexterm zone="postgresql createuser">
            <primary sortas="b-createuser">createuser</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dropdb">
        <term><command>dropdb</command></term>
        <listitem>
          <para>removes a <application>PostgreSQL</application> database.</para>
          <indexterm zone="postgresql dropdb">
            <primary sortas="b-dropdb">dropdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="droplang">
        <term><command>droplang</command></term>
        <listitem>
          <para>removes a <application>PostgreSQL</application> procedural
          language.</para>
          <indexterm zone="postgresql droplang">
            <primary sortas="b-droplang">droplang</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dropuser">
        <term><command>dropuser</command></term>
        <listitem>
          <para>removes a <application>PostgreSQL</application>
          user account.</para>
          <indexterm zone="postgresql dropuser">
            <primary sortas="b-dropuser">dropuser</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ecpg">
        <term><command>ecpg</command></term>
        <listitem>
          <para>is the embedded SQL preprocessor.</para>
          <indexterm zone="postgresql ecpg">
            <primary sortas="b-ecpg">ecpg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="initdb">
        <term><command>initdb</command></term>
        <listitem>
          <para>creates a new database cluster.</para>
          <indexterm zone="postgresql initdb">
            <primary sortas="b-initdb">initdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_basebackup">
        <term><command>pg_basebackup</command></term>
        <listitem>
          <para>takes base backups of a running
          <application>PostgreSQL</application> cluster.</para>
          <indexterm zone="postgresql pg_basebackup">
            <primary sortas="b-pg_basebackup">pg_basebackup</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_config">
        <term><command>pg_config</command></term>
        <listitem>
          <para>retrieves <application>PostgreSQL</application> version
          information.</para>
          <indexterm zone="postgresql pg_config">
            <primary sortas="b-pg_config">pg_config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_controldata">
        <term><command>pg_controldata</command></term>
        <listitem>
          <para>returns information initialized during
          <command>initdb</command>, such as the catalog version and server
          locale.</para>
          <indexterm zone="postgresql pg_controldata">
            <primary sortas="b-pg_controldata">pg_controldata</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_ctl">
        <term><command>pg_ctl</command></term>
        <listitem>
          <para>controls stopping and starting the database server.</para>
          <indexterm zone="postgresql pg_ctl">
            <primary sortas="b-pg_ctl">pg_ctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_dump">
        <term><command>pg_dump</command></term>
        <listitem>
          <para>dumps database data and metadata into scripts which are used
          to recreate the database.</para>
          <indexterm zone="postgresql pg_dump">
            <primary sortas="b-pg_dump">pg_dump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_dumpall">
        <term><command>pg_dumpall</command></term>
        <listitem>
          <para>recursively calls <command>pg_dump</command> for each
          database in a cluster.</para>
          <indexterm zone="postgresql pg_dumpall">
            <primary sortas="b-pg_dumpall">pg_dumpall</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_resetxlog">
        <term><command>pg_resetxlog</command></term>
        <listitem>
          <para>clears the write-ahead log and optionally resets some
          fields in the <filename>pg_control</filename> file.</para>
          <indexterm zone="postgresql pg_resetxlog">
            <primary sortas="b-pg_resetxlog">pg_resetxlog</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pg_restore">
        <term><command>pg_restore</command></term>
        <listitem>
          <para>creates databases from dump files created by
          <command>pg_dump</command>.</para>
          <indexterm zone="postgresql pg_restore">
            <primary sortas="b-pg_restore">pg_restore</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pltcl_delmod">
        <term><command>pltcl_delmod</command></term>
        <listitem>
          <para>is a support script used to delete a module from a
          PL/<application>Tcl</application> table. The command
          requires the <ulink
          url="http://gborg.postgresql.org/project/pgtcl/">Pgtcl</ulink>
          package to be installed also.</para>
          <indexterm zone="postgresql pltcl_delmod">
            <primary sortas="b-pltcl_delmod">pltcl_delmod</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pltcl_listmod">
        <term><command>pltcl_listmod</command></term>
        <listitem>
          <para>is a support script used to list the modules in a
          PL/<application>Tcl</application> table. The command
          requires the <ulink
          url="http://gborg.postgresql.org/project/pgtcl/">Pgtcl</ulink>
          package to be installed also.</para>
          <indexterm zone="postgresql pltcl_listmod">
            <primary sortas="b-pltcl_listmod">pltcl_listmod</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="pltcl_loadmod">
        <term><command>pltcl_loadmod</command></term>
        <listitem>
          <para>is a support script used to load a module into a
          PL/<application>Tcl</application> table. The command
          requires the <ulink
          url="http://gborg.postgresql.org/project/pgtcl/">Pgtcl</ulink>
          package to be installed also.</para>
          <indexterm zone="postgresql pltcl_loadmod">
            <primary sortas="b-pltcl_loadmod">pltcl_loadmod</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="postgres">
        <term><command>postgres</command></term>
        <listitem>
          <para>is a single user database server, generally used for
          debugging.</para>
          <indexterm zone="postgresql postgres">
            <primary sortas="b-postgres">postgres</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="postmaster">
        <term><command>postmaster</command></term>
        <listitem>
          <para>(a symlink to <command>postgres</command>) is a multi-user
          database daemon.</para>
          <indexterm zone="postgresql postmaster">
            <primary sortas="b-postmaster">postmaster</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="psql">
        <term><command>psql</command></term>
        <listitem>
          <para>is a console based database shell.</para>
          <indexterm zone="postgresql psql">
            <primary sortas="b-psql">psql</primary>
          </indexterm>
        </listitem>
      </varlistentry>

       <varlistentry id="reindexdb">
        <term><command>reindexdb</command></term>
        <listitem>
          <para>is a utility for rebuilding indexes in a database.</para>
          <indexterm zone="postgresql reindexdb">
            <primary sortas="b-reindexdb">reindexdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="vacuumdb">
        <term><command>vacuumdb</command></term>
        <listitem>
          <para>compacts databases and generates statistics for the query
          analyzer.</para>
          <indexterm zone="postgresql vacuumdb">
            <primary sortas="b-vacuumdb">vacuumdb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libecpg">
        <term><filename class='libraryfile'>libecpg.{so,a}</filename></term>
        <listitem>
          <para>contains functions to support embedded SQL in C programs.</para>
          <indexterm zone="postgresql libecpg">
            <primary sortas="c-libecpg">libecpg.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libecpg_compat">
        <term><filename class='libraryfile'>libecpg_compat.{so,a}</filename></term>
        <listitem>
          <para>is the ecpg compatability library.</para>
          <indexterm zone="postgresql libecpg_compat">
            <primary sortas="c-libecpg_compat">libecpg_compat.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgport">
        <term><filename class='libraryfile'>libgport.a</filename></term>
        <listitem>
          <para>is the port-specific subsystem of the Postgres backend.</para>
          <indexterm zone="postgresql libgport">
            <primary sortas="c-libgport">libgport.a</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpgtypes">
        <term><filename class='libraryfile'>libpgtypes.{so,a}</filename></term>
        <listitem>
          <para>contains functions for dealing with Postgres data types.</para>
          <indexterm zone="postgresql libpgtypes">
            <primary sortas="c-libpgtypes">libpgtypes.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libpq">
        <term><filename class='libraryfile'>libpq.{so,a}</filename></term>
        <listitem>
          <para>is the C programmer's API to Postgres.</para>
          <indexterm zone="postgresql libpq">
            <primary sortas="c-libpq">libpq.{so,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>