<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.14 2001/05/07 00:43:15 tgl Exp $
Postgres documentation
-->

<refentry id="SQL-VACUUM">
 <refmeta>
  <refentrytitle id="sql-vacuum-title">
   VACUUM
  </refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>
   VACUUM
  </refname>
  <refpurpose>
   Clean and optionally analyze a <productname>Postgres</productname> database
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>2001-05-04</date>
  </refsynopsisdivinfo>
  <synopsis>
VACUUM [ VERBOSE ] [ <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</term>
      <listitem>
       <para>
	Prints a detailed vacuum activity report for each table.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>ANALYZE</term>
      <listitem>
       <para>
	Updates statistics used by the optimizer to
	determine the most efficient way to execute a query.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">table</replaceable></term>
      <listitem>
       <para>
	The name of a specific table to vacuum. Defaults to all tables.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="PARAMETER">column</replaceable></term>
      <listitem>
       <para>
	The name of a specific column to analyze. Defaults to all columns.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-VACUUM-2">
   <refsect2info>
    <date>1998-10-04</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>
<returnvalue>VACUUM</returnvalue>
       </computeroutput></term>
      <listitem>
       <para>
	The command is complete.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
NOTICE:  --Relation <replaceable class="PARAMETER">table</replaceable>--
       </computeroutput></term>
      <listitem>
       <para>
	The report header for <replaceable class="PARAMETER">table</replaceable>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
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.
       </computeroutput></term>
      <listitem>
       <para>
	The analysis for <replaceable class="PARAMETER">table</replaceable> itself.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>
NOTICE:  Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
         Tuples 1000: Deleted 3000. Elapsed 0/0 sec.
       </computeroutput></term>
      <listitem>
       <para>
	The analysis for an index on the target table.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-VACUUM-1">
  <refsect1info>
   <date>1998-10-04</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>VACUUM</command> reclaims storage occupied by deleted tuples.
   In normal <productname>Postgres</productname> operation, tuples that
   are DELETEd or obsoleted by UPDATE are not physically removed from
   their table; they remain present until a <command>VACUUM</command> is
   done.  Therefore it's necessary to do <command>VACUUM</command>
   periodically, especially on frequently-updated tables.
  </para>

  <para>
   With no parameter, <command>VACUUM</command> processes every table in the
   current database.  With a parameter, <command>VACUUM</command> processes
   only that table.
  </para>

  <para>
   <command>VACUUM ANALYZE</command> performs a <command>VACUUM</command>
   and then an <command>ANALYZE</command> for each selected table.  This
   is a handy combination form for routine maintenance scripts.  See
   <xref linkend="sql-analyze" endterm="sql-analyze-title">
   for more details about its processing.
  </para>

  <refsect2 id="R2-SQL-VACUUM-3">
   <refsect2info>
    <date>1998-10-04</date>
   </refsect2info>
   <title>
    Notes
   </title>

   <para>
    We recommend that active production databases be
    <command>VACUUM</command>-ed nightly, in order to remove
    expired rows. After copying a large table into
    <productname>Postgres</productname> or after deleting a large number
    of records, it may be a good idea to issue a <command>VACUUM
    ANALYZE</command> command for the affected table. 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>

  </refsect2>
 </refsect1>

 <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>
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-VACUUM-3">
  <title>
   Compatibility
  </title>

  <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 <acronym>SQL92</acronym>.
   </para>
  </refsect2>
 </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:
-->
