doc/src/sgml/ref/vacuumdb.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.41 2007/06/04 10:02:40 petere Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-VACUUMDB">
   7  <refmeta>
   8   <refentrytitle id="APP-VACUUMDB-TITLE"><application>vacuumdb</application></refentrytitle>
   9   <manvolnum>1</manvolnum>
  10   <refmiscinfo>Application</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname id="vacuumdb">vacuumdb</refname>
  15   <refpurpose>garbage-collect and analyze a <productname>PostgreSQL</productname> database</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="app-vacuumdb">
  19   <primary>vacuumdb</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>vacuumdb</command>
  25    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  26    <group><arg>--full</arg><arg>-f</arg></group>
  27    <group><arg>--verbose</arg><arg>-v</arg></group>
  28    <group><arg>--analyze</arg><arg>-z</arg></group>
  29    <arg>--table | -t <replaceable>table</replaceable>
  30     <arg>( <replaceable class="parameter">column</replaceable> [,...] )</arg>
  31    </arg>
  32    <arg><replaceable>dbname</replaceable></arg>
  33    <sbr>
  34    <command>vacuumdb</command>
  35    <arg rep="repeat"><replaceable>connection-options</replaceable></arg>
  36    <group><arg>--all</arg><arg>-a</arg></group>
  37    <group><arg>--full</arg><arg>-f</arg></group>
  38    <group><arg>--verbose</arg><arg>-v</arg></group>
  39    <group><arg>--analyze</arg><arg>-z</arg></group>
  40   </cmdsynopsis>
  41  </refsynopsisdiv>
  42
  43
  44  <refsect1>
  45   <title>Description</title>
  46
  47   <para>
  48    <application>vacuumdb</application> is a utility for cleaning a
  49    <productname>PostgreSQL</productname> database.
  50    <application>vacuumdb</application> will also generate internal statistics
  51    used by the <productname>PostgreSQL</productname> query optimizer.
  52   </para>
  53
  54   <para>
  55    <application>vacuumdb</application> is a wrapper around the SQL
  56    command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">.
  57    There is no effective difference between vacuuming databases via
  58    this utility and via other methods for accessing the server.
  59   </para>
  60
  61  </refsect1>
  62
  63
  64  <refsect1>
  65   <title>Options</title>
  66
  67    <para>
  68     <application>vacuumdb</application> accepts the following command-line arguments:
  69
  70     <variablelist>
  71      <varlistentry>
  72       <term><option>-a</option></term>
  73       <term><option>--all</option></term>
  74       <listitem>
  75        <para>
  76         Vacuum all databases.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80
  81      <varlistentry>
  82       <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
  83       <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></option></term>
  84       <listitem>
  85        <para>
  86         Specifies the name of the database to be cleaned or analyzed.
  87         If this is not specified and <option>-a</option> (or
  88         <option>--all</option>) is not used, the database name is read
  89         from the environment variable <envar>PGDATABASE</envar>.  If
  90         that is not set, the user name specified for the connection is
  91         used.
  92        </para>
  93       </listitem>
  94      </varlistentry>
  95
  96      <varlistentry>
  97       <term><option>-e</></term>
  98       <term><option>--echo</></term>
  99       <listitem>
 100        <para>
 101         Echo the commands that <application>vacuumdb</application> generates
 102         and sends to the server.
 103        </para>
 104       </listitem>
 105      </varlistentry>
 106
 107      <varlistentry>
 108       <term><option>-f</option></term>
 109       <term><option>--full</option></term>
 110       <listitem>
 111        <para>
 112         Perform <quote>full</quote> vacuuming.
 113        </para>
 114       </listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><option>-q</></term>
 119       <term><option>--quiet</></term>
 120       <listitem>
 121        <para>
 122         Do not display progress messages.
 123        </para>
 124       </listitem>
 125      </varlistentry>
 126
 127      <varlistentry>
 128       <term><option>-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></term>
 129       <term><option>--table <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></term>
 130       <listitem>
 131        <para>
 132         Clean or analyze <replaceable class="parameter">table</replaceable> only.
 133         Column names can be specified only in conjunction with
 134         the <option>--analyze</option> option.
 135        </para>
 136        <tip>
 137         <para>
 138          If you specify columns, you probably have to escape the parentheses
 139          from the shell.  (See examples below.)
 140         </para>
 141        </tip>
 142       </listitem>
 143      </varlistentry>
 144
 145      <varlistentry>
 146       <term><option>-v</option></term>
 147       <term><option>--verbose</option></term>
 148       <listitem>
 149        <para>
 150         Print detailed information during processing.
 151        </para>
 152       </listitem>
 153      </varlistentry>
 154
 155      <varlistentry>
 156       <term><option>-z</option></term>
 157       <term><option>--analyze</option></term>
 158       <listitem>
 159        <para>
 160         Calculate statistics for use by the optimizer.
 161        </para>
 162       </listitem>
 163      </varlistentry>
 164     </variablelist>
 165    </para>
 166
 167    <para>
 168     <application>vacuumdb</application> also accepts
 169     the following command-line arguments for connection parameters:
 170
 171     <variablelist>
 172      <varlistentry>
 173       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 174       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 175       <listitem>
 176        <para>
 177         Specifies the host name of the machine on which the
 178         server
 179         is running.  If the value begins with a slash, it is used
 180         as the directory for the Unix domain socket.
 181        </para>
 182       </listitem>
 183      </varlistentry>
 184
 185      <varlistentry>
 186       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 187       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 188       <listitem>
 189        <para>
 190         Specifies the TCP port or local Unix domain socket file
 191         extension on which the server
 192         is listening for connections.
 193        </para>
 194       </listitem>
 195      </varlistentry>
 196
 197      <varlistentry>
 198       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 199       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 200       <listitem>
 201        <para>
 202         User name to connect as
 203        </para>
 204       </listitem>
 205      </varlistentry>
 206
 207      <varlistentry>
 208       <term><option>-W</></term>
 209       <term><option>--password</></term>
 210       <listitem>
 211        <para>
 212         Force password prompt.
 213        </para>
 214       </listitem>
 215      </varlistentry>
 216     </variablelist>
 217    </para>
 218  </refsect1>
 219
 220
 221  <refsect1>
 222   <title>Environment</title>
 223
 224   <variablelist>
 225    <varlistentry>
 226     <term><envar>PGDATABASE</envar></term>
 227     <term><envar>PGHOST</envar></term>
 228     <term><envar>PGPORT</envar></term>
 229     <term><envar>PGUSER</envar></term>
 230
 231     <listitem>
 232      <para>
 233       Default connection parameters
 234      </para>
 235     </listitem>
 236    </varlistentry>
 237   </variablelist>
 238
 239   <para>
 240    This utility, like most other <productname>PostgreSQL</> utilities,
 241    also uses the environment variables supported by <application>libpq</>
 242    (see <xref linkend="libpq-envars">).
 243   </para>
 244
 245  </refsect1>
 246
 247
 248  <refsect1>
 249   <title>Diagnostics</title>
 250
 251   <para>
 252    In case of difficulty, see <xref linkend="SQL-VACUUM"
 253    endterm="sql-vacuum-title"> and <xref linkend="APP-PSQL"> for
 254    discussions of potential problems and error messages.
 255    The database server must be running at the
 256    targeted host.  Also, any default connection settings and environment
 257    variables used by the <application>libpq</application> front-end
 258    library will apply.
 259   </para>
 260
 261  </refsect1>
 262
 263
 264  <refsect1>
 265   <title>Notes</title>
 266
 267   <para>
 268    <application>vacuumdb</application> might need to connect several
 269    times to the <productname>PostgreSQL</productname> server, asking
 270    for a password each time. It is convenient to have a
 271    <filename>~/.pgpass</> file in such cases. See <xref
 272    linkend="libpq-pgpass"> for more information.
 273   </para>
 274  </refsect1>
 275
 276  <refsect1>
 277   <title>Examples</title>
 278
 279    <para>
 280     To clean the database <literal>test</literal>:
 281 <screen>
 282 <prompt>$ </prompt><userinput>vacuumdb test</userinput>
 283 </screen>
 284    </para>
 285
 286    <para>
 287     To clean and analyze for the optimizer a database named
 288     <literal>bigdb</literal>:
 289 <screen>
 290 <prompt>$ </prompt><userinput>vacuumdb --analyze bigdb</userinput>
 291 </screen>
 292    </para>
 293
 294    <para>
 295     To clean a single table
 296     <literal>foo</literal> in a database named
 297     <literal>xyzzy</literal>, and analyze a single column
 298     <literal>bar</literal> of the table for the optimizer:
 299 <screen>
 300 <prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy</userinput>
 301 </screen>
 302    </para>
 303
 304  </refsect1>
 305
 306  <refsect1>
 307   <title>See Also</title>
 308
 309   <simplelist type="inline">
 310    <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
 311   </simplelist>
 312  </refsect1>
 313
 314 </refentry>