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