vacuumdb: Usage, Options & Common CI Errors
vacuumdb reclaims storage and refreshes planner statistics for Postgres.
vacuumdb is run after large data loads in CI so query plans use fresh statistics. It is a wrapper around VACUUM and ANALYZE that can target whole clusters and run in parallel.
What it does
vacuumdb connects to a server and runs VACUUM (and optionally ANALYZE) to reclaim dead-tuple space and update the statistics the query planner relies on. It can process one database, all databases, or specific tables.
Common usage
PGPASSWORD=secret vacuumdb -h localhost -U postgres -z app
vacuumdb -h localhost -U postgres --analyze-only -d app
vacuumdb -h db -U postgres -a # all databases
vacuumdb -h localhost -U postgres -j4 -z app # 4 parallel jobsOptions
| Flag | What it does |
|---|---|
| -z / --analyze | Also update planner statistics |
| --analyze-only | Only ANALYZE, do not VACUUM |
| -f / --full | VACUUM FULL (rewrites tables; takes a lock) |
| -a / --all | Process every database |
| -j <N> | Run N concurrent connections |
| -t <table> | Restrict to a table |
Common errors in CI
vacuumdb: error: ... FATAL: password authentication failed - same PGPASSWORD fix as psql. -f / VACUUM FULL takes an ACCESS EXCLUSIVE lock and rewrites the table, so it can block other steps and is rarely needed in CI; prefer plain -z. "WARNING: skipping ... only superuser or owner can vacuum it" means the connecting role does not own the objects.