doc/src/sgml/ref/vacuumdb.sgml

   1 <!--
   2 $PostgreSQL$
   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 <application>vacuumdb</application> to prompt for a
 213         password before connecting to a database.
 214        </para>
 215
 216        <para>
 217         This option is never essential, since
 218         <application>vacuumdb</application> will automatically prompt
 219         for a password if the server demands password authentication.
 220         However, <application>vacuumdb</application> will waste a
 221         connection attempt finding out that the server wants a password.
 222         In some cases it is worth typing <option>-W</> to avoid the extra
 223         connection attempt.
 224        </para>
 225       </listitem>
 226      </varlistentry>
 227     </variablelist>
 228    </para>
 229  </refsect1>
 230
 231
 232  <refsect1>
 233   <title>Environment</title>
 234
 235   <variablelist>
 236    <varlistentry>
 237     <term><envar>PGDATABASE</envar></term>
 238     <term><envar>PGHOST</envar></term>
 239     <term><envar>PGPORT</envar></term>
 240     <term><envar>PGUSER</envar></term>
 241
 242     <listitem>
 243      <para>
 244       Default connection parameters
 245      </para>
 246     </listitem>
 247    </varlistentry>
 248   </variablelist>
 249
 250   <para>
 251    This utility, like most other <productname>PostgreSQL</> utilities,
 252    also uses the environment variables supported by <application>libpq</>
 253    (see <xref linkend="libpq-envars">).
 254   </para>
 255
 256  </refsect1>
 257
 258
 259  <refsect1>
 260   <title>Diagnostics</title>
 261
 262   <para>
 263    In case of difficulty, see <xref linkend="SQL-VACUUM"
 264    endterm="sql-vacuum-title"> and <xref linkend="APP-PSQL"> for
 265    discussions of potential problems and error messages.
 266    The database server must be running at the
 267    targeted host.  Also, any default connection settings and environment
 268    variables used by the <application>libpq</application> front-end
 269    library will apply.
 270   </para>
 271
 272  </refsect1>
 273
 274
 275  <refsect1>
 276   <title>Notes</title>
 277
 278   <para>
 279    <application>vacuumdb</application> might need to connect several
 280    times to the <productname>PostgreSQL</productname> server, asking
 281    for a password each time. It is convenient to have a
 282    <filename>~/.pgpass</> file in such cases. See <xref
 283    linkend="libpq-pgpass"> for more information.
 284   </para>
 285  </refsect1>
 286
 287  <refsect1>
 288   <title>Examples</title>
 289
 290    <para>
 291     To clean the database <literal>test</literal>:
 292 <screen>
 293 <prompt>$ </prompt><userinput>vacuumdb test</userinput>
 294 </screen>
 295    </para>
 296
 297    <para>
 298     To clean and analyze for the optimizer a database named
 299     <literal>bigdb</literal>:
 300 <screen>
 301 <prompt>$ </prompt><userinput>vacuumdb --analyze bigdb</userinput>
 302 </screen>
 303    </para>
 304
 305    <para>
 306     To clean a single table
 307     <literal>foo</literal> in a database named
 308     <literal>xyzzy</literal>, and analyze a single column
 309     <literal>bar</literal> of the table for the optimizer:
 310 <screen>
 311 <prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table 'foo(bar)' xyzzy</userinput>
 312 </screen>
 313    </para>
 314
 315  </refsect1>
 316
 317  <refsect1>
 318   <title>See Also</title>
 319
 320   <simplelist type="inline">
 321    <member><xref linkend="sql-vacuum" endterm="sql-vacuum-title"></member>
 322   </simplelist>
 323  </refsect1>
 324
 325 </refentry>