begriffs open source - ai-pg/blob - full-docs/man1/clusterdb.1

   1 '\" t
   2 .\"     Title: clusterdb
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CLUSTERDB" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 clusterdb \- cluster a PostgreSQL database
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBclusterdb\fR\ 'u
  34 \fBclusterdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-\-table\fR\ |\ \fB\-t\fR\ \fItable\fR\ ]...  [\fIdbname\fR\ |\ \fB\-a\fR\ |\ \fB\-\-all\fR]
  35 .SH "DESCRIPTION"
  36 .PP
  37 clusterdb
  38 is a utility for reclustering tables in a
  39 PostgreSQL
  40 database\&. It finds tables that have previously been clustered, and clusters them again on the same index that was last used\&. Tables that have never been clustered are not affected\&.
  41 .PP
  42 clusterdb
  43 is a wrapper around the SQL command
  44 \fBCLUSTER\fR(7)\&. There is no effective difference between clustering databases via this utility and via other methods for accessing the server\&.
  45 .SH "OPTIONS"
  46 .PP
  47 clusterdb
  48 accepts the following command\-line arguments:
  49 .PP
  50 \fB\-a\fR
  51 .br
  52 \fB\-\-all\fR
  53 .RS 4
  54 Cluster all databases\&.
  55 .RE
  56 .PP
  57 \fB[\-d]\fR\fB \fR\fB\fIdbname\fR\fR
  58 .br
  59 \fB[\-\-dbname=]\fR\fB\fIdbname\fR\fR
  60 .RS 4
  61 Specifies the name of the database to be clustered, when
  62 \fB\-a\fR/\fB\-\-all\fR
  63 is not used\&. If this is not specified, the database name is read from the environment variable
  64 \fBPGDATABASE\fR\&. If that is not set, the user name specified for the connection is used\&. The
  65 \fIdbname\fR
  66 can be a
  67 connection string\&. If so, connection string parameters will override any conflicting command line options\&.
  68 .RE
  69 .PP
  70 \fB\-e\fR
  71 .br
  72 \fB\-\-echo\fR
  73 .RS 4
  74 Echo the commands that
  75 clusterdb
  76 generates and sends to the server\&.
  77 .RE
  78 .PP
  79 \fB\-q\fR
  80 .br
  81 \fB\-\-quiet\fR
  82 .RS 4
  83 Do not display progress messages\&.
  84 .RE
  85 .PP
  86 \fB\-t \fR\fB\fItable\fR\fR
  87 .br
  88 \fB\-\-table=\fR\fB\fItable\fR\fR
  89 .RS 4
  90 Cluster
  91 \fItable\fR
  92 only\&. Multiple tables can be clustered by writing multiple
  93 \fB\-t\fR
  94 switches\&.
  95 .RE
  96 .PP
  97 \fB\-v\fR
  98 .br
  99 \fB\-\-verbose\fR
 100 .RS 4
 101 Print detailed information during processing\&.
 102 .RE
 103 .PP
 104 \fB\-V\fR
 105 .br
 106 \fB\-\-version\fR
 107 .RS 4
 108 Print the
 109 clusterdb
 110 version and exit\&.
 111 .RE
 112 .PP
 113 \fB\-?\fR
 114 .br
 115 \fB\-\-help\fR
 116 .RS 4
 117 Show help about
 118 clusterdb
 119 command line arguments, and exit\&.
 120 .RE
 121 .PP
 122 clusterdb
 123 also accepts the following command\-line arguments for connection parameters:
 124 .PP
 125 \fB\-h \fR\fB\fIhost\fR\fR
 126 .br
 127 \fB\-\-host=\fR\fB\fIhost\fR\fR
 128 .RS 4
 129 Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix domain socket\&.
 130 .RE
 131 .PP
 132 \fB\-p \fR\fB\fIport\fR\fR
 133 .br
 134 \fB\-\-port=\fR\fB\fIport\fR\fR
 135 .RS 4
 136 Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&.
 137 .RE
 138 .PP
 139 \fB\-U \fR\fB\fIusername\fR\fR
 140 .br
 141 \fB\-\-username=\fR\fB\fIusername\fR\fR
 142 .RS 4
 143 User name to connect as\&.
 144 .RE
 145 .PP
 146 \fB\-w\fR
 147 .br
 148 \fB\-\-no\-password\fR
 149 .RS 4
 150 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
 151 \&.pgpass
 152 file, the connection attempt will fail\&. This option can be useful in batch jobs and scripts where no user is present to enter a password\&.
 153 .RE
 154 .PP
 155 \fB\-W\fR
 156 .br
 157 \fB\-\-password\fR
 158 .RS 4
 159 Force
 160 clusterdb
 161 to prompt for a password before connecting to a database\&.
 162 .sp
 163 This option is never essential, since
 164 clusterdb
 165 will automatically prompt for a password if the server demands password authentication\&. However,
 166 clusterdb
 167 will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
 168 \fB\-W\fR
 169 to avoid the extra connection attempt\&.
 170 .RE
 171 .PP
 172 \fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR
 173 .RS 4
 174 When the
 175 \fB\-a\fR/\fB\-\-all\fR
 176 is used, connect to this database to gather the list of databases to cluster\&. If not specified, the
 177 postgres
 178 database will be used, or if that does not exist,
 179 template1
 180 will be used\&. This can be a
 181 connection string\&. If so, connection string parameters will override any conflicting command line options\&. Also, connection string parameters other than the database name itself will be re\-used when connecting to other databases\&.
 182 .RE
 183 .SH "ENVIRONMENT"
 184 .PP
 185 \fBPGDATABASE\fR
 186 .br
 187 \fBPGHOST\fR
 188 .br
 189 \fBPGPORT\fR
 190 .br
 191 \fBPGUSER\fR
 192 .RS 4
 193 Default connection parameters
 194 .RE
 195 .PP
 196 \fBPG_COLOR\fR
 197 .RS 4
 198 Specifies whether to use color in diagnostic messages\&. Possible values are
 199 always,
 200 auto
 201 and
 202 never\&.
 203 .RE
 204 .PP
 205 This utility, like most other
 206 PostgreSQL
 207 utilities, also uses the environment variables supported by
 208 libpq
 209 (see
 210 Section\ \&32.15)\&.
 211 .SH "DIAGNOSTICS"
 212 .PP
 213 In case of difficulty, see
 214 \fBCLUSTER\fR(7)
 215 and
 216 \fBpsql\fR(1)
 217 for discussions of potential problems and error messages\&. The database server must be running at the targeted host\&. Also, any default connection settings and environment variables used by the
 218 libpq
 219 front\-end library will apply\&.
 220 .SH "EXAMPLES"
 221 .PP
 222 To cluster the database
 223 test:
 224 .sp
 225 .if n \{\
 226 .RS 4
 227 .\}
 228 .nf
 229 $ \fBclusterdb test\fR
 230 .fi
 231 .if n \{\
 232 .RE
 233 .\}
 234 .PP
 235 To cluster a single table
 236 foo
 237 in a database named
 238 xyzzy:
 239 .sp
 240 .if n \{\
 241 .RS 4
 242 .\}
 243 .nf
 244 $ \fBclusterdb \-\-table=foo xyzzy\fR
 245 .fi
 246 .if n \{\
 247 .RE
 248 .\}
 249 .SH "SEE ALSO"
 250 \fBCLUSTER\fR(7)