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

   1 '\" t
   2 .\"     Title: vacuumdb
   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 "VACUUMDB" "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 vacuumdb \- garbage\-collect and analyze a PostgreSQL database
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBvacuumdb\fR\ 'u
  34 \fBvacuumdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-t\fR\ |\ \fB\-\-table\fR\ \fItable\fR\ [(\ \fIcolumn\fR\ [,\&.\&.\&.]\ )]\ ]...  [\fIdbname\fR\ |\ \fB\-a\fR\ |\ \fB\-\-all\fR]
  35 .HP \w'\fBvacuumdb\fR\ 'u
  36 \fBvacuumdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-n\fR\ |\ \fB\-\-schema\fR\ \fIschema\fR\ ]...  [\fIdbname\fR\ |\ \fB\-a\fR\ |\ \fB\-\-all\fR]
  37 .HP \w'\fBvacuumdb\fR\ 'u
  38 \fBvacuumdb\fR [\fIconnection\-option\fR...] [\fIoption\fR...] [\ \fB\-N\fR\ |\ \fB\-\-exclude\-schema\fR\ \fIschema\fR\ ]...  [\fIdbname\fR\ |\ \fB\-a\fR\ |\ \fB\-\-all\fR]
  39 .SH "DESCRIPTION"
  40 .PP
  41 vacuumdb
  42 is a utility for cleaning a
  43 PostgreSQL
  44 database\&.
  45 vacuumdb
  46 will also generate internal statistics used by the
  47 PostgreSQL
  48 query optimizer\&.
  49 .PP
  50 vacuumdb
  51 is a wrapper around the SQL command
  52 \fBVACUUM\fR\&. There is no effective difference between vacuuming and analyzing databases via this utility and via other methods for accessing the server\&.
  53 .SH "OPTIONS"
  54 .PP
  55 vacuumdb
  56 accepts the following command\-line arguments:
  57 .PP
  58 \fB\-a\fR
  59 .br
  60 \fB\-\-all\fR
  61 .RS 4
  62 Vacuum all databases\&.
  63 .RE
  64 .PP
  65 \fB\-\-buffer\-usage\-limit \fR\fB\fIsize\fR\fR
  66 .RS 4
  67 Specifies the
  68 Buffer Access Strategy
  69 ring buffer size for a given invocation of
  70 vacuumdb\&. This size is used to calculate the number of shared buffers which will be reused as part of this strategy\&. See
  71 \fBVACUUM\fR(7)\&.
  72 .RE
  73 .PP
  74 \fB[\-d]\fR\fB \fR\fB\fIdbname\fR\fR
  75 .br
  76 \fB[\-\-dbname=]\fR\fB\fIdbname\fR\fR
  77 .RS 4
  78 Specifies the name of the database to be cleaned or analyzed, when
  79 \fB\-a\fR/\fB\-\-all\fR
  80 is not used\&. If this is not specified, the database name is read from the environment variable
  81 \fBPGDATABASE\fR\&. If that is not set, the user name specified for the connection is used\&. The
  82 \fIdbname\fR
  83 can be a
  84 connection string\&. If so, connection string parameters will override any conflicting command line options\&.
  85 .RE
  86 .PP
  87 \fB\-\-disable\-page\-skipping\fR
  88 .RS 4
  89 Disable skipping pages based on the contents of the visibility map\&.
  90 .RE
  91 .PP
  92 \fB\-e\fR
  93 .br
  94 \fB\-\-echo\fR
  95 .RS 4
  96 Echo the commands that
  97 vacuumdb
  98 generates and sends to the server\&.
  99 .RE
 100 .PP
 101 \fB\-f\fR
 102 .br
 103 \fB\-\-full\fR
 104 .RS 4
 105 Perform
 106 \(lqfull\(rq
 107 vacuuming\&.
 108 .RE
 109 .PP
 110 \fB\-F\fR
 111 .br
 112 \fB\-\-freeze\fR
 113 .RS 4
 114 Aggressively
 115 \(lqfreeze\(rq
 116 tuples\&.
 117 .RE
 118 .PP
 119 \fB\-\-force\-index\-cleanup\fR
 120 .RS 4
 121 Always remove index entries pointing to dead tuples\&.
 122 .RE
 123 .PP
 124 \fB\-j \fR\fB\fInjobs\fR\fR
 125 .br
 126 \fB\-\-jobs=\fR\fB\fInjobs\fR\fR
 127 .RS 4
 128 Execute the vacuum or analyze commands in parallel by running
 129 \fInjobs\fR
 130 commands simultaneously\&. This option may reduce the processing time but it also increases the load on the database server\&.
 131 .sp
 132 vacuumdb
 133 will open
 134 \fInjobs\fR
 135 connections to the database, so make sure your
 136 max_connections
 137 setting is high enough to accommodate all connections\&.
 138 .sp
 139 Note that using this mode together with the
 140 \fB\-f\fR
 141 (FULL) option might cause deadlock failures if certain system catalogs are processed in parallel\&.
 142 .RE
 143 .PP
 144 \fB\-\-min\-mxid\-age \fR\fB\fImxid_age\fR\fR
 145 .RS 4
 146 Only execute the vacuum or analyze commands on tables with a multixact ID age of at least
 147 \fImxid_age\fR\&. This setting is useful for prioritizing tables to process to prevent multixact ID wraparound (see
 148 Section\ \&24.1.5.1)\&.
 149 .sp
 150 For the purposes of this option, the multixact ID age of a relation is the greatest of the ages of the main relation and its associated
 151 TOAST
 152 table, if one exists\&. Since the commands issued by
 153 vacuumdb
 154 will also process the
 155 TOAST
 156 table for the relation if necessary, it does not need to be considered separately\&.
 157 .RE
 158 .PP
 159 \fB\-\-min\-xid\-age \fR\fB\fIxid_age\fR\fR
 160 .RS 4
 161 Only execute the vacuum or analyze commands on tables with a transaction ID age of at least
 162 \fIxid_age\fR\&. This setting is useful for prioritizing tables to process to prevent transaction ID wraparound (see
 163 Section\ \&24.1.5)\&.
 164 .sp
 165 For the purposes of this option, the transaction ID age of a relation is the greatest of the ages of the main relation and its associated
 166 TOAST
 167 table, if one exists\&. Since the commands issued by
 168 vacuumdb
 169 will also process the
 170 TOAST
 171 table for the relation if necessary, it does not need to be considered separately\&.
 172 .RE
 173 .PP
 174 \fB\-\-missing\-stats\-only\fR
 175 .RS 4
 176 Only analyze relations that are missing statistics for a column, index expression, or extended statistics object\&. When used with
 177 \fB\-\-analyze\-in\-stages\fR, this option prevents
 178 vacuumdb
 179 from temporarily replacing existing statistics with ones generated with lower statistics targets, thus avoiding transiently worse query optimizer choices\&.
 180 .sp
 181 This option can only be used in conjunction with
 182 \fB\-\-analyze\-only\fR
 183 or
 184 \fB\-\-analyze\-in\-stages\fR\&.
 185 .sp
 186 Note that
 187 \fB\-\-missing\-stats\-only\fR
 188 requires
 189 SELECT
 190 privileges on
 191 pg_statistic
 192 and
 193 pg_statistic_ext_data, which are restricted to superusers by default\&.
 194 .RE
 195 .PP
 196 \fB\-n \fR\fB\fIschema\fR\fR
 197 .br
 198 \fB\-\-schema=\fR\fB\fIschema\fR\fR
 199 .RS 4
 200 Clean or analyze all tables in
 201 \fIschema\fR
 202 only\&. Multiple schemas can be vacuumed by writing multiple
 203 \fB\-n\fR
 204 switches\&.
 205 .RE
 206 .PP
 207 \fB\-N \fR\fB\fIschema\fR\fR
 208 .br
 209 \fB\-\-exclude\-schema=\fR\fB\fIschema\fR\fR
 210 .RS 4
 211 Do not clean or analyze any tables in
 212 \fIschema\fR\&. Multiple schemas can be excluded by writing multiple
 213 \fB\-N\fR
 214 switches\&.
 215 .RE
 216 .PP
 217 \fB\-\-no\-index\-cleanup\fR
 218 .RS 4
 219 Do not remove index entries pointing to dead tuples\&.
 220 .RE
 221 .PP
 222 \fB\-\-no\-process\-main\fR
 223 .RS 4
 224 Skip the main relation\&.
 225 .RE
 226 .PP
 227 \fB\-\-no\-process\-toast\fR
 228 .RS 4
 229 Skip the TOAST table associated with the table to vacuum, if any\&.
 230 .RE
 231 .PP
 232 \fB\-\-no\-truncate\fR
 233 .RS 4
 234 Do not truncate empty pages at the end of the table\&.
 235 .RE
 236 .PP
 237 \fB\-P \fR\fB\fIparallel_workers\fR\fR
 238 .br
 239 \fB\-\-parallel=\fR\fB\fIparallel_workers\fR\fR
 240 .RS 4
 241 Specify the number of parallel workers for
 242 parallel vacuum\&. This allows the vacuum to leverage multiple CPUs to process indexes\&. See
 243 \fBVACUUM\fR(7)\&.
 244 .RE
 245 .PP
 246 \fB\-q\fR
 247 .br
 248 \fB\-\-quiet\fR
 249 .RS 4
 250 Do not display progress messages\&.
 251 .RE
 252 .PP
 253 \fB\-\-skip\-locked\fR
 254 .RS 4
 255 Skip relations that cannot be immediately locked for processing\&.
 256 .RE
 257 .PP
 258 \fB\-t \fR\fB\fItable\fR\fR\fB [ (\fR\fB\fIcolumn\fR\fR\fB [,\&.\&.\&.]) ]\fR
 259 .br
 260 \fB\-\-table=\fR\fB\fItable\fR\fR\fB [ (\fR\fB\fIcolumn\fR\fR\fB [,\&.\&.\&.]) ]\fR
 261 .RS 4
 262 Clean or analyze
 263 \fItable\fR
 264 only\&. Column names can be specified only in conjunction with the
 265 \fB\-\-analyze\fR
 266 or
 267 \fB\-\-analyze\-only\fR
 268 options\&. Multiple tables can be vacuumed by writing multiple
 269 \fB\-t\fR
 270 switches\&.
 271 .if n \{\
 272 .sp
 273 .\}
 274 .RS 4
 275 .it 1 an-trap
 276 .nr an-no-space-flag 1
 277 .nr an-break-flag 1
 278 .br
 279 .ps +1
 280 \fBTip\fR
 281 .ps -1
 282 .br
 283 If you specify columns, you probably have to escape the parentheses from the shell\&. (See examples below\&.)
 284 .sp .5v
 285 .RE
 286 .RE
 287 .PP
 288 \fB\-v\fR
 289 .br
 290 \fB\-\-verbose\fR
 291 .RS 4
 292 Print detailed information during processing\&.
 293 .RE
 294 .PP
 295 \fB\-V\fR
 296 .br
 297 \fB\-\-version\fR
 298 .RS 4
 299 Print the
 300 vacuumdb
 301 version and exit\&.
 302 .RE
 303 .PP
 304 \fB\-z\fR
 305 .br
 306 \fB\-\-analyze\fR
 307 .RS 4
 308 Also calculate statistics for use by the optimizer\&.
 309 .RE
 310 .PP
 311 \fB\-Z\fR
 312 .br
 313 \fB\-\-analyze\-only\fR
 314 .RS 4
 315 Only calculate statistics for use by the optimizer (no vacuum)\&.
 316 .RE
 317 .PP
 318 \fB\-\-analyze\-in\-stages\fR
 319 .RS 4
 320 Only calculate statistics for use by the optimizer (no vacuum), like
 321 \fB\-\-analyze\-only\fR\&. Run three stages of analyze; the first stage uses the lowest possible statistics target (see
 322 default_statistics_target) to produce usable statistics faster, and subsequent stages build the full statistics\&.
 323 .sp
 324 This option is only useful to analyze a database that currently has no statistics or has wholly incorrect ones, such as if it is newly populated from a restored dump or by
 325 \fBpg_upgrade\fR\&. Be aware that running with this option in a database with existing statistics may cause the query optimizer choices to become transiently worse due to the low statistics targets of the early stages\&.
 326 .RE
 327 .PP
 328 \fB\-?\fR
 329 .br
 330 \fB\-\-help\fR
 331 .RS 4
 332 Show help about
 333 vacuumdb
 334 command line arguments, and exit\&.
 335 .RE
 336 .PP
 337 vacuumdb
 338 also accepts the following command\-line arguments for connection parameters:
 339 .PP
 340 \fB\-h \fR\fB\fIhost\fR\fR
 341 .br
 342 \fB\-\-host=\fR\fB\fIhost\fR\fR
 343 .RS 4
 344 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\&.
 345 .RE
 346 .PP
 347 \fB\-p \fR\fB\fIport\fR\fR
 348 .br
 349 \fB\-\-port=\fR\fB\fIport\fR\fR
 350 .RS 4
 351 Specifies the TCP port or local Unix domain socket file extension on which the server is listening for connections\&.
 352 .RE
 353 .PP
 354 \fB\-U \fR\fB\fIusername\fR\fR
 355 .br
 356 \fB\-\-username=\fR\fB\fIusername\fR\fR
 357 .RS 4
 358 User name to connect as\&.
 359 .RE
 360 .PP
 361 \fB\-w\fR
 362 .br
 363 \fB\-\-no\-password\fR
 364 .RS 4
 365 Never issue a password prompt\&. If the server requires password authentication and a password is not available by other means such as a
 366 \&.pgpass
 367 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\&.
 368 .RE
 369 .PP
 370 \fB\-W\fR
 371 .br
 372 \fB\-\-password\fR
 373 .RS 4
 374 Force
 375 vacuumdb
 376 to prompt for a password before connecting to a database\&.
 377 .sp
 378 This option is never essential, since
 379 vacuumdb
 380 will automatically prompt for a password if the server demands password authentication\&. However,
 381 vacuumdb
 382 will waste a connection attempt finding out that the server wants a password\&. In some cases it is worth typing
 383 \fB\-W\fR
 384 to avoid the extra connection attempt\&.
 385 .RE
 386 .PP
 387 \fB\-\-maintenance\-db=\fR\fB\fIdbname\fR\fR
 388 .RS 4
 389 When the
 390 \fB\-a\fR/\fB\-\-all\fR
 391 is used, connect to this database to gather the list of databases to vacuum\&. If not specified, the
 392 postgres
 393 database will be used, or if that does not exist,
 394 template1
 395 will be used\&. This can be a
 396 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\&.
 397 .RE
 398 .SH "ENVIRONMENT"
 399 .PP
 400 \fBPGDATABASE\fR
 401 .br
 402 \fBPGHOST\fR
 403 .br
 404 \fBPGPORT\fR
 405 .br
 406 \fBPGUSER\fR
 407 .RS 4
 408 Default connection parameters
 409 .RE
 410 .PP
 411 \fBPG_COLOR\fR
 412 .RS 4
 413 Specifies whether to use color in diagnostic messages\&. Possible values are
 414 always,
 415 auto
 416 and
 417 never\&.
 418 .RE
 419 .PP
 420 This utility, like most other
 421 PostgreSQL
 422 utilities, also uses the environment variables supported by
 423 libpq
 424 (see
 425 Section\ \&32.15)\&.
 426 .SH "DIAGNOSTICS"
 427 .PP
 428 In case of difficulty, see
 429 \fBVACUUM\fR(7)
 430 and
 431 \fBpsql\fR(1)
 432 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
 433 libpq
 434 front\-end library will apply\&.
 435 .SH "EXAMPLES"
 436 .PP
 437 To clean the database
 438 test:
 439 .sp
 440 .if n \{\
 441 .RS 4
 442 .\}
 443 .nf
 444 $ \fBvacuumdb test\fR
 445 .fi
 446 .if n \{\
 447 .RE
 448 .\}
 449 .PP
 450 To clean and analyze for the optimizer a database named
 451 bigdb:
 452 .sp
 453 .if n \{\
 454 .RS 4
 455 .\}
 456 .nf
 457 $ \fBvacuumdb \-\-analyze bigdb\fR
 458 .fi
 459 .if n \{\
 460 .RE
 461 .\}
 462 .PP
 463 To clean a single table
 464 foo
 465 in a database named
 466 xyzzy, and analyze a single column
 467 bar
 468 of the table for the optimizer:
 469 .sp
 470 .if n \{\
 471 .RS 4
 472 .\}
 473 .nf
 474 $ \fBvacuumdb \-\-analyze \-\-verbose \-\-table=\*(Aqfoo(bar)\*(Aq xyzzy\fR
 475 .fi
 476 .if n \{\
 477 .RE
 478 .\}
 479 .PP
 480 To clean all tables in the
 481 foo
 482 and
 483 bar
 484 schemas in a database named
 485 xyzzy:
 486 .sp
 487 .if n \{\
 488 .RS 4
 489 .\}
 490 .nf
 491 $ \fBvacuumdb \-\-schema=\*(Aqfoo\*(Aq \-\-schema=\*(Aqbar\*(Aq xyzzy\fR
 492 .fi
 493 .if n \{\
 494 .RE
 495 .\}
 496 .SH "SEE ALSO"
 497 \fBVACUUM\fR(7)