1VACUUMDB(1) PostgreSQL 12.6 Documentation VACUUMDB(1)
2
6 vacuumdb - garbage-collect and analyze a PostgreSQL database
7
9 vacuumdb [connection-option...] [option...]
10 [ -t | --table table [( column [,...] )] ]... [dbname]
11 vacuumdb [connection-option...] [option...] -a | --all
13
15 vacuumdb is a utility for cleaning a PostgreSQL database. vacuumdb
16 will also generate internal statistics used by the PostgreSQL query
17 optimizer.
18 vacuumdb is a wrapper around the SQL command VACUUM(7). There is no
20 effective difference between vacuuming and analyzing databases via this
21 utility and via other methods for accessing the server.
22
24 vacuumdb accepts the following command-line arguments:
25 -a
27 --all
28 Vacuum all databases.
29 [-d] dbname
31 [--dbname=]dbname
32 Specifies the name of the database to be cleaned or analyzed, when
33 -a/--all is not used. If this is not specified, the database name
34 is read from the environment variable PGDATABASE. If that is not
35 set, the user name specified for the connection is used. The dbname
36 can be a connection string. If so, connection string parameters
37 will override any conflicting command line options.
38 --disable-page-skipping
40 Disable skipping pages based on the contents of the visibility map.
41 Note
43 This option is only available for servers running PostgreSQL
44 9.6 and later.
45 -e
47 --echo
48 Echo the commands that vacuumdb generates and sends to the server.
49 -f
51 --full
52 Perform “full” vacuuming.
53 -F
55 --freeze
56 Aggressively “freeze” tuples.
57 -j njobs
59 --jobs=njobs
60 Execute the vacuum or analyze commands in parallel by running njobs
61 commands simultaneously. This option reduces the time of the
62 processing but it also increases the load on the database server.
63 vacuumdb will open njobs connections to the database, so make sure
65 your max_connections setting is high enough to accommodate all
66 connections.
67 Note that using this mode together with the -f (FULL) option might
69 cause deadlock failures if certain system catalogs are processed in
70 parallel.
71 --min-mxid-age mxid_age
73 Only execute the vacuum or analyze commands on tables with a
74 multixact ID age of at least mxid_age. This setting is useful for
75 prioritizing tables to process to prevent multixact ID wraparound
76 (see Section 24.1.5.1).
77 For the purposes of this option, the multixact ID age of a relation
79 is the greatest of the ages of the main relation and its associated
80 TOAST table, if one exists. Since the commands issued by vacuumdb
81 will also process the TOAST table for the relation if necessary, it
82 does not need to be considered separately.
83 Note
85 This option is only available for servers running PostgreSQL
86 9.6 and later.
87 --min-xid-age xid_age
89 Only execute the vacuum or analyze commands on tables with a
90 transaction ID age of at least xid_age. This setting is useful for
91 prioritizing tables to process to prevent transaction ID wraparound
92 (see Section 24.1.5).
93 For the purposes of this option, the transaction ID age of a
95 relation is the greatest of the ages of the main relation and its
96 associated TOAST table, if one exists. Since the commands issued by
97 vacuumdb will also process the TOAST table for the relation if
98 necessary, it does not need to be considered separately.
99 Note
101 This option is only available for servers running PostgreSQL
102 9.6 and later.
103 -q
105 --quiet
106 Do not display progress messages.
107 --skip-locked
109 Skip relations that cannot be immediately locked for processing.
110 Note
112 This option is only available for servers running PostgreSQL 12
113 and later.
114 -t table [ (column [,...]) ]
116 --table=table [ (column [,...]) ]
117 Clean or analyze table only. Column names can be specified only in
118 conjunction with the --analyze or --analyze-only options. Multiple
119 tables can be vacuumed by writing multiple -t switches.
120 Tip
122 If you specify columns, you probably have to escape the
123 parentheses from the shell. (See examples below.)
124 -v
126 --verbose
127 Print detailed information during processing.
128 -V
130 --version
131 Print the vacuumdb version and exit.
132 -z
134 --analyze
135 Also calculate statistics for use by the optimizer.
136 -Z
138 --analyze-only
139 Only calculate statistics for use by the optimizer (no vacuum).
140 --analyze-in-stages
142 Only calculate statistics for use by the optimizer (no vacuum),
143 like --analyze-only. Run several (currently three) stages of
144 analyze with different configuration settings, to produce usable
145 statistics faster.
146 This option is useful to analyze a database that was newly
148 populated from a restored dump or by pg_upgrade. This option will
149 try to create some statistics as fast as possible, to make the
150 database usable, and then produce full statistics in the subsequent
151 stages.
152 -?
154 --help
155 Show help about vacuumdb command line arguments, and exit.
156 vacuumdb also accepts the following command-line arguments for
158 connection parameters:
159 -h host
161 --host=host
162 Specifies the host name of the machine on which the server is
163 running. If the value begins with a slash, it is used as the
164 directory for the Unix domain socket.
165 -p port
167 --port=port
168 Specifies the TCP port or local Unix domain socket file extension
169 on which the server is listening for connections.
170 -U username
172 --username=username
173 User name to connect as.
174 -w
176 --no-password
177 Never issue a password prompt. If the server requires password
178 authentication and a password is not available by other means such
179 as a .pgpass file, the connection attempt will fail. This option
180 can be useful in batch jobs and scripts where no user is present to
181 enter a password.
182 -W
184 --password
185 Force vacuumdb to prompt for a password before connecting to a
186 database.
187 This option is never essential, since vacuumdb will automatically
189 prompt for a password if the server demands password
190 authentication. However, vacuumdb will waste a connection attempt
191 finding out that the server wants a password. In some cases it is
192 worth typing -W to avoid the extra connection attempt.
193 --maintenance-db=dbname
195 Specifies the name of the database to connect to to discover which
196 databases should be vacuumed, when -a/--all is used. If not
197 specified, the postgres database will be used, or if that does not
198 exist, template1 will be used. This can be a connection string. If
199 so, connection string parameters will override any conflicting
200 command line options. Also, connection string parameters other than
201 the database name itself will be re-used when connecting to other
202 databases.
203
205 PGDATABASE
206 PGHOST
207 PGPORT
208 PGUSER
209 Default connection parameters
210 PG_COLOR
212 Specifies whether to use color in diagnostic messages. Possible
213 values are always, auto and never.
214 This utility, like most other PostgreSQL utilities, also uses the
216 environment variables supported by libpq (see Section 33.14).
217
219 In case of difficulty, see VACUUM(7) and psql(1) for discussions of
220 potential problems and error messages. The database server must be
221 running at the targeted host. Also, any default connection settings and
222 environment variables used by the libpq front-end library will apply.
223
225 vacuumdb might need to connect several times to the PostgreSQL server,
226 asking for a password each time. It is convenient to have a ~/.pgpass
227 file in such cases. See Section 33.15 for more information.
228
230 To clean the database test:
231 $ vacuumdb test
233 To clean and analyze for the optimizer a database named bigdb:
235 $ vacuumdb --analyze bigdb
237 To clean a single table foo in a database named xyzzy, and analyze a
239 single column bar of the table for the optimizer:
240 $ vacuumdb --analyze --verbose --table='foo(bar)' xyzzy
242
244 VACUUM(7)
245PostgreSQL 12.6 2021 VACUUMDB(1)