1VACUUMDB(1) PostgreSQL 13.4 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 may reduce the processing time
62 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 -P parallel_workers
105 --parallel=parallel_workers
106 Specify the number of parallel workers for parallel vacuum. This
107 allows the vacuum to leverage multiple CPUs to process indexes. See
108 VACUUM(7).
109 Note
111 This option is only available for servers running PostgreSQL 13
112 and later.
113 -q
115 --quiet
116 Do not display progress messages.
117 --skip-locked
119 Skip relations that cannot be immediately locked for processing.
120 Note
122 This option is only available for servers running PostgreSQL 12
123 and later.
124 -t table [ (column [,...]) ]
126 --table=table [ (column [,...]) ]
127 Clean or analyze table only. Column names can be specified only in
128 conjunction with the --analyze or --analyze-only options. Multiple
129 tables can be vacuumed by writing multiple -t switches.
130 Tip
132 If you specify columns, you probably have to escape the
133 parentheses from the shell. (See examples below.)
134 -v
136 --verbose
137 Print detailed information during processing.
138 -V
140 --version
141 Print the vacuumdb version and exit.
142 -z
144 --analyze
145 Also calculate statistics for use by the optimizer.
146 -Z
148 --analyze-only
149 Only calculate statistics for use by the optimizer (no vacuum).
150 --analyze-in-stages
152 Only calculate statistics for use by the optimizer (no vacuum),
153 like --analyze-only. Run several (currently three) stages of
154 analyze with different configuration settings, to produce usable
155 statistics faster.
156 This option is useful to analyze a database that was newly
158 populated from a restored dump or by pg_upgrade. This option will
159 try to create some statistics as fast as possible, to make the
160 database usable, and then produce full statistics in the subsequent
161 stages.
162 -?
164 --help
165 Show help about vacuumdb command line arguments, and exit.
166 vacuumdb also accepts the following command-line arguments for
168 connection parameters:
169 -h host
171 --host=host
172 Specifies the host name of the machine on which the server is
173 running. If the value begins with a slash, it is used as the
174 directory for the Unix domain socket.
175 -p port
177 --port=port
178 Specifies the TCP port or local Unix domain socket file extension
179 on which the server is listening for connections.
180 -U username
182 --username=username
183 User name to connect as.
184 -w
186 --no-password
187 Never issue a password prompt. If the server requires password
188 authentication and a password is not available by other means such
189 as a .pgpass file, the connection attempt will fail. This option
190 can be useful in batch jobs and scripts where no user is present to
191 enter a password.
192 -W
194 --password
195 Force vacuumdb to prompt for a password before connecting to a
196 database.
197 This option is never essential, since vacuumdb will automatically
199 prompt for a password if the server demands password
200 authentication. However, vacuumdb will waste a connection attempt
201 finding out that the server wants a password. In some cases it is
202 worth typing -W to avoid the extra connection attempt.
203 --maintenance-db=dbname
205 Specifies the name of the database to connect to to discover which
206 databases should be vacuumed, when -a/--all is used. If not
207 specified, the postgres database will be used, or if that does not
208 exist, template1 will be used. This can be a connection string. If
209 so, connection string parameters will override any conflicting
210 command line options. Also, connection string parameters other than
211 the database name itself will be re-used when connecting to other
212 databases.
213
215 PGDATABASE
216 PGHOST
217 PGPORT
218 PGUSER
219 Default connection parameters
220 PG_COLOR
222 Specifies whether to use color in diagnostic messages. Possible
223 values are always, auto and never.
224 This utility, like most other PostgreSQL utilities, also uses the
226 environment variables supported by libpq (see Section 33.14).
227
229 In case of difficulty, see VACUUM(7) and psql(1) for discussions of
230 potential problems and error messages. The database server must be
231 running at the targeted host. Also, any default connection settings and
232 environment variables used by the libpq front-end library will apply.
233
235 vacuumdb might need to connect several times to the PostgreSQL server,
236 asking for a password each time. It is convenient to have a ~/.pgpass
237 file in such cases. See Section 33.15 for more information.
238
240 To clean the database test:
241 $ vacuumdb test
243 To clean and analyze for the optimizer a database named bigdb:
245 $ vacuumdb --analyze bigdb
247 To clean a single table foo in a database named xyzzy, and analyze a
249 single column bar of the table for the optimizer:
250 $ vacuumdb --analyze --verbose --table='foo(bar)' xyzzy
252
254 VACUUM(7)
255PostgreSQL 13.4 2021 VACUUMDB(1)