begriffs open source - ai-pg/blob - full-docs/src/sgml/html/app-clusterdb.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>clusterdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="reference-client.html" title="PostgreSQL Client Applications" /><link rel="next" href="app-createdb.html" title="createdb" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">clusterdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="reference-client.html" title="PostgreSQL Client Applications">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-createdb.html" title="createdb">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-CLUSTERDB"><div class="titlepage"></div><a id="id-1.9.4.3.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">clusterdb</span></span></h2><p>clusterdb — cluster a <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.3.4.1"><code class="command">clusterdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...]
   3      [
   4          <code class="option">--table</code>  |   <code class="option">-t</code>
   5        <em class="replaceable"><code>table</code></em>
   6      ]
   7    ...  [
   8       <em class="replaceable"><code>dbname</code></em>  |   <code class="option">-a</code>  |   <code class="option">--all</code>
   9    ]</p></div></div><div class="refsect1" id="id-1.9.4.3.5"><h2>Description</h2><p>
  10    <span class="application">clusterdb</span> is a utility for reclustering tables
  11    in a <span class="productname">PostgreSQL</span> database.  It finds tables
  12    that have previously been clustered, and clusters them again on the same
  13    index that was last used.  Tables that have never been clustered are not
  14    affected.
  15   </p><p>
  16    <span class="application">clusterdb</span> is a wrapper around the SQL
  17    command <a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a>.
  18    There is no effective difference between clustering databases via
  19    this utility and via other methods for accessing the server.
  20   </p></div><div class="refsect1" id="id-1.9.4.3.6"><h2>Options</h2><p>
  21     <span class="application">clusterdb</span> accepts the following command-line arguments:
  22
  23     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-a</code><br /></span><span class="term"><code class="option">--all</code></span></dt><dd><p>
  24         Cluster all databases.
  25        </p></dd><dt><span class="term"><code class="option">[<span class="optional">-d</span>] <em class="replaceable"><code>dbname</code></em></code><br /></span><span class="term"><code class="option">[<span class="optional">--dbname=</span>]<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
  26         Specifies the name of the database to be clustered,
  27         when <code class="option">-a</code>/<code class="option">--all</code> is not used.
  28         If this is not specified, the database name is read
  29         from the environment variable <code class="envar">PGDATABASE</code>.  If
  30         that is not set, the user name specified for the connection is
  31         used.  The <em class="replaceable"><code>dbname</code></em> can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">connection string</a>.  If so,
  32         connection string parameters will override any conflicting command
  33         line options.
  34        </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
  35         Echo the commands that <span class="application">clusterdb</span> generates
  36         and sends to the server.
  37        </p></dd><dt><span class="term"><code class="option">-q</code><br /></span><span class="term"><code class="option">--quiet</code></span></dt><dd><p>
  38         Do not display progress messages.
  39        </p></dd><dt><span class="term"><code class="option">-t <em class="replaceable"><code>table</code></em></code><br /></span><span class="term"><code class="option">--table=<em class="replaceable"><code>table</code></em></code></span></dt><dd><p>
  40         Cluster <em class="replaceable"><code>table</code></em> only.
  41         Multiple tables can be clustered by writing multiple
  42         <code class="option">-t</code> switches.
  43        </p></dd><dt><span class="term"><code class="option">-v</code><br /></span><span class="term"><code class="option">--verbose</code></span></dt><dd><p>
  44         Print detailed information during processing.
  45        </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
  46       Print the <span class="application">clusterdb</span> version and exit.
  47       </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
  48       Show help about <span class="application">clusterdb</span> command line
  49       arguments, and exit.
  50       </p></dd></dl></div><p>
  51    </p><p>
  52     <span class="application">clusterdb</span> also accepts
  53     the following command-line arguments for connection parameters:
  54
  55     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
  56         Specifies the host name of the machine on which the server is
  57         running.  If the value begins with a slash, it is used as the
  58         directory for the Unix domain socket.
  59        </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
  60         Specifies the TCP port or local Unix domain socket file
  61         extension on which the server
  62         is listening for connections.
  63        </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
  64         User name to connect as.
  65        </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
  66         Never issue a password prompt.  If the server requires
  67         password authentication and a password is not available by
  68         other means such as a <code class="filename">.pgpass</code> file, the
  69         connection attempt will fail.  This option can be useful in
  70         batch jobs and scripts where no user is present to enter a
  71         password.
  72        </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
  73         Force <span class="application">clusterdb</span> to prompt for a
  74         password before connecting to a database.
  75        </p><p>
  76         This option is never essential, since
  77         <span class="application">clusterdb</span> will automatically prompt
  78         for a password if the server demands password authentication.
  79         However, <span class="application">clusterdb</span> will waste a
  80         connection attempt finding out that the server wants a password.
  81         In some cases it is worth typing <code class="option">-W</code> to avoid the extra
  82         connection attempt.
  83        </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
  84         When the <code class="option">-a</code>/<code class="option">--all</code> is used, connect
  85         to this database to gather the list of databases to cluster.
  86         If not specified, the <code class="literal">postgres</code> database will be used,
  87         or if that does not exist, <code class="literal">template1</code> will be used.
  88         This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">connection
  89         string</a>.  If so, connection string parameters will override any
  90         conflicting command line options.  Also, connection string parameters
  91         other than the database name itself will be re-used when connecting
  92         to other databases.
  93        </p></dd></dl></div><p>
  94    </p></div><div class="refsect1" id="id-1.9.4.3.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code><br /></span><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
  95       Default connection parameters
  96      </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
  97       Specifies whether to use color in diagnostic messages. Possible values
  98       are <code class="literal">always</code>, <code class="literal">auto</code> and
  99       <code class="literal">never</code>.
 100      </p></dd></dl></div><p>
 101    This utility, like most other <span class="productname">PostgreSQL</span> utilities,
 102    also uses the environment variables supported by <span class="application">libpq</span>
 103    (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>).
 104   </p></div><div class="refsect1" id="id-1.9.4.3.8"><h2>Diagnostics</h2><p>
 105    In case of difficulty, see <a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a>
 106    and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
 107    discussions of potential problems and error messages.
 108    The database server must be running at the
 109    targeted host.  Also, any default connection settings and environment
 110    variables used by the <span class="application">libpq</span> front-end
 111    library will apply.
 112   </p></div><div class="refsect1" id="id-1.9.4.3.9"><h2>Examples</h2><p>
 113     To cluster the database <code class="literal">test</code>:
 114 </p><pre class="screen">
 115 <code class="prompt">$ </code><strong class="userinput"><code>clusterdb test</code></strong>
 116 </pre><p>
 117    </p><p>
 118     To cluster a single table
 119     <code class="literal">foo</code> in a database named
 120     <code class="literal">xyzzy</code>:
 121 </p><pre class="screen">
 122 <code class="prompt">$ </code><strong class="userinput"><code>clusterdb --table=foo xyzzy</code></strong>
 123 </pre></div><div class="refsect1" id="id-1.9.4.3.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-cluster.html" title="CLUSTER"><span class="refentrytitle">CLUSTER</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="reference-client.html" title="PostgreSQL Client Applications">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-createdb.html" title="createdb">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PostgreSQL Client Applications </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">createdb</span></td></tr></table></div></body></html>