<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.31 2003/08/31 17:32:24 petere Exp $
PostgreSQL documentation
-->

<refentry id="APP-VACUUMDB">
 <refmeta>
  <refentrytitle id="APP-VACUUMDB-TITLE"><application>vacuumdb</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname id="vacuumdb">vacuumdb</refname>
  <refpurpose>garbage-collect and analyze a <productname>PostgreSQL</productname> database</refpurpose>
 </refnamediv>

 <indexterm zone="app-vacuumdb">
  <primary>vacuumdb</primary>
 </indexterm>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>vacuumdb</command>
   <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
   <group><arg>--full</arg><arg>-f</arg></group>
   <group><arg>--verbose</arg><arg>-v</arg></group>
   <group><arg>--analyze</arg><arg>-z</arg></group>
   <arg>--table | -t <replaceable>table</replaceable>
    <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
   </arg>
   <arg><replaceable>dbname</replaceable></arg>
   <sbr>
   <command>vacuumdb</command>
   <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
   <group><arg>--all</arg><arg>-a</arg></group>
   <group><arg>--full</arg><arg>-f</arg></group>
   <group><arg>--verbose</arg><arg>-v</arg></group>
   <group><arg>--analyze</arg><arg>-z</arg></group>
  </cmdsynopsis>
 </refsynopsisdiv>
 

 <refsect1>
  <title>Description</title>

  <para>
   <application>vacuumdb</application> is a utility for cleaning a
   <productname>PostgreSQL</productname> database.
   <application>vacuumdb</application> will also generate internal statistics
   used by the <productname>PostgreSQL</productname> query optimizer.
  </para>

  <para>
   <application>vacuumdb</application> is a wrapper around the SQL
   command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">.
   There is no effective difference between vacuuming databases via
   this or other methods.  The database server must be running at the
   targeted host.  Also, any default settings and environment
   variables used by the <application>libpq</application> front-end
   library will apply.
  </para>


  <para>
   <application>vacuumdb</application> might need to connect several
   times to the <productname>PostgreSQL</productname> server, asking
   for a password each time. It is convenient to have a
   <filename>$HOME/.pgpass</> file in such cases. See <xref
   linkend="libpq-pgpass"> for more information.
  </para>

 </refsect1>


 <refsect1>
  <title>Options</title>

   <para>
    <application>vacuumdb</application> accepts the following command-line arguments:
    
    <variablelist>
     <varlistentry>
      <term><option>-a</option></term>
      <term><option>--all</option></term>
      <listitem>
       <para>
	Vacuum all databases.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
      <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></option></term>
      <listitem>
       <para>
	Specifies the name of the database to be cleaned or analyzed.
	If this is not specified and <option>-a</option> (or
	<option>--all</option>) is not used, the database name is read
	from the environment variable <envar>PGDATABASE</envar>.  If
	that is not set, the user name specified for the connection is
	used.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-e</></term>
      <term><option>--echo</></term>
      <listitem>
       <para>
        Echo the commands that <application>vacuumdb</application> generates
	and sends to the server.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-f</option></term>
      <term><option>--full</option></term>
      <listitem>
       <para>
        Perform <quote>full</quote> vacuuming.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-q</></term>
      <term><option>--quiet</></term>
      <listitem>
       <para>
        Do not display a response.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></term>
      <term><option>--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></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, you probably have to escape the parentheses
         from the shell.  (See examples below.)
        </para>
       </tip>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-v</option></term>
      <term><option>--verbose</option></term>
      <listitem>
       <para>
	Print detailed information during processing.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-z</option></term>
      <term><option>--analyze</option></term>
      <listitem>
       <para>
	Calculate statistics for use by the optimizer.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    <application>vacuumdb</application> also accepts 
    the following command-line arguments for connection parameters:
    
    <variablelist>
     <varlistentry>
      <term><option>-h <replaceable class="parameter">host</replaceable></></term>
      <term><option>--host <replaceable class="parameter">host</replaceable></></term>
      <listitem>
       <para>
	Specifies the host name of the machine on which the 
	server
	is running.  If the value begins with a slash, it is used 
	as the directory for the Unix domain socket.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-p <replaceable class="parameter">port</replaceable></></term>
      <term><option>--port <replaceable class="parameter">port</replaceable></></term>
      <listitem>
       <para>
	Specifies the TCP port or local Unix domain socket file 
	extension on which the server
	is listening for connections.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-U <replaceable class="parameter">username</replaceable></></term>
      <term><option>--username <replaceable class="parameter">username</replaceable></></term>
      <listitem>
       <para>
        User name to connect as
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-W</></term>
      <term><option>--password</></term>
      <listitem>
       <para>
        Force password prompt.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
 </refsect1>


 <refsect1>
  <title>Diagnostics</title>

   <para>
    <variablelist>
     <varlistentry>
      <term><computeroutput>VACUUM</computeroutput></term>
      <listitem>
       <para>
        The database was successfully vacuumed.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>vacuumdb: Vacuum failed.</computeroutput></term>
      <listitem>
       <para>
        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"> for a detailed
        discussion of error messages and potential problems.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATABASE</envar></term>
    <term><envar>PGHOST</envar></term>
    <term><envar>PGPORT</envar></term>
    <term><envar>PGUSER</envar></term>

    <listitem>
     <para>
      Default connection parameters
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>


 <refsect1>
  <title>Examples</title>

   <para>
    To clean the database <literal>test</literal>:
<screen>
<prompt>$ </prompt><userinput>vacuumdb test</userinput>
</screen>
   </para>

   <para>
    To clean and analyze for the optimizer a database named
    <literal>bigdb</literal>:
<screen>
<prompt>$ </prompt><userinput>vacuumdb --analyze bigdb</userinput>
</screen>
   </para>

   <para>
    To clean a single table
    <literal>foo</literal> in a database named
    <literal>xyzzy</literal>, and analyze a single column
    <literal>bar</literal> of the table for the optimizer:
<screen>
<prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy</userinput>
</screen>
   </para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
  </simplelist>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
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:
-->
