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