granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/vacuumdb.sgml

   1 <!--
   2 doc/src/sgml/ref/vacuumdb.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-VACUUMDB">
   7  <indexterm zone="app-vacuumdb">
   8   <primary>vacuumdb</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>vacuumdb</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname id="vacuumdb">vacuumdb</refname>
  19   <refpurpose>garbage-collect and analyze a <productname>PostgreSQL</productname> database</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>vacuumdb</command>
  25    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  26    <arg rep="repeat"><replaceable>option</replaceable></arg>
  27
  28    <arg choice="plain" rep="repeat">
  29     <arg choice="opt">
  30      <group choice="plain">
  31       <arg choice="plain"><option>--table</option></arg>
  32       <arg choice="plain"><option>-t</option></arg>
  33      </group>
  34      <replaceable>table</replaceable>
  35      <arg choice="opt">( <replaceable class="parameter">column</replaceable> [,...] )</arg>
  36     </arg>
  37    </arg>
  38
  39    <arg choice="opt"><replaceable>dbname</replaceable></arg>
  40   </cmdsynopsis>
  41
  42   <cmdsynopsis>
  43    <command>vacuumdb</command>
  44    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  45    <arg rep="repeat"><replaceable>option</replaceable></arg>
  46    <group choice="plain">
  47     <arg choice="plain"><option>--all</option></arg>
  48     <arg choice="plain"><option>-a</option></arg>
  49    </group>
  50   </cmdsynopsis>
  51  </refsynopsisdiv>
  52
  53  <refsect1>
  54   <title>Description</title>
  55
  56   <para>
  57    <application>vacuumdb</application> is a utility for cleaning a
  58    <productname>PostgreSQL</productname> database.
  59    <application>vacuumdb</application> will also generate internal statistics
  60    used by the <productname>PostgreSQL</productname> query optimizer.
  61   </para>
  62
  63   <para>
  64    <application>vacuumdb</application> is a wrapper around the SQL
  65    command <xref linkend="SQL-VACUUM">.
  66    There is no effective difference between vacuuming and analyzing
  67    databases via this utility and via other methods for accessing the
  68    server.
  69   </para>
  70
  71  </refsect1>
  72
  73
  74  <refsect1>
  75   <title>Options</title>
  76
  77    <para>
  78     <application>vacuumdb</application> accepts the following command-line arguments:
  79     <variablelist>
  80      <varlistentry>
  81       <term><option>-a</option></term>
  82       <term><option>--all</option></term>
  83       <listitem>
  84        <para>
  85         Vacuum all databases.
  86        </para>
  87       </listitem>
  88      </varlistentry>
  89
  90      <varlistentry>
  91       <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></option></term>
  92       <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></option></term>
  93       <listitem>
  94        <para>
  95         Specifies the name of the database to be cleaned or analyzed.
  96         If this is not specified and <option>-a</option> (or
  97         <option>--all</option>) is not used, the database name is read
  98         from the environment variable <envar>PGDATABASE</envar>.  If
  99         that is not set, the user name specified for the connection is
 100         used.
 101        </para>
 102       </listitem>
 103      </varlistentry>
 104
 105      <varlistentry>
 106       <term><option>-e</></term>
 107       <term><option>--echo</></term>
 108       <listitem>
 109        <para>
 110         Echo the commands that <application>vacuumdb</application> generates
 111         and sends to the server.
 112        </para>
 113       </listitem>
 114      </varlistentry>
 115
 116      <varlistentry>
 117       <term><option>-f</option></term>
 118       <term><option>--full</option></term>
 119       <listitem>
 120        <para>
 121         Perform <quote>full</quote> vacuuming.
 122        </para>
 123       </listitem>
 124      </varlistentry>
 125
 126      <varlistentry>
 127       <term><option>-F</option></term>
 128       <term><option>--freeze</option></term>
 129       <listitem>
 130        <para>
 131         Aggressively <quote>freeze</quote> tuples.
 132        </para>
 133       </listitem>
 134      </varlistentry>
 135
 136      <varlistentry>
 137       <term><option>-j <replaceable class="parameter">njobs</replaceable></option></term>
 138       <term><option>--jobs=<replaceable class="parameter">njobs</replaceable></option></term>
 139       <listitem>
 140        <para>
 141         Execute the vacuum or analyze commands in parallel by running
 142         <replaceable class="parameter">njobs</replaceable>
 143         commands simultaneously.  This option reduces the time of the
 144         processing but it also increases the load on the database server.
 145        </para>
 146        <para>
 147         <application>vacuumdb</application> will open
 148         <replaceable class="parameter">njobs</replaceable> connections to the
 149         database, so make sure your <xref linkend="guc-max-connections">
 150         setting is high enough to accommodate all connections.
 151        </para>
 152        <para>
 153         Note that using this mode together with the <option>-f</option>
 154         (<literal>FULL</literal>) option might cause deadlock failures if
 155         certain system catalogs are processed in parallel.
 156        </para>
 157       </listitem>
 158      </varlistentry>
 159
 160      <varlistentry>
 161       <term><option>-q</></term>
 162       <term><option>--quiet</></term>
 163       <listitem>
 164        <para>
 165         Do not display progress messages.
 166        </para>
 167       </listitem>
 168      </varlistentry>
 169
 170      <varlistentry>
 171       <term><option>-t <replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></term>
 172       <term><option>--table=<replaceable class="parameter">table</replaceable> [ (<replaceable class="parameter">column</replaceable> [,...]) ]</option></term>
 173       <listitem>
 174        <para>
 175         Clean or analyze <replaceable class="parameter">table</replaceable> only.
 176         Column names can be specified only in conjunction with
 177         the <option>--analyze</option> or <option>--analyze-only</option> options.
 178         Multiple tables can be vacuumed by writing multiple
 179         <option>-t</> switches.
 180        </para>
 181        <tip>
 182         <para>
 183          If you specify columns, you probably have to escape the parentheses
 184          from the shell.  (See examples below.)
 185         </para>
 186        </tip>
 187       </listitem>
 188      </varlistentry>
 189
 190      <varlistentry>
 191       <term><option>-v</option></term>
 192       <term><option>--verbose</option></term>
 193       <listitem>
 194        <para>
 195         Print detailed information during processing.
 196        </para>
 197       </listitem>
 198      </varlistentry>
 199
 200      <varlistentry>
 201        <term><option>-V</></term>
 202        <term><option>--version</></term>
 203        <listitem>
 204        <para>
 205        Print the <application>vacuumdb</application> version and exit.
 206        </para>
 207        </listitem>
 208      </varlistentry>
 209
 210      <varlistentry>
 211       <term><option>-z</option></term>
 212       <term><option>--analyze</option></term>
 213       <listitem>
 214        <para>
 215         Also calculate statistics for use by the optimizer.
 216        </para>
 217       </listitem>
 218      </varlistentry>
 219
 220      <varlistentry>
 221       <term><option>-Z</option></term>
 222       <term><option>--analyze-only</option></term>
 223       <listitem>
 224        <para>
 225         Only calculate statistics for use by the optimizer (no vacuum).
 226        </para>
 227       </listitem>
 228      </varlistentry>
 229
 230      <varlistentry>
 231       <term><option>--analyze-in-stages</option></term>
 232       <listitem>
 233        <para>
 234         Only calculate statistics for use by the optimizer (no vacuum),
 235         like <option>--analyze-only</option>.  Run several (currently three)
 236         stages of analyze with different configuration settings, to produce
 237         usable statistics faster.
 238        </para>
 239
 240        <para>
 241         This option is useful to analyze a database that was newly populated
 242         from a restored dump or by <command>pg_upgrade</command>.  This option
 243         will try to create some statistics as fast as possible, to make the
 244         database usable, and then produce full statistics in the subsequent
 245         stages.
 246        </para>
 247       </listitem>
 248      </varlistentry>
 249
 250      <varlistentry>
 251        <term><option>-?</></term>
 252        <term><option>--help</></term>
 253        <listitem>
 254        <para>
 255        Show help about <application>vacuumdb</application> command line
 256        arguments, and exit.
 257        </para>
 258        </listitem>
 259      </varlistentry>
 260
 261     </variablelist>
 262    </para>
 263
 264    <para>
 265     <application>vacuumdb</application> also accepts
 266     the following command-line arguments for connection parameters:
 267     <variablelist>
 268      <varlistentry>
 269       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 270       <term><option>--host=<replaceable class="parameter">host</replaceable></></term>
 271       <listitem>
 272        <para>
 273         Specifies the host name of the machine on which the server
 274         is running.  If the value begins with a slash, it is used
 275         as the directory for the Unix domain socket.
 276        </para>
 277       </listitem>
 278      </varlistentry>
 279
 280      <varlistentry>
 281       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 282       <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
 283       <listitem>
 284        <para>
 285         Specifies the TCP port or local Unix domain socket file
 286         extension on which the server
 287         is listening for connections.
 288        </para>
 289       </listitem>
 290      </varlistentry>
 291
 292      <varlistentry>
 293       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 294       <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
 295       <listitem>
 296        <para>
 297         User name to connect as.
 298        </para>
 299       </listitem>
 300      </varlistentry>
 301
 302      <varlistentry>
 303       <term><option>-w</></term>
 304       <term><option>--no-password</></term>
 305       <listitem>
 306        <para>
 307         Never issue a password prompt.  If the server requires
 308         password authentication and a password is not available by
 309         other means such as a <filename>.pgpass</filename> file, the
 310         connection attempt will fail.  This option can be useful in
 311         batch jobs and scripts where no user is present to enter a
 312         password.
 313        </para>
 314       </listitem>
 315      </varlistentry>
 316
 317      <varlistentry>
 318       <term><option>-W</></term>
 319       <term><option>--password</></term>
 320       <listitem>
 321        <para>
 322         Force <application>vacuumdb</application> to prompt for a
 323         password before connecting to a database.
 324        </para>
 325
 326        <para>
 327         This option is never essential, since
 328         <application>vacuumdb</application> will automatically prompt
 329         for a password if the server demands password authentication.
 330         However, <application>vacuumdb</application> will waste a
 331         connection attempt finding out that the server wants a password.
 332         In some cases it is worth typing <option>-W</> to avoid the extra
 333         connection attempt.
 334        </para>
 335       </listitem>
 336      </varlistentry>
 337
 338      <varlistentry>
 339       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term>
 340       <listitem>
 341        <para>
 342          Specifies the name of the database to connect to discover what other
 343          databases should be vacuumed. If not specified, the
 344          <literal>postgres</literal> database will be used,
 345          and if that does not exist, <literal>template1</literal> will be used.
 346        </para>
 347       </listitem>
 348      </varlistentry>
 349     </variablelist>
 350    </para>
 351  </refsect1>
 352
 353
 354  <refsect1>
 355   <title>Environment</title>
 356
 357   <variablelist>
 358    <varlistentry>
 359     <term><envar>PGDATABASE</envar></term>
 360     <term><envar>PGHOST</envar></term>
 361     <term><envar>PGPORT</envar></term>
 362     <term><envar>PGUSER</envar></term>
 363
 364     <listitem>
 365      <para>
 366       Default connection parameters
 367      </para>
 368     </listitem>
 369    </varlistentry>
 370   </variablelist>
 371
 372   <para>
 373    This utility, like most other <productname>PostgreSQL</> utilities,
 374    also uses the environment variables supported by <application>libpq</>
 375    (see <xref linkend="libpq-envars">).
 376   </para>
 377
 378  </refsect1>
 379
 380
 381  <refsect1>
 382   <title>Diagnostics</title>
 383
 384   <para>
 385    In case of difficulty, see <xref linkend="SQL-VACUUM">
 386    and <xref linkend="APP-PSQL"> for
 387    discussions of potential problems and error messages.
 388    The database server must be running at the
 389    targeted host.  Also, any default connection settings and environment
 390    variables used by the <application>libpq</application> front-end
 391    library will apply.
 392   </para>
 393
 394  </refsect1>
 395
 396
 397  <refsect1>
 398   <title>Notes</title>
 399
 400   <para>
 401    <application>vacuumdb</application> might need to connect several
 402    times to the <productname>PostgreSQL</productname> server, asking
 403    for a password each time. It is convenient to have a
 404    <filename>~/.pgpass</> file in such cases. See <xref
 405    linkend="libpq-pgpass"> for more information.
 406   </para>
 407  </refsect1>
 408
 409  <refsect1>
 410   <title>Examples</title>
 411
 412    <para>
 413     To clean the database <literal>test</literal>:
 414 <screen>
 415 <prompt>$ </prompt><userinput>vacuumdb test</userinput>
 416 </screen>
 417    </para>
 418
 419    <para>
 420     To clean and analyze for the optimizer a database named
 421     <literal>bigdb</literal>:
 422 <screen>
 423 <prompt>$ </prompt><userinput>vacuumdb --analyze bigdb</userinput>
 424 </screen>
 425    </para>
 426
 427    <para>
 428     To clean a single table
 429     <literal>foo</literal> in a database named
 430     <literal>xyzzy</literal>, and analyze a single column
 431     <literal>bar</literal> of the table for the optimizer:
 432 <screen>
 433 <prompt>$ </prompt><userinput>vacuumdb --analyze --verbose --table='foo(bar)' xyzzy</userinput>
 434 </screen></para>
 435
 436  </refsect1>
 437
 438  <refsect1>
 439   <title>See Also</title>
 440
 441   <simplelist type="inline">
 442    <member><xref linkend="sql-vacuum"></member>
 443   </simplelist>
 444  </refsect1>
 445
 446 </refentry>