source: content/databases/postgresql.xml@ df7efe5

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

  <!ENTITY postgresql-download-http "http://gd.tuwien.ac.at/db/postgresql/v&postgresql-version;/postgresql-&postgresql-version;.tar.bz2">
  <!ENTITY postgresql-download-ftp  "ftp://ftp.fr.postgresql.org/v&postgresql-version;/postgresql-&postgresql-version;.tar.bz2">
  <!ENTITY postgresql-size          "9.7 MB">
  <!ENTITY postgresql-buildsize     "80 MB">
  <!ENTITY postgresql-time          "1.21 SBU">
]>

<sect1 id="postgresql" xreflabel="PostgreSQL-&postgresql-version;">
<?dbhtml filename="postgresql.html"?>
<title>Postgre<acronym>SQL</acronym>-&postgresql-version;</title>

<sect2>
<title>Introduction to <application>Postgre<acronym>SQL</acronym></application></title>

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

<sect3><title>Package information</title>
<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 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>
</sect3>

<sect3><title><application>Postgre<acronym>SQL</acronym></application> dependencies</title>
<sect4><title>Optional</title>
<para>
<xref linkend="readline"/>,
<xref linkend="Python"/>,
<xref linkend="tcl"/>,
<xref linkend="tk"/>,
<xref linkend="openssl"/>,
<xref linkend="Linux_PAM"/>,
<ulink url="http://www.pdc.kth.se/kth-krb/">krb4</ulink>,
<xref linkend="mitkrb"/> or <xref linkend="heimdal"/>,
<ulink url="http://ant.apache.org/">Ant</ulink> and
<ulink url="http://rendezvous.sourceforge.net/">Rendezvous</ulink>
</para></sect4>
</sect3>

</sect2>

<sect2>
<title>Installation of <application>Postgre<acronym>SQL</acronym></application></title>

<para>Install <application>Postgre<acronym>SQL</acronym></application> with the following commands: </para>

<screen><userinput><command>./configure --prefix=/usr --without-readline &amp;&amp;
make &amp;&amp;
make install</command></userinput></screen>

<para>The standard installation provides only the header files needed
for client application development. Server-side applications require
the entire <application>Postgre<acronym>SQL</acronym></application>
include tree which can be installed using the following command:</para>

<screen><userinput><command>make install-all-headers</command></userinput></screen>

<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/7.4/static/install-upgrading.html">the
official <application>Postgre<acronym>SQL</acronym></application>
documentation</ulink>.</para></note>

<para>Initialize a database cluster with the following commands:</para>

<screen><userinput><command>mkdir -p /var/pgsql/data &amp;&amp;
useradd -d /var/pgsql/data postgres &amp;&amp;
chown postgres /var/pgsql/data &amp;&amp;
su - postgres -c '/usr/bin/initdb -D /var/pgsql/data'</command></userinput></screen>

<para>Start the database server with the following command:</para>

<screen><userinput><command>su - postgres -c '/usr/bin/postmaster -D /var/pgsql/data > \
    /var/pgsql/data/logfile 2&gt;&amp;1 &amp;'</command></userinput></screen>

<para>Create a database and verify the installation:</para>

<screen><userinput><command>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')</command></userinput></screen>

</sect2>

<sect2>
<title>Command explanations</title>

<para><option>--without-readline</option>: Omit this switch if you have
<application>readline</application> installed and wish to utilize
it.</para>

<para><command>useradd -d /var/pgsql/data postgres</command>: Add an unprivileged user 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>
<title>Configuring <application>Postgre<acronym>SQL</acronym></application></title>

<sect3>
<title>Config files</title>

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

<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/html/index.html"/>.</para>

<para>Install the <filename>/etc/rc.d/init.d/postgresql</filename>
init script included in the <xref linkend="intro-important-bootscripts"/> package.</para>
                                                                                                                
<screen><userinput><command>make install-postgresql</command></userinput></screen>

</sect3>

</sect2>

<sect2>
<title>Contents</title>

