Debian Codegraph @

doc/src/sgml/ref/clusterdb.sgml

raw
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 When the <option>-a</option>/<option>--all</option> is used, connect
252 to this database to gather the list of databases to cluster.
253 If not specified, the <literal>postgres</literal> database will be used,
254 or if that does not exist, <literal>template1</literal> will be used.
255 This can be a <link linkend="libpq-connstring">connection
256 string</link>. If so, connection string parameters will override any
257 conflicting command line options. Also, connection string parameters
258 other than the database name itself will be re-used when connecting
259 to other databases.
260 </para>
261 </listitem>
262 </varlistentry>
263 </variablelist>
264 </para>
265 </refsect1>
266
267
268 <refsect1>
269 <title>Environment</title>
270
271 <variablelist>
272 <varlistentry>
273 <term><envar>PGDATABASE</envar></term>
274 <term><envar>PGHOST</envar></term>
275 <term><envar>PGPORT</envar></term>
276 <term><envar>PGUSER</envar></term>
277
278 <listitem>
279 <para>
280 Default connection parameters
281 </para>
282 </listitem>
283 </varlistentry>
284
285 <varlistentry>
286 <term><envar>PG_COLOR</envar></term>
287 <listitem>
288 <para>
289 Specifies whether to use color in diagnostic messages. Possible values
290 are <literal>always</literal>, <literal>auto</literal> and
291 <literal>never</literal>.
292 </para>
293 </listitem>
294 </varlistentry>
295 </variablelist>
296
297 <para>
298 This utility, like most other <productname>PostgreSQL</productname> utilities,
299 also uses the environment variables supported by <application>libpq</application>
300 (see <xref linkend="libpq-envars"/>).
301 </para>
302
303 </refsect1>
304
305
306 <refsect1>
307 <title>Diagnostics</title>
308
309 <para>
310 In case of difficulty, see <xref linkend="sql-cluster"/>
311 and <xref linkend="app-psql"/> for
312 discussions of potential problems and error messages.
313 The database server must be running at the
314 targeted host. Also, any default connection settings and environment
315 variables used by the <application>libpq</application> front-end
316 library will apply.
317 </para>
318
319 </refsect1>
320
321
322 <refsect1>
323 <title>Examples</title>
324
325 <para>
326 To cluster the database <literal>test</literal>:
327 <screen>
328 <prompt>$ </prompt><userinput>clusterdb test</userinput>
329 </screen>
330 </para>
331
332 <para>
333 To cluster a single table
334 <literal>foo</literal> in a database named
335 <literal>xyzzy</literal>:
336 <screen>
337 <prompt>$ </prompt><userinput>clusterdb --table=foo xyzzy</userinput>
338 </screen></para>
339
340 </refsect1>
341
342 <refsect1>
343 <title>See Also</title>
344
345 <simplelist type="inline">
346 <member><xref linkend="sql-cluster"/></member>
347 </simplelist>
348 </refsect1>
349
350 </refentry>