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