source: content/databases/postgresql.xml@ bccf77a5

<?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     "197 MB">
  <!ENTITY postgresql-time          "1.21 SBU">
]>

<sect1 id="postgresql" xreflabel="PostgreSQL-&postgresql-version;">
<sect1info>
<othername>$LastChangedBy$</othername>
<date>$Date$</date>
</sect1info>
<?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="Python"/>,
<xref linkend="tcl"/>,
<xref linkend="tk"/>,
<xref linkend="openssl"/>,
<xref linkend="Linux_PAM"/>,
<xref linkend="opensp"/>,
<xref linkend="openjade"/>,
<xref linkend="perl-modules"/>: SGMLSpm-&SGMLSpm-version;, 
<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 &amp;&amp;
make &amp;&amp;
make install &amp;&amp;
chown -R root:root /usr/share/doc/postgresql/html</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 /srv/pgsql/data &amp;&amp;
useradd -d /srv/pgsql/data postgres &amp;&amp;
chown postgres /srv/pgsql/data &amp;&amp;
su - postgres -c '/usr/bin/initdb -D /srv/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 /srv/pgsql/data > \
    /srv/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><command>chown -R root:root /usr/share/doc/postgresql/html</command>: 
This command corrects the improper ownership of some documentation 
files.</para>

<para><command>useradd -d /srv/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> and 
<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>