2 doc/src/sgml/ref/clusterdb.sgml
3 PostgreSQL documentation
6 <refentry id="APP-CLUSTERDB">
8 <refentrytitle><application>clusterdb</application></refentrytitle>
9 <manvolnum>1</manvolnum>
10 <refmiscinfo>Application</refmiscinfo>
14 <refname id="clusterdb">clusterdb</refname>
15 <refpurpose>cluster a <productname>PostgreSQL</productname> database</refpurpose>
18 <indexterm zone="app-clusterdb">
19 <primary>clusterdb</primary>
24 <command>clusterdb</command>
25 <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
26 <group><arg>--verbose</arg><arg>-v</arg></group>
27 <arg>--table | -t <replaceable>table</replaceable> </arg>
28 <arg><replaceable>dbname</replaceable></arg>
32 <command>clusterdb</command>
33 <arg rep="repeat"><replaceable>connection-option</replaceable></arg>
34 <group><arg>--verbose</arg><arg>-v</arg></group>
35 <group><arg>--all</arg><arg>-a</arg></group>
41 <title>Description</title>
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
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.
62 <title>Options</title>
65 <application>clusterdb</application> accepts the following command-line arguments:
69 <term><option>-a</></term>
70 <term><option>--all</></term>
73 Cluster all databases.
79 <term><option><optional>-d</> <replaceable class="parameter">dbname</replaceable></></term>
80 <term><option><optional>--dbname=</><replaceable class="parameter">dbname</replaceable></></term>
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
94 <term><option>-e</></term>
95 <term><option>--echo</></term>
98 Echo the commands that <application>clusterdb</application> generates
99 and sends to the server.
105 <term><option>-q</></term>
106 <term><option>--quiet</></term>
109 Do not display progress messages.
115 <term><option>-t <replaceable class="parameter">table</replaceable></></term>
116 <term><option>--table=<replaceable class="parameter">table</replaceable></></term>
119 Cluster <replaceable class="parameter">table</replaceable> only.
125 <term><option>-v</></term>
126 <term><option>--verbose</></term>
129 Print detailed information during processing.
135 <term><option>-V</></term>
136 <term><option>--version</></term>
139 Print the <application>clusterdb</application> version and exit.
145 <term><option>-?</></term>
146 <term><option>--help</></term>
149 Show help about <application>clusterdb</application> command line
159 <application>clusterdb</application> also accepts
160 the following command-line arguments for connection parameters:
164 <term><option>-h <replaceable class="parameter">host</replaceable></></term>
165 <term><option>--host=<replaceable class="parameter">host</replaceable></></term>
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.
176 <term><option>-p <replaceable class="parameter">port</replaceable></></term>
177 <term><option>--port=<replaceable class="parameter">port</replaceable></></term>
180 Specifies the TCP port or local Unix domain socket file
181 extension on which the server
182 is listening for connections.
188 <term><option>-U <replaceable class="parameter">username</replaceable></></term>
189 <term><option>--username=<replaceable class="parameter">username</replaceable></></term>
192 User name to connect as.
198 <term><option>-w</></term>
199 <term><option>--no-password</></term>
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
213 <term><option>-W</></term>
214 <term><option>--password</></term>
217 Force <application>clusterdb</application> to prompt for a
218 password before connecting to a database.
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
234 <term><option>--maintenance-db=<replaceable class="parameter">dbname</replaceable></></term>
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.
250 <title>Environment</title>
254 <term><envar>PGDATABASE</envar></term>
255 <term><envar>PGHOST</envar></term>
256 <term><envar>PGPORT</envar></term>
257 <term><envar>PGUSER</envar></term>
261 Default connection parameters
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">).
277 <title>Diagnostics</title>
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
293 <title>Examples</title>
296 To cluster the database <literal>test</literal>:
298 <prompt>$ </prompt><userinput>clusterdb test</userinput>
303 To cluster a single table
304 <literal>foo</literal> in a database named
305 <literal>xyzzy</literal>:
307 <prompt>$ </prompt><userinput>clusterdb --table foo xyzzy</userinput>
313 <title>See Also</title>
315 <simplelist type="inline">
316 <member><xref linkend="sql-cluster"></member>