<para>The <application>Postgre<acronym>SQL</acronym></application> package contains
<command>clusterdb</command>,
<command>createdb</command>,
<command>createlang</command>,
<command>createuser</command>,
<command>dropdb</command>,
<command>droplang</command>,
<command>dropuser</command>,
<command>ecpg</command>,
<command>initdb</command>,
<command>initlocation</command>,
<command>ipcclean</command>,
<command>pg_config</command>,
<command>pg_controldata</command>,
<command>pg_ctl</command>,
<command>pg_dump</command>,
<command>pg_dumpall</command>,
<command>pg_encoding</command>,
<command>pg_id</command>,
<command>pg_resetxlog</command>,
<command>pg_restore</command>,
<command>pgtclsh</command>,
<command>pgtksh</command>,
<command>pltcl_delmod</command>,
<command>pltcl_listmod</command>,
<command>pltcl_loadmod</command>,
<command>postgres</command>,
<command>postmaster</command>,
<command>psql</command>,
<command>vacuumdb</command>,
<filename class="libraryfile">libecpg</filename>,
<filename class="libraryfile">libpgtcl</filename>,
<filename class="libraryfile">libpgtypes</filename>,
<filename class="libraryfile">libpq</filename> and various charset
modules.</para>

</sect2>

<sect2><title>Description</title>

<sect3><title>clusterdb</title>
<para><command>clusterdb</command> is a utility for reclustering tables
in a <application>Postgre<acronym>SQL</acronym></application>
database.</para></sect3>

<sect3><title>createdb</title>
<para><command>createdb</command> creates a new
<application>Postgre<acronym>SQL</acronym></application> database.</para></sect3>

<sect3><title>createlang</title>
<para><command>createlang</command> defines a new
<application>Postgre<acronym>SQL</acronym></application> procedural
language.</para></sect3>

<sect3><title>createuser</title>
<para><command>createuser</command> defines a new
<application>Postgre<acronym>SQL</acronym></application> user account.</para></sect3>

<sect3><title>dropdb</title>
<para><command>dropdb</command> removes a
<application>Postgre<acronym>SQL</acronym></application> database.</para></sect3>

<sect3><title>droplang</title>
<para><command>droplang</command> removes a
<application>Postgre<acronym>SQL</acronym></application> procedural
language.</para></sect3>

<sect3><title>dropuser</title>
<para><command>dropuser</command> removes a
<application>Postgre<acronym>SQL</acronym></application> user account.</para></sect3>

<sect3><title>ecpg</title>
<para><command>ecpg</command> is the embedded <acronym>SQL</acronym> preprocessor.</para></sect3>

<sect3><title>initdb</title>
<para><command>initdb</command> create a new database cluster.</para></sect3>

<sect3><title>initlocation</title>
<para><command>initlocation</command> creates a secondary database storage
area.</para></sect3>

<sect3><title>ipcclean</title>
<para><command>ipcclean</command> removes shared memory and semaphores left over by an
aborted database server.</para></sect3>

<sect3><title>pg_config</title>
<para><command>pg_config</command> retrieves
<application>Postgre<acronym>SQL</acronym></application> version
information.</para></sect3>

<sect3><title>pg_controldata</title>
<para><command>pg_controldata</command> returns information initialized during
<command>initdb</command>, such as the catalog version and server
locale.</para></sect3> 

<sect3><title>pg_ctl</title>
<para><command>pg_ctl</command> controls stopping and starting the database
server.</para></sect3>

<sect3><title>pg_dump</title>
<para><command>pg_dump</command> dumps database data and metadata into scripts which are
used to recreate the database.</para></sect3>

<sect3><title>pg_dumpall</title>
<para><command>pg_dumpall</command> recursively calls
<command>pg_dump</command> for each database in a
cluster.</para></sect3>

<sect3><title>pg_resetxlog</title>
<para><command>pg_resetxlog</command> clears the write-ahead log and optionally resets some
fields in the <filename>pg_control</filename> file.</para></sect3>

<sect3><title>pg_restore</title>
<para><command>pg_restore</command> creates databases from dump files created by
<command>pg_dump</command>.</para></sect3>

<sect3><title>pgtclsh</title>
<para><command>pgtclsh</command> is a <application>Tcl</application>
shell interface extended with
<application>Postgre<acronym>SQL</acronym></application> database access
functions.</para></sect3>

<sect3><title>pgtksh</title>
<para><command>pgtksh</command> is a
<application>Tcl</application>/<application>Tk</application> shell
interface extended with
<application>Postgre<acronym>SQL</acronym></application> database access
functions.</para></sect3>

<sect3><title>postgres</title>
<para><command>postgres</command> is a single user database server, generally used for
debugging.</para></sect3>

<sect3><title>postmaster</title>
<para><command>postmaster</command> is the multi-user database daemon.</para></sect3>

<sect3><title>psql</title>
<para><command>psql</command> is a console based database shell.</para></sect3>

<sect3><title>vacuumdb</title>
<para><command>vacuumdb</command> compacts databases and generates statistics for the
query analyzer.</para></sect3>

</sect2>

</sect1>