doc/src/sgml/ref/clusterdb.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="APP-CLUSTERDB">
   7  <refmeta>
   8   <refentrytitle id="APP-CLUSTERDB-TITLE"><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    <arg>--table | -t <replaceable>table</replaceable> </arg>
  27    <arg><replaceable>dbname</replaceable></arg>
  28    <sbr>
  29    <command>clusterdb</command>
  30    <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
  31    <group><arg>--all</arg><arg>-a</arg></group>
  32   </cmdsynopsis>
  33  </refsynopsisdiv>
  34
  35
  36  <refsect1>
  37   <title>Description</title>
  38
  39   <para>
  40    <application>clusterdb</application> is a utility for reclustering tables
  41    in a <productname>PostgreSQL</productname> database.  It finds tables
  42    that have previously been clustered, and clusters them again on the same
  43    index that was last used.  Tables that have never been clustered are not
  44    affected.
  45   </para>
  46
  47   <para>
  48    <application>clusterdb</application> is a wrapper around the SQL
  49    command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">.
  50    There is no effective difference between clustering databases via
  51    this utility and via other methods for accessing the server.
  52   </para>
  53
  54  </refsect1>
  55
  56
  57  <refsect1>
  58   <title>Options</title>
  59
  60    <para>
  61     <application>clusterdb</application> accepts the following command-line arguments:
  62
  63     <variablelist>
  64      <varlistentry>
  65       <term><option>-a</></term>
  66       <term><option>--all</></term>
  67       <listitem>
  68        <para>
  69         Cluster all databases.
  70        </para>
  71       </listitem>
  72      </varlistentry>
  73
  74      <varlistentry>
  75       <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term>
  76       <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></></term>
  77       <listitem>
  78        <para>
  79         Specifies the name of the database to be clustered.
  80         If this is not specified and <option>-a</option> (or
  81         <option>--all</option>) is not used, the database name is read
  82         from the environment variable <envar>PGDATABASE</envar>.  If
  83         that is not set, the user name specified for the connection is
  84         used.
  85        </para>
  86       </listitem>
  87      </varlistentry>
  88
  89      <varlistentry>
  90       <term><option>-e</></term>
  91       <term><option>--echo</></term>
  92       <listitem>
  93        <para>
  94         Echo the commands that <application>clusterdb</application> generates
  95         and sends to the server.
  96        </para>
  97       </listitem>
  98      </varlistentry>
  99
 100      <varlistentry>
 101       <term><option>-q</></term>
 102       <term><option>--quiet</></term>
 103       <listitem>
 104        <para>
 105         Do not display progress messages.
 106        </para>
 107       </listitem>
 108      </varlistentry>
 109
 110      <varlistentry>
 111       <term><option>-t <replaceable class="parameter">table</replaceable></></term>
 112       <term><option>--table <replaceable class="parameter">table</replaceable></></term>
 113       <listitem>
 114        <para>
 115         Cluster <replaceable class="parameter">table</replaceable> only.
 116        </para>
 117       </listitem>
 118      </varlistentry>
 119
 120     </variablelist>
 121    </para>
 122
 123    <para>
 124     <application>clusterdb</application> also accepts
 125     the following command-line arguments for connection parameters:
 126
 127     <variablelist>
 128      <varlistentry>
 129       <term><option>-h <replaceable class="parameter">host</replaceable></></term>
 130       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
 131       <listitem>
 132        <para>
 133         Specifies the host name of the machine on which the server is
 134         running.  If the value begins with a slash, it is used as the
 135         directory for the Unix domain socket.
 136        </para>
 137       </listitem>
 138      </varlistentry>
 139
 140      <varlistentry>
 141       <term><option>-p <replaceable class="parameter">port</replaceable></></term>
 142       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
 143       <listitem>
 144        <para>
 145         Specifies the TCP port or local Unix domain socket file
 146         extension on which the server
 147         is listening for connections.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151
 152      <varlistentry>
 153       <term><option>-U <replaceable class="parameter">username</replaceable></></term>
 154       <term><option>--username <replaceable class="parameter">username</replaceable></></term>
 155       <listitem>
 156        <para>
 157         User name to connect as.
 158        </para>
 159       </listitem>
 160      </varlistentry>
 161
 162      <varlistentry>
 163       <term><option>-W</></term>
 164       <term><option>--password</></term>
 165       <listitem>
 166        <para>
 167         Force <application>clusterdb</application> to prompt for a
 168         password before connecting to a database.
 169        </para>
 170
 171        <para>
 172         This option is never essential, since
 173         <application>clusterdb</application> will automatically prompt
 174         for a password if the server demands password authentication.
 175         However, <application>clusterdb</application> will waste a
 176         connection attempt finding out that the server wants a password.
 177         In some cases it is worth typing <option>-W</> to avoid the extra
 178         connection attempt.
 179        </para>
 180       </listitem>
 181      </varlistentry>
 182     </variablelist>
 183    </para>
 184  </refsect1>
 185
 186
 187  <refsect1>
 188   <title>Environment</title>
 189
 190   <variablelist>
 191    <varlistentry>
 192     <term><envar>PGDATABASE</envar></term>
 193     <term><envar>PGHOST</envar></term>
 194     <term><envar>PGPORT</envar></term>
 195     <term><envar>PGUSER</envar></term>
 196
 197     <listitem>
 198      <para>
 199       Default connection parameters
 200      </para>
 201     </listitem>
 202    </varlistentry>
 203   </variablelist>
 204
 205   <para>
 206    This utility, like most other <productname>PostgreSQL</> utilities,
 207    also uses the environment variables supported by <application>libpq</>
 208    (see <xref linkend="libpq-envars">).
 209   </para>
 210
 211  </refsect1>
 212
 213
 214  <refsect1>
 215   <title>Diagnostics</title>
 216
 217   <para>
 218    In case of difficulty, see <xref linkend="SQL-CLUSTER"
 219    endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for
 220    discussions of potential problems and error messages.
 221    The database server must be running at the
 222    targeted host.  Also, any default connection settings and environment
 223    variables used by the <application>libpq</application> front-end
 224    library will apply.
 225   </para>
 226
 227  </refsect1>
 228
 229
 230  <refsect1>
 231   <title>Examples</title>
 232
 233    <para>
 234     To cluster the database <literal>test</literal>:
 235 <screen>
 236 <prompt>$ </prompt><userinput>clusterdb test</userinput>
 237 </screen>
 238    </para>
 239
 240    <para>
 241     To cluster a single table
 242     <literal>foo</literal> in a database named
 243     <literal>xyzzy</literal>:
 244 <screen>
 245 <prompt>$ </prompt><userinput>clusterdb --table foo xyzzy</userinput>
 246 </screen>
 247    </para>
 248
 249  </refsect1>
 250
 251  <refsect1>
 252   <title>See Also</title>
 253
 254   <simplelist type="inline">
 255    <member><xref linkend="sql-cluster" endterm="sql-cluster-title"></member>
 256   </simplelist>
 257  </refsect1>
 258
 259 </refentry>