begriffs open source - ai-pg/blob - full-docs/txt/app-vacuumdb.txt

   1
   2 vacuumdb
   3
   4    vacuumdb — garbage-collect and analyze a PostgreSQL database
   5
   6 Synopsis
   7
   8    vacuumdb [connection-option...] [option...] [ -t | --table table [(
   9    column [,...] )] ] ... [ dbname | -a | --all ]
  10
  11    vacuumdb [connection-option...] [option...] [ -n | --schema schema ]
  12    ... [ dbname | -a | --all ]
  13
  14    vacuumdb [connection-option...] [option...] [ -N | --exclude-schema
  15    schema ] ... [ dbname | -a | --all ]
  16
  17 Description
  18
  19    vacuumdb is a utility for cleaning a PostgreSQL database. vacuumdb will
  20    also generate internal statistics used by the PostgreSQL query
  21    optimizer.
  22
  23    vacuumdb is a wrapper around the SQL command VACUUM. There is no
  24    effective difference between vacuuming and analyzing databases via this
  25    utility and via other methods for accessing the server.
  26
  27 Options
  28
  29    vacuumdb accepts the following command-line arguments:
  30
  31    -a
  32           --all
  33           Vacuum all databases.
  34
  35    --buffer-usage-limit size
  36           Specifies the Buffer Access Strategy ring buffer size for a
  37           given invocation of vacuumdb. This size is used to calculate the
  38           number of shared buffers which will be reused as part of this
  39           strategy. See VACUUM.
  40
  41    [-d] dbname
  42           [--dbname=]dbname
  43           Specifies the name of the database to be cleaned or analyzed,
  44           when -a/--all is not used. If this is not specified, the
  45           database name is read from the environment variable PGDATABASE.
  46           If that is not set, the user name specified for the connection
  47           is used. The dbname can be a connection string. If so,
  48           connection string parameters will override any conflicting
  49           command line options.
  50
  51    --disable-page-skipping
  52           Disable skipping pages based on the contents of the visibility
  53           map.
  54
  55    -e
  56           --echo
  57           Echo the commands that vacuumdb generates and sends to the
  58           server.
  59
  60    -f
  61           --full
  62           Perform “full” vacuuming.
  63
  64    -F
  65           --freeze
  66           Aggressively “freeze” tuples.
  67
  68    --force-index-cleanup
  69           Always remove index entries pointing to dead tuples.
  70
  71    -j njobs
  72           --jobs=njobs
  73           Execute the vacuum or analyze commands in parallel by running
  74           njobs commands simultaneously. This option may reduce the
  75           processing time but it also increases the load on the database
  76           server.
  77
  78           vacuumdb will open njobs connections to the database, so make
  79           sure your max_connections setting is high enough to accommodate
  80           all connections.
  81
  82           Note that using this mode together with the -f (FULL) option
  83           might cause deadlock failures if certain system catalogs are
  84           processed in parallel.
  85
  86    --min-mxid-age mxid_age
  87           Only execute the vacuum or analyze commands on tables with a
  88           multixact ID age of at least mxid_age. This setting is useful
  89           for prioritizing tables to process to prevent multixact ID
  90           wraparound (see Section 24.1.5.1).
  91
  92           For the purposes of this option, the multixact ID age of a
  93           relation is the greatest of the ages of the main relation and
  94           its associated TOAST table, if one exists. Since the commands
  95           issued by vacuumdb will also process the TOAST table for the
  96           relation if necessary, it does not need to be considered
  97           separately.
  98
  99    --min-xid-age xid_age
 100           Only execute the vacuum or analyze commands on tables with a
 101           transaction ID age of at least xid_age. This setting is useful
 102           for prioritizing tables to process to prevent transaction ID
 103           wraparound (see Section 24.1.5).
 104
 105           For the purposes of this option, the transaction ID age of a
 106           relation is the greatest of the ages of the main relation and
 107           its associated TOAST table, if one exists. Since the commands
 108           issued by vacuumdb will also process the TOAST table for the
 109           relation if necessary, it does not need to be considered
 110           separately.
 111
 112    --missing-stats-only
 113           Only analyze relations that are missing statistics for a column,
 114           index expression, or extended statistics object. When used with
 115           --analyze-in-stages, this option prevents vacuumdb from
 116           temporarily replacing existing statistics with ones generated
 117           with lower statistics targets, thus avoiding transiently worse
 118           query optimizer choices.
 119
 120           This option can only be used in conjunction with --analyze-only
 121           or --analyze-in-stages.
 122
 123           Note that --missing-stats-only requires SELECT privileges on
 124           pg_statistic and pg_statistic_ext_data, which are restricted to
 125           superusers by default.
 126
 127    -n schema
 128           --schema=schema
 129           Clean or analyze all tables in schema only. Multiple schemas can
 130           be vacuumed by writing multiple -n switches.
 131
 132    -N schema
 133           --exclude-schema=schema
 134           Do not clean or analyze any tables in schema. Multiple schemas
 135           can be excluded by writing multiple -N switches.
 136
 137    --no-index-cleanup
 138           Do not remove index entries pointing to dead tuples.
 139
 140    --no-process-main
 141           Skip the main relation.
 142
 143    --no-process-toast
 144           Skip the TOAST table associated with the table to vacuum, if
 145           any.
 146
 147    --no-truncate
 148           Do not truncate empty pages at the end of the table.
 149
 150    -P parallel_workers
 151           --parallel=parallel_workers
 152           Specify the number of parallel workers for parallel vacuum. This
 153           allows the vacuum to leverage multiple CPUs to process indexes.
 154           See VACUUM.
 155
 156    -q
 157           --quiet
 158           Do not display progress messages.
 159
 160    --skip-locked
 161           Skip relations that cannot be immediately locked for processing.
 162
 163    -t table [ (column [,...]) ]
 164           --table=table [ (column [,...]) ]
 165           Clean or analyze table only. Column names can be specified only
 166           in conjunction with the --analyze or --analyze-only options.
 167           Multiple tables can be vacuumed by writing multiple -t switches.
 168
 169 Tip
 170
 171           If you specify columns, you probably have to escape the
 172           parentheses from the shell. (See examples below.)
 173
 174    -v
 175           --verbose
 176           Print detailed information during processing.
 177
 178    -V
 179           --version
 180           Print the vacuumdb version and exit.
 181
 182    -z
 183           --analyze
 184           Also calculate statistics for use by the optimizer.
 185
 186    -Z
 187           --analyze-only
 188           Only calculate statistics for use by the optimizer (no vacuum).
 189
 190    --analyze-in-stages
 191           Only calculate statistics for use by the optimizer (no vacuum),
 192           like --analyze-only. Run three stages of analyze; the first
 193           stage uses the lowest possible statistics target (see
 194           default_statistics_target) to produce usable statistics faster,
 195           and subsequent stages build the full statistics.
 196
 197           This option is only useful to analyze a database that currently
 198           has no statistics or has wholly incorrect ones, such as if it is
 199           newly populated from a restored dump or by pg_upgrade. Be aware
 200           that running with this option in a database with existing
 201           statistics may cause the query optimizer choices to become
 202           transiently worse due to the low statistics targets of the early
 203           stages.
 204
 205    -?
 206           --help
 207           Show help about vacuumdb command line arguments, and exit.
 208
 209    vacuumdb also accepts the following command-line arguments for
 210    connection parameters:
 211
 212    -h host
 213           --host=host
 214           Specifies the host name of the machine on which the server is
 215           running. If the value begins with a slash, it is used as the
 216           directory for the Unix domain socket.
 217
 218    -p port
 219           --port=port
 220           Specifies the TCP port or local Unix domain socket file
 221           extension on which the server is listening for connections.
 222
 223    -U username
 224           --username=username
 225           User name to connect as.
 226
 227    -w
 228           --no-password
 229           Never issue a password prompt. If the server requires password
 230           authentication and a password is not available by other means
 231           such as a .pgpass file, the connection attempt will fail. This
 232           option can be useful in batch jobs and scripts where no user is
 233           present to enter a password.
 234
 235    -W
 236           --password
 237           Force vacuumdb to prompt for a password before connecting to a
 238           database.
 239
 240           This option is never essential, since vacuumdb will
 241           automatically prompt for a password if the server demands
 242           password authentication. However, vacuumdb will waste a
 243           connection attempt finding out that the server wants a password.
 244           In some cases it is worth typing -W to avoid the extra
 245           connection attempt.
 246
 247    --maintenance-db=dbname
 248           When the -a/--all is used, connect to this database to gather
 249           the list of databases to vacuum. If not specified, the postgres
 250           database will be used, or if that does not exist, template1 will
 251           be used. This can be a connection string. If so, connection
 252           string parameters will override any conflicting command line
 253           options. Also, connection string parameters other than the
 254           database name itself will be re-used when connecting to other
 255           databases.
 256
 257 Environment
 258
 259    PGDATABASE
 260           PGHOST
 261           PGPORT
 262           PGUSER
 263           Default connection parameters
 264
 265    PG_COLOR
 266           Specifies whether to use color in diagnostic messages. Possible
 267           values are always, auto and never.
 268
 269    This utility, like most other PostgreSQL utilities, also uses the
 270    environment variables supported by libpq (see Section 32.15).
 271
 272 Diagnostics
 273
 274    In case of difficulty, see VACUUM and psql for discussions of potential
 275    problems and error messages. The database server must be running at the
 276    targeted host. Also, any default connection settings and environment
 277    variables used by the libpq front-end library will apply.
 278
 279 Examples
 280
 281    To clean the database test:
 282 $ vacuumdb test
 283
 284    To clean and analyze for the optimizer a database named bigdb:
 285 $ vacuumdb --analyze bigdb
 286
 287    To clean a single table foo in a database named xyzzy, and analyze a
 288    single column bar of the table for the optimizer:
 289 $ vacuumdb --analyze --verbose --table='foo(bar)' xyzzy
 290
 291    To clean all tables in the foo and bar schemas in a database named
 292    xyzzy:
 293 $ vacuumdb --schema='foo' --schema='bar' xyzzy
 294
 295 See Also
 296
 297    VACUUM