Haven't yet done cleardbdir, ipcclean, pg_passwd, and pg_upgrade.
Add reference info for the SQL VACUUM command (oops, forgot it earlier).
<!entity vacuum system "vacuum.sgml">
<!-- these are in the "utilities" reference chapter -->
+<!entity createdb system "createdb.sgml">
+<!entity createuser system "createuser.sgml">
+<!entity destroydb system "destroydb.sgml">
+<!entity destroyuser system "destroyuser.sgml">
+<!entity initdb system "initdb.sgml">
+<!entity initlocation system "initlocation.sgml">
+<!entity pgDump system "pg_dump.sgml">
+<!entity pgDumpall system "pg_dumpall.sgml">
<!entity psqlRef system "psql-ref.sgml">
&set;
&show;
&update;
+&vacuum;
</Chapter>
<productname>Postgres</productname> support utilities.
</para>
+&createdb;
+&createuser;
+&destroydb;
+&destroyuser;
+&initdb;
+&initlocation;
+&pgDump;
+&pgDumpall;
&psqlRef;
</chapter>
--- /dev/null
+<REFENTRY ID="APP-CREATEDB">
+<REFMETA>
+<REFENTRYTITLE>
+<application>createdb</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>createdb</application>
+</REFNAME>
+<REFPURPOSE>
+Create a new <productname>Postgres</productname> database
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+createdb [ <replaceable class="parameter">dbname</replaceable> ]
+createdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ -D <replaceable class="parameter">datadir</replaceable> ]
+ [ -u ] [ <replaceable class="parameter">dbname</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-CREATEDB-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Use password authentication.
+Prompts for
+<replaceable class="parameter">username</replaceable>
+ and <replaceable class="parameter">password</replaceable>.
+
+<varlistentry>
+<term>
+-D <replaceable class="parameter">datadir</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the alternate database location for this database installation.
+This is the location of the installation system tables, not the location
+of this specific database, which may be different.
+
+<varlistentry>
+<term>
+<replaceable class="parameter">dbname</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the name of the database to be created. The name must be
+unique among all <productname>Postgres</productname> databases in this installation.
+<replaceable class="parameter">dbname</replaceable>
+defaults to the value of the
+<envar>USER</envar>
+environment variable.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-CREATEDB-2">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>createdb</application> will create files in the
+<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
+data area for the new database.
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+<application>createdb</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>.
+Contact your <productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
+createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+You do not have permission to create new databases.
+Contact your <productname>Postgres</productname> site administrator.
+
+<varlistentry>
+<term>
+ERROR: createdb: database '<replaceable class="parameter">dbname</replaceable>' already exists.
+createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+The database already exists.
+
+<varlistentry>
+<term>
+createdb: database creation failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server. Ensure that your site administrator has
+properly installed <productname>Postgres</productname>and initialized the site with
+<application>initdb</application>.
+
+</variablelist>
+
+<note>
+<para>
+<application>createdb</application> internally runs
+CREATE DATABASE from <application>psql</application>
+while connected to the <literal>template1</literal> database.
+</note>
+
+<REFSECT1 ID="R1-APP-CREATEDB-1">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>createdb</application> creates a new
+<productname>Postgres</productname> database.
+The person who executes this command becomes
+the database administrator, or <acronym>DBA</acronym>,
+ for this database and is the only
+person, other than the <productname>Postgres</productname> super-user,
+ who can destroy it.
+
+<para>
+<application>createdb</application> is a shell script that invokes
+<application>psql</application>.
+Hence, a <application>postmaster</application>
+process must be running on the database server host before
+<application>createdb</application>
+is executed. The
+<envar>PGOPTION</envar>
+and
+<envar>PGREALM</envar>
+environment variables will be passed on to
+<application>psql</application>
+and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
+
+<REFSECT1 ID="R1-APP-CREATEDB-2">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To create the database <literal>demo</literal>
+ using the postmaster on the local host, port 5432:
+<programlisting>
+createdb demo
+</programlisting>
+
+To create the database <literal>demo</literal>
+ using the postmaster on host eden, port 5000:
+<programlisting>
+createdb -p 5000 -h eden demo
+</programlisting>
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-CREATEUSER">
+<REFMETA>
+<REFENTRYTITLE>
+<application>createuser</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>createuser</application>
+</REFNAME>
+<REFPURPOSE>
+Create a new <productname>Postgres</productname> user
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+createuser [ <replaceable class="parameter">username</replaceable> ]
+createuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ -i <replaceable class="parameter">userid</replaceable> ]
+ [ -d | -D ] [ -u | -U ] [ <replaceable class="parameter">username</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-CREATEUSER-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+-d
+</term>
+<listitem>
+<para>
+Allows the user to create databases.
+
+<varlistentry>
+<term>
+-D
+</term>
+<listitem>
+<para>
+Forbids the user to create databases.
+
+<varlistentry>
+<term>
+-i <replaceable class="parameter">userid</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the numeric identifier to be associated with this user.
+This identifier must be unique among all <productname>Postgres</productname> users, and is not required
+to match the operating system UID.
+You will be prompted for an identifier if none is specified on the command line,
+and it will suggest an identifier matching the UID.
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Allows the user to create other users.
+
+<varlistentry>
+<term>
+-U
+</term>
+<listitem>
+<para>
+Forbids the user to create other users.
+
+<varlistentry>
+<term>
+<replaceable class="parameter">username</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the name of the <productname>Postgres</productname> user to be created.
+This name must be unique among all <productname>Postgres</productname> users.
+You will be prompted for a name if none is specified on the command line.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-CREATEUSER-2">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>createuser</application> will add an entry in the
+<literal>pg_user</literal> or <literal>pg_shadow</literal> system table.
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+createuser: database access failed.
+<listitem>
+<para>
+<application>createuser</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+createuser: database access failed.
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>. Contact your
+<productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+createuser: <replaceable class="parameter">username</replaceable> cannot create users.
+<listitem>
+<para>
+You do not have permission to create new users; contact your
+<productname>Postgres</productname> site administrator.
+
+<varlistentry>
+<term>
+createuser: user "<replaceable class="parameter">username</replaceable>" already exists
+<listitem>
+<para>
+The user to be added already has an entry in the <literal>pg_shadow</literal>
+class.
+
+<varlistentry>
+<term>
+database access failed
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server. Ensure that your site administrator has
+properly installed <productname>Postgres</productname>and initialized the site with
+<application>initdb</application>.
+
+</variablelist>
+
+<note>
+<para>
+<application>createuser</application> internally runs
+CREATE USER from <application>psql</application>
+while connected to the <literal>template1</literal> database.
+</note>
+
+<REFSECT1 ID="R1-APP-CREATEUSER-1">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>createuser</application> creates a
+new <productname>Postgres</productname> user.
+Only users with <literal>usesuper</literal> set in
+the <literal>pg_shadow</literal> class can create
+new <productname>Postgres</productname> users. As shipped,
+the user <literal>postgres</literal> can create users.
+
+<para>
+<application>createuser</application> is a shell script that invokes
+<application>psql</application>.
+Hence, a <application>postmaster</application>
+process must be running on the database server host before
+<application>createuser</application> is executed.
+ The
+<envar>PGOPTION</envar>
+and
+<envar>PGREALM</envar>
+environment variables will be passed on to
+<application>psql</application>
+and processed as described in <xref linkend="app-psql" endterm="app-psql">.
+
+Once invoked, <application>createuser</application>
+will ask a series of questions to obtain parameters not specified on
+the command line. The new user's database login name and a numeric
+user identifier must be specified.
+
+<note>
+<para>
+The <productname>Postgres</productname> user identifier
+does not need to be the same as the user's Unix UID. However, typically
+they are assigned to be the same.
+</note>
+
+<para>
+You must also describe the privileges of the new user for security purposes.
+Specifically, you will be asked whether the new user should be able to
+act as <productname>Postgres</productname> super-user,
+whether the new user may create new databases and whether the new user
+is allowed to create other new users.
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-DESTROYDB">
+<REFMETA>
+<REFENTRYTITLE>
+<application>destroydb</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>destroydb</application>
+</REFNAME>
+<REFPURPOSE>
+Create a new <productname>Postgres</productname> database
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+destroydb [ <replaceable class="parameter">dbname</replaceable> ]
+destroydb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ -i ] [ <replaceable class="parameter">dbname</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-DESTROYDB-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+-i
+</term>
+<listitem>
+<para>
+Run in interactive mode.
+Prompts for confirmation before destroying a database.
+
+<varlistentry>
+<term>
+<replaceable class="parameter">dbname</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the name of the database to be destroyed. The database
+must be one of the existing <productname>Postgres</productname> databases
+ in this installation.
+<replaceable class="parameter">dbname</replaceable>
+defaults to the value of the
+<envar>USER</envar>
+environment variable.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-DESTROYDB-2">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>destroydb</application> will remove files from the
+<filename><envar>PGDATA</envar>/<replaceable class="parameter">dbname</replaceable>/</filename>
+data area for the existing database.
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+<application>destroydb</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>.
+Contact your <productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/destroy databases
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+You do not have permission to destroy (or create) databases.
+Contact your <productname>Postgres</productname> site administrator.
+
+<varlistentry>
+<term>
+ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' does not exist.
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+The database to be removed does not have an entry in the
+<literal>pg_database</literal> class.
+
+<varlistentry>
+<term>
+ERROR: destroydb: database '<replaceable class="parameter">dbname</replaceable>' is not owned by you.
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+You are not the Database Administrator (DBA) for the specified database.
+
+<varlistentry>
+<term>
+destroydb: database destroy failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server. Ensure that your site administrator has
+properly installed <productname>Postgres</productname>and initialized the site with
+<application>initdb</application>.
+
+</variablelist>
+
+<note>
+<para>
+<application>destroydb</application> internally runs
+<command>DESTROY DATABASE</command> from <application>psql</application>
+while connected to the <literal>template1</literal> database.
+</note>
+
+<REFSECT1 ID="R1-APP-DESTROYDB-1">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>destroydb</application> destroys an existing
+<productname>Postgres</productname> database.
+The person who executes this command must be
+the database administrator, or <acronym>DBA</acronym>,
+or must be the <productname>Postgres</productname> super-user.
+The program runs silently; no confirmation message will be displayed.
+After the database is destroyed, a Unix shell prompt will reappear.
+
+<para>
+All references to
+the database are removed, including the directory containing this
+database and its associated files.
+
+<para>
+<application>destroydb</application> is a shell script that invokes
+<application>psql</application>.
+Hence, a <application>postmaster</application>
+process must be running on the database server host before
+<application>destroydb</application>
+is executed. The
+<envar>PGOPTION</envar>
+and
+<envar>PGREALM</envar>
+environment variables will be passed on to
+<application>psql</application>
+and processed as described in <xref linkend="app-psql" endterm="psql-ref">.
+
+<REFSECT1 ID="R1-APP-DESTROYDB-2">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To destroy the database <literal>demo</literal>
+ using the postmaster on the local host, port 5432:
+<programlisting>
+destroydb demo
+</programlisting>
+
+<para>
+To destroy the database <literal>demo</literal>
+ using the postmaster on host eden, port 5000:
+<programlisting>
+destroydb -p 5000 -h eden demo
+</programlisting>
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-DESTROYUSER">
+<REFMETA>
+<REFENTRYTITLE>
+<application>destroyuser</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>destroyuser</application>
+</REFNAME>
+<REFPURPOSE>
+Destroy a <productname>Postgres</productname> user and associated databases
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+destroyuser [ <replaceable class="parameter">username</replaceable> ]
+destroyuser [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ <replaceable class="parameter">username</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-DESTROYUSER-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+<replaceable class="parameter">username</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the name of the <productname>Postgres</productname> user to be removed.
+This name must exist in the <productname>Postgres</productname> installation.
+You will be prompted for a name if none is specified on the command line.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-DESTROYUSER-2">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>destroyuser</application> will remove an entry in the
+<literal>pg_user</literal> or <literal>pg_shadow</literal> system table,
+and will remove all databases for which that user is the administrator
+ (<acronym>DBA</acronym>).
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+destroyuser: database access failed.
+<listitem>
+<para>
+<application>destroyuser</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+destroyuser: database access failed.
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>. Contact your
+<productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+destroyuser: <replaceable class="parameter">username</replaceable> cannot delete users.
+<listitem>
+<para>
+You do not have permission to delete users; contact your
+<productname>Postgres</productname> site administrator.
+
+<varlistentry>
+<term>
+destroyuser: user "<replaceable class="parameter">username</replaceable>" already exists
+<listitem>
+<para>
+The user to be added already has an entry in the <literal>pg_shadow</literal>
+class.
+
+<varlistentry>
+<term>
+database access failed
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server. Ensure that your site administrator has
+properly installed <productname>Postgres</productname>and initialized the site with
+<application>initdb</application>.
+
+<varlistentry>
+<term>
+destroydb on <replaceable class="parameter">dbname</replaceable> failed - exiting
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server. There was possibly a Unix permissions problem with the
+specified database.
+
+
+<varlistentry>
+<term>
+delete of user <replaceable class="parameter">username</replaceable> was UNSUCCESSFUL
+<listitem>
+<para>
+An internal error occurred in <application>psql</application>
+or in the backend server.
+
+</variablelist>
+
+<note>
+<para>
+<application>destroyuser</application> internally runs
+DROP USER from <application>psql</application>
+while connected to the <literal>template1</literal> database.
+</note>
+
+<REFSECT1 ID="R1-APP-DESTROYUSER-1">
+<REFSECT1INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>destroyuser</application> removes an existing
+ <productname>Postgres</productname> user
+and the databases for which that user
+is database administrator.
+Only users with <literal>usesuper</literal> set in
+the <literal>pg_shadow</literal> class can destroy
+ <productname>Postgres</productname> users. As shipped,
+the user <literal>postgres</literal> can remove users.
+
+<para>
+<application>destroyuser</application> is a shell script that invokes
+<application>psql</application>.
+Hence, a <application>postmaster</application>
+process must be running on the database server host before
+<application>destroyuser</application> is executed.
+ The
+<envar>PGOPTION</envar>
+and
+<envar>PGREALM</envar>
+environment variables will be passed on to
+<application>psql</application>
+and processed as described in <xref linkend="app-psql" endterm="app-psql">.
+
+<para>
+Once invoked, <application>destroyuser</application>
+will warn you about the databases that will be destroyed in the
+process and permit you to abort the removal of the user if desired.
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-INITDB">
+<REFMETA>
+<REFENTRYTITLE>
+<application>initdb</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>initdb</application>
+</REFNAME>
+<REFPURPOSE>
+Create a new <productname>Postgres</productname> database installation
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <replaceable class="parameter">dbdir</replaceable> ]
+ [ --pglib=<replaceable class="parameter">libdir</replaceable> | -l <replaceable class="parameter">libdir</replaceable> ]
+ [ --template=<replaceable class="parameter">template</replaceable> | -t <replaceable class="parameter">template</replaceable> ]
+ [ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
+ [ --noclean | -n ] [ --debug | -d ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-INITDB-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+<variablelist>
+<varlistentry>
+<term>
+--pglib=<replaceable class="parameter">libdir</replaceable>
+</term>
+<term>
+-l <replaceable class="parameter">libdir</replaceable>
+</term>
+<term>
+<envar>PGLIB</envar>
+<listitem>
+<para>
+Where are the files that make up <productname>Postgres</productname>?
+ Apart from files that
+have to go in particular directories because of their function, the
+files that make up the <productname>Postgres</productname> software
+were installed in a directory
+called the <replaceable class="parameter">libdir</replaceable> directory.
+An example of a file that will be found
+there that <application>initdb</application>
+needs is <filename>global1.bki.source</filename>,
+ which contains all the information that goes
+into the shared catalog tables.
+
+<varlistentry>
+<term>
+--pgdata=<replaceable class="parameter">dbdir</replaceable>
+</term>
+<term>
+-r <replaceable class="parameter">dbdir</replaceable>
+</term>
+<term>
+<envar>PGDATA</envar>
+</term>
+<listitem>
+<para>
+Where in your Unix filesystem do you want the database data to go?
+The top level directory is called the <envar>PGDATA</envar> directory.
+
+<varlistentry>
+<term>
+--username=<replaceable class="parameter">name</replaceable>
+</term>
+<term>
+-u <replaceable class="parameter">name</replaceable>
+</term>
+<term>
+<envar>PGUSER</envar>
+</term>
+<listitem>
+<para>
+Who will be the <productname>Postgres</productname> superuser
+ for this database system? The
+<productname>Postgres</productname> superuser is a Unix user
+who owns all files that store the database
+system and also owns the postmaster and backend processes that access them.
+Or just let it default to you (the Unix user who runs
+<application>initdb</application>).
+
+<note>
+<para>
+Only the Unix superuser can create a database system with a
+different user as <productname>Postgres</productname> superuser.
+</note>
+
+</variablelist>
+
+<para>
+Other, less commonly used, parameters are also available:
+
+<variablelist>
+<varlistentry>
+<term>
+--template=<replaceable class="parameter">template</replaceable>
+</term>
+<term>
+-t <replaceable class="parameter">template</replaceable>
+</term>
+<listitem>
+<para>
+Replace the <literal>template1</literal>
+database in an existing database system, and don't touch anything else.
+This is useful when you need to upgrade your <literal>template1</literal>
+database using <application>initdb</application>
+from a newer release of <productname>Postgres</productname>,
+or when your <literal>template1</literal>
+database has become corrupted by some system problem. Normally the
+contents of <literal>template1</literal>
+remain constant throughout the life of the database system. You can't
+destroy anything by running <application>initdb</application>
+with the
+<option>--template</option>
+option.
+
+<varlistentry>
+<term>
+--noclean
+</term>
+<term>
+-n
+</term>
+<listitem>
+<para>
+By default, when <application>initdb</application>
+determines that error prevent it from completely creating the database
+system, it removes any files it may have created before determining
+that it can't finish the job. That includes any core files left by
+the programs it invokes. This option inhibits any tidying-up and is
+thus useful for debugging.
+
+<varlistentry>
+<term>
+--debug
+</term>
+<term>
+-d
+</term>
+<listitem>
+<para>
+Print debugging output from the bootstrap backend.
+The bootstrap backend is the program <application>initdb</application>
+uses to create the catalog tables. This option generates a tremendous
+amount of output. It also turns off the final vacuuming step.
+
+</variablelist>
+
+<para>
+Files are also input to <application>initdb</application>:
+
+<variablelist>
+<varlistentry>
+<term>
+<application>postconfig</application>
+</term>
+<listitem>
+<para>
+If appearing somewhere in the Unix command search path
+(defined by the PATH environment variable).
+ This is a program that specifies defaults for some of the
+command options. See below.
+
+<varlistentry>
+<term>
+<filename><envar>PGLIB</envar>/global1.bki.source</filename>
+</term>
+<listitem>
+<para>
+Contents for the shared catalog tables in the new database system. This
+file is part of the <productname>Postgres</productname> software.
+
+<varlistentry>
+<term>
+<filename><envar>PGLIB</envar>/local1_template1.bki.source</filename>
+</term>
+<listitem>
+<para>
+Contents for the template1 tables in the new database system. This
+file is part of the <productname>Postgres</productname> software.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-INITDB-2">
+<REFSECT2INFO>
+<DATE>1998-09-26</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>initdb</application> will create files in the <envar>PGDATA</envar>
+data area which are the system tables and framework for a complete
+installation.
+
+<REFSECT1 ID="R1-APP-INITDB-1">
+<REFSECT1INFO>
+<DATE>1998-09-26</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>initdb</application> creates a new
+<productname>Postgres</productname> database system.
+A database system is a
+collection of databases that are all administered by the same Unix user
+and managed by a single postmaster.
+
+<para>
+Creating a database system consists of creating the directories in which
+the database data will live, generating the shared catalog tables
+(tables that don't belong to any particular database), and
+creating the <literal>template1</literal>
+database. What is the <literal>template1</literal>
+database? When you create a database, <productname>Postgres</productname>
+does it by copying
+everything from the <literal>template1</literal>
+database. It contains catalog tables filled in for things like the
+builtin types.
+
+<para>
+After <application>initdb</application>
+creates the database, it completes the initialization by running
+<application>vacuum</application>, which resets some optimization parameters.
+
+<para>
+There are three ways to give parameters to <application>initdb</application>.
+
+First, you can use <application>initdb</application> command options.
+ Second, you can set environment
+variables before invoking <application>initdb</application>.
+Third, you can have a program called <application>postconfig</application>
+in your Unix command search path.
+<application>initdb</application> invokes that program and that program then writes
+<application>initdb</application> parameters to its standard output stream.
+This third option is not a common thing to do, however.
+
+<para>
+Command options always override parameters specified any other way.
+The values returned by <application>postconfig</application>
+override any environment variables, but your
+<application>postconfig</application>
+program may base its output on the environment variables if you want
+their values to be used.
+
+<para>
+The value that <application>postconfig</application>
+outputs must have the format
+<programlisting>
+ <replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ...
+</programlisting>
+
+It can output nothing if it doesn't want to supply any parameters.
+The <replaceable>var</replaceable> values are equal to
+the corresponding environment variable
+names. For example,
+<programlisting>
+PGDATA=/tmp/postgres_test
+</programlisting>
+has the
+same effect as invoking <application>initdb</application>
+with an environment variable called <envar>PGDATA</envar> whose value is
+<filename>/tmp/postgres_test</filename>.
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-INITLOCATION">
+<REFMETA>
+<REFENTRYTITLE>
+<application>initlocation</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>initlocation</application>
+</REFNAME>
+<REFPURPOSE>
+Create a secondary <productname>Postgres</productname> database storage area
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-02</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+initlocation [ --location=<replaceable class="parameter">altdir</replaceable> | -D <replaceable class="parameter">altdir</replaceable> ]
+ [ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ]
+ [ <replaceable class="parameter">altdir</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-INITLOCATION-1">
+<REFSECT2INFO>
+<DATE>1998-10-02</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<variablelist>
+<varlistentry>
+<term>
+--location=<replaceable class="parameter">altdir</replaceable>
+</term>
+<term>
+-D <replaceable class="parameter">altdir</replaceable>
+</term>
+<term>
+<replaceable class="parameter">altdir</replaceable>
+</term>
+<listitem>
+<para>
+Where in your Unix filesystem do you want alternate databases to go?
+The top level directory is called the <envar>PGDATA</envar> directory, so you
+might want to point your first alternate location at <envar>PGDATA2</envar>.
+
+<varlistentry>
+<term>
+--username=<replaceable class="parameter">name</replaceable>
+</term>
+<term>
+-u <replaceable class="parameter">name</replaceable>
+</term>
+<term>
+<envar>PGUSER</envar>
+</term>
+<listitem>
+<para>
+Who will be the Unix filesystem owner of this database storage area?
+The
+<productname>Postgres</productname> superuser is a Unix user
+who owns all files that store the database
+system and also owns the postmaster and backend processes that access them.
+Usually, this is the user who should run <application>initlocation</application>
+and who will thus have ownership of the directories and files.
+
+<note>
+<para>
+Only the Unix superuser can create a database system with a
+different user as the <productname>Postgres</productname> superuser.
+Specifying a user other than the <productname>Postgres</productname> superuser
+may lead to database security and data integrity problems. Refer to the
+<citetitle><productname>PostgreSQL</productname> Administrator's Guide</citetitle>
+ for more information.
+</note>
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-INITLOCATION-2">
+<REFSECT2INFO>
+<DATE>1998-09-26</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>initlocation</application> will create directories in
+the specified place.
+
+<variablelist>
+<varlistentry>
+<term>
+We are initializing the database area with username postgres (uid=500).
+This user will own all the files and must also own the server process.
+Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
+Creating Postgres database system directory <replaceable class="parameter">altdir</replaceable>
+</term>
+<listitem>
+<para>
+Successful completion.
+
+<varlistentry>
+<term>
+We are initializing the database area with username postgres (uid=500).
+This user will own all the files and must also own the server process.
+Creating Postgres database system directory /usr/local/src/testlocation
+mkdir: cannot make directory `<replaceable class="parameter">altdir</replaceable>': Permission denied
+</term>
+<listitem>
+<para>
+You do not have filesystem permission to write to the specified directory area.
+
+<varlistentry>
+<term>
+Valid username not given. You must specify the username for
+the Postgres superuser for the database system you are
+initializing, either with the --username option or by default
+to the USER environment variable.
+</term>
+<listitem>
+<para>
+The username which you have specified is not the
+<productname>Postgres</productname> superuser.
+
+<varlistentry>
+<term>
+Can't tell what username to use. You don't have the USER
+environment variable set to your username and didn't specify the
+--username option
+</term>
+<listitem>
+<para>
+Specify the <option>--username</option> command line option.
+
+</variablelist>
+
+<REFSECT1 ID="R1-APP-INITLOCATION-1">
+<REFSECT1INFO>
+<DATE>1998-09-26</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>initlocation</application>
+creates a new <productname>Postgres</productname> secondary database storage area.
+A secondary storage area contains a required tree of directories with
+the correct file permissions on those directories.
+
+<para>
+Creating a database storage area consists of creating the directories in which
+database data might live.
+
+<para>
+There are two kinds of arguments for <application>initlocation</application>.
+First, you can specify an environment variable (e.g. <envar>PGDATA2</envar>).
+This environment variable should be known to the backend for later use in
+<command>CREATE DATABASE/WITH LOCATION</command>
+ or
+<command>createdb -D <replaceable class="parameter">altdir</replaceable></command>.
+However, <emphasis>the backend daemon must have this variable in it's
+environment</emphasis> for this to succeed.
+
+Second, you may be able to specify an explicit
+absolute path to the top directory of the storage area. However,this second
+option is possible only if explicitly enabled during the
+<productname>Postgres</productname> installation. It is usually disabled
+ to alleviate security and data integrity concerns.
+
+<note>
+<para>
+<productname>Postgres</productname> will add <filename>/base/</filename>
+to the specified path to create the storage area.
+
+<para>
+The backend requires that any argument to <option>WITH LOCATION</option> which is
+in all uppercase and which has no path delimiters is an environment variable.
+</note>
+
+<REFSECT1 ID="R1-APP-INITLOCATION-2">
+<REFSECT1INFO>
+<DATE>1998-09-26</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To create a database in an alternate location, using an environment variable:
+
+<programlisting>
+% setenv PGDATA2 /opt/postgres/data
+
+% initlocation PGDATA2
+% createdb -D PGDATA2
+</programlisting>
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-PG-DUMP">
+<REFMETA>
+<REFENTRYTITLE>
+<application>pg_dump</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME id="pg-dump">
+<application>pg_dump</application>
+</REFNAME>
+<REFPURPOSE>
+Extract a <productname>Postgres</productname> database into a script file
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-04</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+pg_dump [ <replaceable class="parameter">dbname</replaceable> ]
+pg_dump [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ -t <replaceable class="parameter">table</replaceable> ]
+ [ -f <replaceable class="parameter">outputfile</replaceable> ]
+ [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
+ [ <replaceable class="parameter">dbname</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-PG-DUMP-1">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+<application>pg_dump</application> accepts the following command line arguments:
+
+<variablelist>
+<varlistentry>
+<term>
+<replaceable class="parameter">dbname</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the name of the database to be extracted.
+<replaceable class="parameter">dbname</replaceable>
+defaults to the value of the
+<envar>USER</envar>
+environment variable.
+
+<varlistentry>
+<term>
+-a
+</term>
+<listitem>
+<para>
+Dump out only the data, no schema (definitions).
+
+<varlistentry>
+<term>
+-d
+</term>
+<listitem>
+<para>
+Dump data as proper insert strings.
+
+<varlistentry>
+<term>
+-D
+</term>
+<listitem>
+<para>
+Dump data as inserts with attribute names
+
+<varlistentry>
+<term>
+-f <replaceable class="parameter">filename</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the output file. Defaults to <filename>stdout</filename>.
+
+<varlistentry>
+<term>
+-n
+</term>
+<listitem>
+<para>
+Suppress double quotes around identifiers unless absolutely necessary.
+This may cause trouble loading this dumped data if there are reserved words
+used for identifiers.
+
+<varlistentry>
+<term>
+-o
+</term>
+<listitem>
+<para>
+Dump object identifiers (<acronym>OID</acronym>s) for every table.
+
+<varlistentry>
+<term>
+-s
+</term>
+<listitem>
+<para>
+Dump out only the schema (definitions), no data.
+
+<varlistentry>
+<term>
+-t <replaceable class="parameter">table</replaceable>
+</term>
+<listitem>
+<para>
+Dump data for <replaceable class="parameter">table</replaceable> only.
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Use password authentication. Prompts for username and password.
+
+<varlistentry>
+<term>
+-v
+</term>
+<listitem>
+<para>
+Specifies verbose mode
+
+<varlistentry>
+<term>
+-z
+</term>
+<listitem>
+<para>
+Include ACLs (grant/revoke commands) and table ownership information.
+
+</variablelist>
+
+<para>
+<application>pg_dump</application> also accepts
+the following command line arguments for connection parameters:
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Use password authentication.
+Prompts for
+<replaceable class="parameter">username</replaceable>
+ and <replaceable class="parameter">password</replaceable>.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-PG-DUMP-2">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>pg_dump</application> will create a file or
+ write to <filename>stdout</filename>.
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+<listitem>
+<para>
+<application>pg_dump</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>.
+Contact your <productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
+<listitem>
+<para>
+You do not have permission to read the database.
+Contact your <productname>Postgres</productname> site administrator.
+
+</variablelist>
+
+<note>
+<para>
+<application>pg_dump</application> internally executes
+<command>SELECT</command> statements. If you have problems running
+<application>pg_dump</application>,
+make sure you are able to select information from the database using, for
+example, <application>psql</application>.
+</note>
+
+<REFSECT1 ID="R1-APP-PG-DUMP-1">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>pg_dump</application> is a utility for dumping out a
+<productname>Postgres</productname> database into a script file
+ containing query commands. The script
+files are in text format and can be used to reconstruct the database,
+even on other machines and other architectures.
+<application>pg_dump</application>
+will produce the queries necessary to re-generate all
+user-defined types, functions, tables, indices, aggregates, and
+operators. In addition, all the data is copied out in text format so
+that it can be readily copied in again, as well as imported into tools
+for editing.
+
+<para>
+<application>pg_dump</application>
+is useful for dumping out the contents of a database to move from one
+<productname>Postgres</productname> installation to another. After running
+<application>pg_dump</application>,
+ one should examine the output script file for any warnings, especially
+in light of the limitations listed below.
+
+<REFSECT1 ID="R1-APP-PG-DUMP-2">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Notes
+</TITLE>
+<PARA>
+<application>pg_dump</application> has a few limitations.
+The limitations mostly stem from
+difficulty in extracting certain meta-information from the system
+catalogs.
+
+<variablelist>
+<varlistentry>
+<term>
+rules and views
+<listitem>
+<para>
+<application>pg_dump</application>
+does not understand user-defined rules and views and
+will fail to dump them properly. (This is due to the fact that
+rules are stored as plans in the catalogs and not textually).
+
+<varlistentry>
+<term>
+partial indices
+<listitem>
+<para>
+<application>pg_dump</application>
+does not understand partial indices. The reason is
+the same as above; partial index predicates are stored as plans.
+
+<varlistentry>
+<term>
+large objects
+<listitem>
+<para>
+<application>pg_dump</application> does not handle large objects.
+Large objects are ignored and must be dealt with manually.
+
+</variablelist>
+
+<REFSECT1 ID="R1-APP-PG-DUMP-3">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To dump a database of the same name as the user:
+
+<programlisting>
+% pg_dump > db.out
+</programlisting>
+
+<para>
+To reload this database:
+
+<programlisting>
+psql -e database < db.out
+</programlisting>
+
+</REFENTRY>
--- /dev/null
+<REFENTRY ID="APP-PG-DUMPALL">
+<REFMETA>
+<REFENTRYTITLE>
+<application>pg_dumpall</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+<application>pg_dumpall</application>
+</REFNAME>
+<REFPURPOSE>
+Extract all <productname>Postgres</productname> databases into a script file
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-04</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+pg_dumpall
+pg_dumpall [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+ [ -a ] [ -d ] [ -D ] [ -o ] [ -s ] [ -u ] [ -v ] [ -z ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-PG-DUMPALL-1">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+<application>pg_dumpall</application> accepts the following command line arguments:
+
+<variablelist>
+<varlistentry>
+<term>
+-a
+</term>
+<listitem>
+<para>
+Dump out only the data, no schema (definitions).
+
+<varlistentry>
+<term>
+-d
+</term>
+<listitem>
+<para>
+Dump data as proper insert strings.
+
+<varlistentry>
+<term>
+-D
+</term>
+<listitem>
+<para>
+Dump data as inserts with attribute names
+
+<varlistentry>
+<term>
+-n
+</term>
+<listitem>
+<para>
+Suppress double quotes around identifiers unless absolutely necessary.
+This may cause trouble loading this dumped data if there are reserved words
+used for identifiers.
+
+<varlistentry>
+<term>
+-o
+</term>
+<listitem>
+<para>
+Dump object identifiers (<acronym>OID</acronym>s) for every table.
+
+<varlistentry>
+<term>
+-s
+</term>
+<listitem>
+<para>
+Dump out only the schema (definitions), no data.
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Use password authentication. Prompts for username and password.
+
+<varlistentry>
+<term>
+-v
+</term>
+<listitem>
+<para>
+Specifies verbose mode
+
+<varlistentry>
+<term>
+-z
+</term>
+<listitem>
+<para>
+Include ACLs (grant/revoke commands) and table ownership information.
+
+</variablelist>
+
+<para>
+<application>pg_dumpall</application> also accepts
+the following command line arguments for connection parameters:
+
+<variablelist>
+<varlistentry>
+<term>
+-h <replaceable class="parameter">host</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the hostname of the machine on which the
+<application>postmaster</application>
+is running. Defaults to using a local Unix domain socket
+ rather than an IP connection..
+
+<varlistentry>
+<term>
+-p <replaceable class="parameter">port</replaceable>
+</term>
+<listitem>
+<para>
+Specifies the Internet TCP/IP port or local Unix domain socket file
+extension on which the <application>postmaster</application>
+is listening for connections. The port number defaults to 5432,
+ or the value of the <envar>PGPORT</envar>
+environment variable (if set).
+
+<varlistentry>
+<term>
+-u
+</term>
+<listitem>
+<para>
+Use password authentication.
+Prompts for
+<replaceable class="parameter">username</replaceable>
+ and <replaceable class="parameter">password</replaceable>.
+
+</variablelist>
+
+<REFSECT2 ID="R2-APP-PG-DUMPALL-2">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>pg_dumpall</application> will create a file or
+ write to <filename>stdout</filename>.
+
+<variablelist>
+<varlistentry>
+<term>
+Connection to database 'template1' failed.
+connectDB() failed: Is the postmaster running and accepting connections
+ at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
+<listitem>
+<para>
+<application>pg_dumpall</application> could not attach to the
+<application>postmaster</application>
+process on the specified host and port. If you see this message,
+ensure that the <application>postmaster</application>
+is running on the proper host and that you have specified the proper
+port. If your site uses an authentication system, ensure that you
+have obtained the required authentication credentials.
+
+<varlistentry>
+<term>
+Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
+FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
+<listitem>
+<para>
+You do not have a valid entry in the relation <literal>pg_shadow</literal>
+and and will not be allowed to access <productname>Postgres</productname>.
+Contact your <productname>Postgres</productname> administrator.
+
+<varlistentry>
+<term>
+dumpSequence(<replaceable class="parameter">table</replaceable>): SELECT failed
+<listitem>
+<para>
+You do not have permission to read the database.
+Contact your <productname>Postgres</productname> site administrator.
+
+</variablelist>
+
+<note>
+<para>
+<application>pg_dumpall</application> internally executes
+<command>SELECT</command> statements. If you have problems running
+<application>pg_dumpall</application>,
+make sure you are able to select information from the database using, for
+example, <application>psql</application>.
+</note>
+
+<REFSECT1 ID="R1-APP-PG-DUMPALL-1">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<application>pg_dumpall</application>
+is a utility for dumping out all Postgres databases into one file.
+It also dumps the pg_shadow table, which is global to all databases.
+<application>pg_dumpall</application> includes in this file the proper commands
+to automatically create each dumped database before loading.
+
+<para>
+<application>pg_dumpall</application> takes all <application>pg_dump</application>
+ options, but <option>-f</option>, <option>-t</option> and
+<replaceable class="parameter">dbname</replaceable>
+should be omitted.
+
+<para>
+Refer to
+<xref linkend="app-pg-dump" endterm="pg-dump">
+ for more information on this capability.
+
+<REFSECT1 ID="R1-APP-PG-DUMPALL-2">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To dump all databases:
+
+<programlisting>
+% pg_dumpall -o > db.out
+</programlisting>
+
+<tip>
+<para>
+You can use most <application>pg_dump</application> options
+for <application>pg_dumpall</application>.
+</tip>
+
+<para>
+To reload this database:
+
+<programlisting>
+psql -e template1 < db.out
+</programlisting>
+
+<tip>
+<para>
+You can use most <application>psql</application> options
+when reloading.
+</tip>
+
+</REFENTRY>
<REFMISCINFO>Application</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
-<REFNAME>
+<REFNAME id="psql-ref">
<application>psql</application>
</REFNAME>
<REFPURPOSE>
Description
</TITLE>
<PARA>
-
<application>psql</application> is a character-based front-end to
<productname>Postgres</productname>.
It enables you to
--- /dev/null
+<REFENTRY ID="SQL-VACUUM-1">
+<REFMETA>
+<REFENTRYTITLE>
+VACUUM
+</REFENTRYTITLE>
+<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME>
+VACUUM
+</REFNAME>
+<REFPURPOSE>
+Clean and analyze a <productname>Postgres</productname> database
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-04</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+VACUUM [ VERBOSE ] [ ANALYZE ] [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> ]
+VACUUM [ VERBOSE ] ANALYZE [ <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> [ (<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE> [, ...] ) ] ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-SQL-VACUUM-1">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+VERBOSE
+<LISTITEM>
+<PARA>
+Prints a detailed vacuum activity report for each table.
+
+<VARLISTENTRY>
+<TERM>
+ANALYZE
+<LISTITEM>
+<PARA>
+Updates column statistics used by the optimizer to
+determine the most efficient way to execute a query.
+The statistics represent the disbursion of the data in each column.
+This information is valuable when several execution paths are possible.
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>
+<LISTITEM>
+<PARA>
+The name of a specific table to vacuum. Defaults to all tables.
+
+<VARLISTENTRY>
+<TERM>
+<REPLACEABLE CLASS="PARAMETER">column</REPLACEABLE>
+<LISTITEM>
+<PARA>
+The name of a specific column to analyze. Defaults to all columns.
+
+</VARIABLELIST>
+
+</REFSECT2>
+
+<REFSECT2 ID="R2-SQL-VACUUM-2">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+
+<VARIABLELIST>
+<VARLISTENTRY>
+<TERM>
+<ReturnValue>VACUUM</ReturnValue>
+</TERM>
+<LISTITEM>
+<PARA>
+The command has been accepted and the database is being cleaned.
+
+<VARLISTENTRY>
+<TERM>
+NOTICE: --Relation <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>--
+<LISTITEM>
+<PARA>
+The report header for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE>.
+
+<VARLISTENTRY>
+<TERM>
+NOTICE: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
+ Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
+ Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
+ Elapsed 0/0 sec.
+<LISTITEM>
+<PARA>
+The analysis for <REPLACEABLE CLASS="PARAMETER">table</REPLACEABLE> itself.
+
+<VARLISTENTRY>
+<TERM>
+NOTICE: Index <REPLACEABLE CLASS="PARAMETER">index</REPLACEABLE>: Pages 28;
+ Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+<LISTITEM>
+<PARA>
+The analysis for an index on the target table.
+
+</VARIABLELIST>
+
+</REFSECT2>
+</REFSYNOPSISDIV>
+
+<REFSECT1 ID="R1-SQL-VACUUM-1">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+<PARA>
+<command>VACUUM</command> serves two purposes in
+<productname>Postgres</productname> as both a means to reclaim storage and
+also a means to collect information for the optimizer.
+
+<para>
+<command>VACUUM</command> opens every class in the database,
+cleans out records from rolled back transactions, and updates statistics in the
+system catalogs. The statistics maintained include the number of
+tuples and number of pages stored in all classes.
+
+Running <command>VACUUM</command>
+periodically will increase the speed of the database in processing user queries.
+
+<REFSECT2 ID="R2-SQL-VACUUM-3">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Notes
+</TITLE>
+<PARA>
+The open database is target for <command>VACUUM</command>.
+
+<para>
+We recommend that active production databases be cleaned nightly, in order
+to keep statistics relatively current. The <command>VACUUM</command>
+query may be executed at any time, however. In particular, after
+copying a large class into <productname>Postgres</productname>
+or after deleting a large number of
+records, it may be a good idea to issue a <command>VACUUM</command>
+query. This will update the system catalogs with the results of all
+recent changes, and allow the <productname>Postgres</productname>
+query optimizer to make better choices in planning user queries.
+
+<para>
+If the server crashes during a <command>VACUUM</command> command,
+chances are it will leave a lock file hanging around.
+Attempts to re-run the <command>VACUUM</command> command
+result in an error message about the creation of a lock file. If you
+are sure <command>VACUUM</command> is not running,
+remove the <filename>pg_vlock</filename> file in your
+database directory
+(i.e. <filename><envar>PGDATA</envar>/base/dbname/pg_vlock</filename>).
+</PARA>
+
+</REFSECT2>
+
+<REFSECT1 ID="R1-SQL-VACUUM-2">
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+The following is an example from running <command>VACUUM</command> on a table
+in the regression database:
+
+<ProgramListing>
+regression=> vacuum verbose analyze onek;
+NOTICE: --Relation onek--
+NOTICE: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
+ Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
+ Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
+ Elapsed 0/0 sec.
+NOTICE: Index onek_stringu1: Pages 28; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_hundred: Pages 12; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique2: Pages 19; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique1: Pages 17; Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
+NOTICE: Rel onek: Pages: 98 --> 25; Tuple(s) moved: 1000. Elapsed 0/1 sec.
+NOTICE: Index onek_stringu1: Pages 28; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_hundred: Pages 12; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique2: Pages 19; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+NOTICE: Index onek_unique1: Pages 17; Tuples 1000: Deleted 1000. Elapsed 0/0 sec.
+VACUUM
+</ProgramListing>
+
+</REFSECT1>
+
+<REFSECT1 ID="R1-SQL-VACUUM-3">
+<TITLE>
+Compatibility
+</TITLE>
+<PARA>
+
+<REFSECT2 ID="R2-SQL-VACUUM-4">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+SQL92
+</TITLE>
+<PARA>
+There is no <COMMAND>VACUUM</COMMAND> statement in SQL92.
+
+</REFENTRY>
projects / postgresql / commitdiff