Add reference page for new vacuumdb utility.

doc/src/sgml/ref/allfiles.sgml

@@ -121,3 +121,4 @@
 <!entity pgDumpall         system "pg_dumpall.sgml">
 <!entity pgUpgrade          system "pg_upgrade.sgml">
 <!entity psqlRef            system "psql-ref.sgml">
+<!entity vacuumdb           system "vacuumdb.sgml">

doc/src/sgml/ref/commands.sgml

@@ -101,6 +101,7 @@ This is reference information for the
 &pgDump;
 &pgDumpall;
 &psqlRef;
+&vacuumdb;
 
 </chapter>
 

doc/src/sgml/ref/vacuumdb.sgml

@@ -0,0 +1,255 @@
+<REFENTRY ID="APP-VACUUMDB">
+<REFMETA>
+<REFENTRYTITLE>
+<application>vacuumdb</application>
+</REFENTRYTITLE>
+<REFMISCINFO>Application</REFMISCINFO>
+</REFMETA>
+<REFNAMEDIV>
+<REFNAME id="vacuumdb">
+<application>vacuumdb</application>
+</REFNAME>
+<REFPURPOSE>
+Clean and analyze a <productname>Postgres</productname> database
+</REFPURPOSE>
+<REFSYNOPSISDIV>
+<REFSYNOPSISDIVINFO>
+<DATE>1998-10-04</DATE>
+</REFSYNOPSISDIVINFO>
+<SYNOPSIS>
+vacuumdb [ --analyze | -z ] [ --verbose | -v ] [ <replaceable class="parameter">dbname</replaceable> ]
+vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+    [ --table '<replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [,...] ) ]' ]
+    [ <replaceable class="parameter">dbname</replaceable> ]
+</SYNOPSIS>
+
+<REFSECT2 ID="R2-APP-VACUUMDB-1">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Inputs
+</TITLE>
+<PARA>
+<application>vacuumdb</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 cleaned or analyzed.
+<replaceable class="parameter">dbname</replaceable>
+defaults to the value of the
+<envar>USER</envar>
+environment variable.
+
+<varlistentry>
+<term>
+--analyze
+</term>
+<term>
+-z
+</term>
+<listitem>
+<para>
+Calculate statistics on the database for use by the optimizer.
+
+<varlistentry>
+<term>
+--verbose
+</term>
+<term>
+-v
+</term>
+<listitem>
+<para>
+Print detailed information during processing.
+
+<varlistentry>
+<term>
+--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
+</term>
+<term>
+-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]
+</term>
+<listitem>
+<para>
+Clean or analyze <replaceable class="parameter">table</replaceable> only.
+Column names may be specified only in conjunction with
+ the <option>--analyze</option> option.
+
+</variablelist>
+
+<para>
+<application>vacuumdb</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-VACUUMDB-2">
+<REFSECT2INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT2INFO>
+<TITLE>
+Outputs
+</TITLE>
+<PARA>
+<application>vacuumdb</application> executes a <command>VACUUM</command> command
+on the specified database, so has not explicit external output.
+
+<variablelist>
+<varlistentry>
+<term>
+ERROR:  Can't vacuum columns, only tables.  You can 'vacuum analyze' columns.
+vacuumdb: database vacuum failed on <replaceable class="parameter">dbname</replaceable>.
+<listitem>
+<para>
+The non-analyze mode requires cleaning full tables or databases.
+Individual columns may be specified only when analyzing a specific table.
+
+<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>vacuumdb</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.
+
+</variablelist>
+
+<note>
+<para>
+<application>vacuumdb</application> internally executes a
+<command>VACUUM</command> <acronym>SQL</acronym> statement. 
+If you have problems running <application>vacuumdb</application>,
+make sure you are able to run <command>VACUUM</command> on the database using, for
+example, <application>psql</application>.
+</note>
+
+<REFSECT1 ID="R1-APP-VACUUMDB-1">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Description
+</TITLE>
+
+<PARA>
+<application>vacuumdb</application> is a utility for cleaning a
+<productname>Postgres</productname> database.
+<application>vacuumdb</application> will also generate internal statistics
+used by the <productname>Postgres</productname> query optimizer.
+
+<REFSECT1 ID="R1-APP-VACUUMDB-2">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Notes
+</TITLE>
+
+<para>
+See <xref linkend="vacuum" endterm="vacuum"> for more details.
+
+<REFSECT1 ID="R1-APP-VACUUMDB-3">
+<REFSECT1INFO>
+<DATE>1998-10-04</DATE>
+</REFSECT1INFO>
+<TITLE>
+Usage
+</TITLE>
+<PARA>
+To clean a database of the same name as the user:
+
+<programlisting>
+% vacuumdb
+</programlisting>
+
+<para>
+To analyze a database named <literal>bigdb</literal> for the optimizer:
+
+<programlisting>
+% vacuumdb --analyze bigdb
+</programlisting>
+
+<para>
+To analyze a single column <literal>bar</literal> in table <literal>foo</literal>
+ in a database named <literal>xyzzy</literal> for the optimizer:
+
+<programlisting>
+% vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy
+</programlisting>
+
+</REFENTRY>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->