doc/src/sgml/ref/clusterdb.sgml

   1 <!--
   2 doc/src/sgml/ref/clusterdb.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="app-clusterdb">
   7  <indexterm zone="app-clusterdb">
   8   <primary>clusterdb</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>clusterdb</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>clusterdb</refname>
  19   <refpurpose>cluster a <productname>PostgreSQL</productname> database</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>clusterdb</command>
  25    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  26    <group choice="opt"><arg choice="plain"><option>--verbose</option></arg><arg choice="plain"><option>-v</option></arg></group>
  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>
  36    </arg>
  37
  38    <arg choice="opt"><replaceable>dbname</replaceable></arg>
  39   </cmdsynopsis>
  40
  41   <cmdsynopsis>
  42    <command>clusterdb</command>
  43    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  44    <group choice="opt"><arg choice="plain"><option>--verbose</option></arg><arg choice="plain"><option>-v</option></arg></group>
  45    <group choice="plain"><arg choice="plain"><option>--all</option></arg><arg choice="plain"><option>-a</option></arg></group>
  46   </cmdsynopsis>
  47  </refsynopsisdiv>
  48
  49
  50  <refsect1>
  51   <title>Description</title>
  52
  53   <para>
  54    <application>clusterdb</application> is a utility for reclustering tables
  55    in a <productname>PostgreSQL</productname> database.  It finds tables
  56    that have previously been clustered, and clusters them again on the same
  57    index that was last used.  Tables that have never been clustered are not
  58    affected.
  59   </para>
  60
  61   <para>
  62    <application>clusterdb</application> is a wrapper around the SQL
  63    command <xref linkend="sql-cluster"/>.
  64    There is no effective difference between clustering databases via
  65    this utility and via other methods for accessing the server.
  66   </para>
  67
  68  </refsect1>
  69
  70
  71  <refsect1>
  72   <title>Options</title>
  73
  74    <para>
  75     <application>clusterdb</application> accepts the following command-line arguments:
  76
  77     <variablelist>
  78      <varlistentry>
  79       <term><option>-a</option></term>
  80       <term><option>--all</option></term>
  81       <listitem>
  82        <para>
  83         Cluster all databases.
  84        </para>
  85       </listitem>
  86      </varlistentry>
  87
  88      <varlistentry>
  89       <term><option><optional>-d</optional> <replaceable class="parameter">dbname</replaceable></option></term>
  90       <term><option><optional>--dbname=</optional><replaceable class="parameter">dbname</replaceable></option></term>
  91       <listitem>
  92        <para>
  93         Specifies the name of the database to be clustered,
  94         when <option>-a</option>/<option>--all</option> is not used.
  95         If this is not specified, the database name is read
  96         from the environment variable <envar>PGDATABASE</envar>.  If
  97         that is not set, the user name specified for the connection is
  98         used.  The <replaceable>dbname</replaceable> can be a <link
  99         linkend="libpq-connstring">connection string</link>.  If so,
 100         connection string parameters will override any conflicting command
 101         line options.
 102        </para>
 103       </listitem>
 104      </varlistentry>
 105
 106      <varlistentry>
 107       <term><option>-e</option></term>
 108       <term><option>--echo</option></term>
 109       <listitem>
 110        <para>
 111         Echo the commands that <application>clusterdb</application> generates
 112         and sends to the server.
 113        </para>
 114       </listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><option>-q</option></term>
 119       <term><option>--quiet</option></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></option></term>
 129       <term><option>--table=<replaceable class="parameter">table</replaceable></option></term>
 130       <listitem>
 131        <para>
 132         Cluster <replaceable class="parameter">table</replaceable> only.
 133         Multiple tables can be clustered by writing multiple
 134         <option>-t</option> switches.
 135        </para>
 136       </listitem>
 137      </varlistentry>
 138
 139      <varlistentry>
 140       <term><option>-v</option></term>
 141       <term><option>--verbose</option></term>
 142       <listitem>
 143        <para>
 144         Print detailed information during processing.
 145        </para>
 146       </listitem>
 147      </varlistentry>
 148
 149     <varlistentry>
 150       <term><option>-V</option></term>
 151       <term><option>--version</option></term>
 152       <listitem>
 153       <para>
 154       Print the <application>clusterdb</application> version and exit.
 155       </para>
 156       </listitem>
 157     </varlistentry>
 158
 159     <varlistentry>
 160       <term><option>-?</option></term>
 161       <term><option>--help</option></term>
 162       <listitem>
 163       <para>
 164       Show help about <application>clusterdb</application> command line
 165       arguments, and exit.
 166       </para>
 167       </listitem>
 168     </varlistentry>
 169
 170     </variablelist>
 171    </para>
 172
 173    <para>
 174     <application>clusterdb</application> also accepts
 175     the following command-line arguments for connection parameters:
 176
 177     <variablelist>
 178      <varlistentry>
 179       <term><option>-h <replaceable class="parameter">host</replaceable></option></term>
 180       <term><option>--host=<replaceable class="parameter">host</replaceable></option></term>
 181       <listitem>
 182        <para>
 183         Specifies the host name of the machine on which the server is
 184         running.  If the value begins with a slash, it is used as the
 185         directory for the Unix domain socket.
 186        </para>
 187       </listitem>
 188      </varlistentry>
 189
 190      <varlistentry>
 191       <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
 192       <term><option>--port=<replaceable class="parameter">port</replaceable></option></term>
 193       <listitem>
 194        <para>
 195         Specifies the TCP port or local Unix domain socket file
 196         extension on which the server
 197         is listening for connections.
 198        </para>
 199       </listitem>
 200      </varlistentry>
 201
 202      <varlistentry>
 203       <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 204       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
 205       <listitem>
 206        <para>
 207         User name to connect as.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211
 212      <varlistentry>
 213       <term><option>-w</option></term>
 214       <term><option>--no-password</option></term>
 215       <listitem>
 216        <para>
 217         Never issue a password prompt.  If the server requires
 218         password authentication and a password is not available by
 219         other means such as a <filename>.pgpass</filename> file, the
 220         connection attempt will fail.  This option can be useful in
 221         batch jobs and scripts where no user is present to enter a
 222         password.
 223        </para>
 224       </listitem>
 225      </varlistentry>
 226
 227      <varlistentry>
 228       <term><option>-W</option></term>
 229       <term><option>--password</option></term>
 230       <listitem>
 231        <para>
 232         Force <application>clusterdb</application> to prompt for a
 233         password before connecting to a database.
 234        </para>
 235
 236        <para>
 237         This option is never essential, since
 238         <application>clusterdb</application> will automatically prompt
 239         for a password if the server demands password authentication.
 240         However, <application>clusterdb</application> will waste a
 241         connection attempt finding out that the server wants a password.
 242         In some cases it is worth typing <option>-W</option> to avoid the extra
 243         connection attempt.
 244        </para>
 245       </listitem>
 246      </varlistentry>
 247
 248      <varlistentry>
 249       <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
 250       <listitem>
 251        <para>
 252         Specifies the name of the database to connect to to discover which
 253         databases should be clustered,
 254         when <option>-a</option>/<option>--all</option> is used.
 255         If not specified, the <literal>postgres</literal> database will be used,
 256         or if that does not exist, <literal>template1</literal> will be used.
 257         This can be a <link linkend="libpq-connstring">connection
 258         string</link>.  If so, connection string parameters will override any
 259         conflicting command line options.  Also, connection string parameters
 260         other than the database name itself will be re-used when connecting
 261         to other databases.
 262        </para>
 263       </listitem>
 264      </varlistentry>
 265     </variablelist>
 266    </para>
 267  </refsect1>
 268
 269
 270  <refsect1>
 271   <title>Environment</title>
 272
 273   <variablelist>
 274    <varlistentry>
 275     <term><envar>PGDATABASE</envar></term>
 276     <term><envar>PGHOST</envar></term>
 277     <term><envar>PGPORT</envar></term>
 278     <term><envar>PGUSER</envar></term>
 279
 280     <listitem>
 281      <para>
 282       Default connection parameters
 283      </para>
 284     </listitem>
 285    </varlistentry>
 286
 287    <varlistentry>
 288     <term><envar>PG_COLOR</envar></term>
 289     <listitem>
 290      <para>
 291       Specifies whether to use color in diagnostic messages. Possible values
 292       are <literal>always</literal>, <literal>auto</literal> and
 293       <literal>never</literal>.
 294      </para>
 295     </listitem>
 296    </varlistentry>
 297   </variablelist>
 298
 299   <para>
 300    This utility, like most other <productname>PostgreSQL</productname> utilities,
 301    also uses the environment variables supported by <application>libpq</application>
 302    (see <xref linkend="libpq-envars"/>).
 303   </para>
 304
 305  </refsect1>
 306
 307
 308  <refsect1>
 309   <title>Diagnostics</title>
 310
 311   <para>
 312    In case of difficulty, see <xref linkend="sql-cluster"/>
 313    and <xref linkend="app-psql"/> for
 314    discussions of potential problems and error messages.
 315    The database server must be running at the
 316    targeted host.  Also, any default connection settings and environment
 317    variables used by the <application>libpq</application> front-end
 318    library will apply.
 319   </para>
 320
 321  </refsect1>
 322
 323
 324  <refsect1>
 325   <title>Examples</title>
 326
 327    <para>
 328     To cluster the database <literal>test</literal>:
 329 <screen>
 330 <prompt>$ </prompt><userinput>clusterdb test</userinput>
 331 </screen>
 332    </para>
 333
 334    <para>
 335     To cluster a single table
 336     <literal>foo</literal> in a database named
 337     <literal>xyzzy</literal>:
 338 <screen>
 339 <prompt>$ </prompt><userinput>clusterdb --table=foo xyzzy</userinput>
 340 </screen></para>
 341
 342  </refsect1>
 343
 344  <refsect1>
 345   <title>See Also</title>
 346
 347   <simplelist type="inline">
 348    <member><xref linkend="sql-cluster"/></member>
 349   </simplelist>
 350  </refsect1>
 351
 352 </refentry>