@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.5 1999/07/22 15:09:15 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.6 1999/12/07 22:41:41 momjian Exp $
Postgres documentation
-->
@ -15,23 +15,21 @@ Postgres documentation
<application>vacuumdb</application>
</refname>
<refpurpose>
Clean and analyze a <productname>Postgres </productname> database
Clean and analyze a <productname>PostgreSQL </productname> database
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1998-10 -04</date>
<date>1999-12 -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> ]
vacuumdb [ <replaceable class="parameter">connection options</replaceable> ] [ --analyze | -z ] [ --verbose | -v ]
[ --table '<replaceable class="parameter">table</replaceable> [ ( <replaceable class="parameter">column</replaceable> [,...] ) ]' ] [ [-d] <replaceable class="parameter">dbname</replaceable> ]
</synopsis>
<refsect2 id="R2-APP-VACUUMDB-1">
<refsect2info>
<date>1998-10 -04</date>
<date>1999-12 -04</date>
</refsect2info>
<title>
Inputs
@ -41,21 +39,16 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
<variablelist>
<varlistentry>
<term><replaceable class="parameter">dbname</replaceable></term>
<term>[-d, --dbname] <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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--analyze</term>
<term>-z</term>
<term>-z, --analyze</term>
<listitem>
<para>
Calculate statistics on the database for use by the optimizer.
@ -64,8 +57,7 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
</varlistentry>
<varlistentry>
<term>--verbose</term>
<term>-v</term>
<term>-v, --verbose</term>
<listitem>
<para>
Print detailed information during processing.
@ -74,14 +66,19 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
</varlistentry>
<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>
<term>-t, --table <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.
</para>
<tip>
<para>
If you specify columns to vacuum, you probably have to escape the parentheses
from the shell.
</para>
</tip>
</listitem>
</varlistentry>
@ -94,38 +91,60 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
<variablelist>
<varlistentry>
<term>-h <replaceable class="parameter">host</replaceable></term>
<term>-h, --host <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..
is running.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-p <replaceable class="parameter">port</replaceable></term>
<term>-p, --port <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).
is listening for connections.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-U, --username <replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
Username to connect as.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-W, --password</term>
<listitem>
<para>
Force password prompt.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-e, --echo</term>
<listitem>
<para>
Echo the commands that <application>vacuumdb</application> generates
and sends to the backend.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-u</term>
<term>-q, --q uiet </term>
<listitem>
<para>
Use password authentication.
Prompts for
<replaceable class="parameter">username</replaceable>
and <replaceable class="parameter">password</replaceable>.
Do not display a response.
</para>
</listitem>
</varlistentry>
@ -135,79 +154,46 @@ vacuumdb [ -h <replaceable class="parameter">host</replaceable> ] [ -p <replacea
<refsect2 id="R2-APP-VACUUMDB-2">
<refsect2info>
<date>1998-10 -04</date>
<date>1999-12 -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><computeroutput>
ERROR: Can't vacuum columns, only tables. You can 'vacuum analyze' columns.
vacuumdb: database vacuum failed on <replaceable class="parameter">dbname</replaceable>.
</computeroutput></term>
<term><computeroutput>VACUUM</computeroutput></term>
<listitem>
<para>
The non-analyze mode requires cleaning full tables or databases.
Individual columns may be specified only when analyzing a specific table.
Everything went well.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
Connection to database 'template1' failed.
connectDB() failed: Is the postmaster running and accepting connections
at 'UNIX Socket' on port '<replaceable class="parameter">port</replaceable>'?
</computeroutput></term>
<term><computeroutput>vacuumdb: Vacuum failed.</computeroutput></term>
<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.
Something went wrong. <application>vacuumdb</application> is only a wrapper
script. See <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">
and <xref linkend="APP-PSQL" endterm="APP-PSQL-title"> for a detailed
discussion of error messages and potential problems.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>
Connection to database '<replaceable class="parameter">dbname</replaceable>' failed.
FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>' is not in 'pg_shadow'
</computeroutput></term>
<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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<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>.
</para>
</note>
<para>
</para>
</refsect2>
</refsynopsisdiv>
<refsect1 id="R1-APP-VACUUMDB-1">
<refsect1info>
<date>1998-10 -04</date>
<date>1999-12-04</date>
</refsect1info>
<title>
Description
@ -215,25 +201,26 @@ FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>
<para>
<application>vacuumdb</application> is a utility for cleaning a
<productname>Postgres </productname> database.
<productname>PostgreSQL </productname> database.
<application>vacuumdb</application> will also generate internal statistics
used by the <productname>Postgres</productname> query optimizer.
</para>
</refsect1>
<refsect1 id="R1-APP-VACUUMDB-2">
<refsect1info>
<date>1998-10-04</date>
</refsect1info>
<title>
Notes
</title>
<para>
See <xref endterm="sql-vacuum-title" linkend="sql-vacuum-title"> for more details.
<application>vacuumdb</application> is a shell script wrapper around the
backend command
<xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title"> via
the <productname>PostgreSQL</productname> interactive terminal
<xref linkend="APP-PSQL" endterm="APP-PSQL-title">. There is no effective
difference between vacuuming databases via this or other methods.
<application>psql</application> must be found by the script and
a database server must be running at the targeted host. Also, any default
settings and environment variables available to <application>psql</application>
and the <application>libpq</application> front-end library do apply.
</para>
</refsect1>
<refsect1 id="R1-APP-VACUUMDB-3">
<refsect1info>
<date>1998-10-04</date>
@ -241,29 +228,29 @@ FATAL 1: SetUserId: user '<replaceable class="parameter">username</replaceable>
<title>
Usage
</title>
<para>
To clean a database of the same name as the user:
<programlisting>
% vacuumdb
</programlisting>
To clean the database <literal>test</literal>:
<programlisting>
$ vacuumdb test
</programlisting>
</para>
<para>
To analyze a database named <literal>bigdb</literal> for the optimizer:
<programlisting>
% vacuumdb --analyze bigdb
</programlisting>
<programlisting>
$ vacuumdb --analyze bigdb
</programlisting>
</para>
<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>
<programlisting>
$ vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy
</programlisting>
</para>
</refsect1>
</refentry>