pg_dump: Usage, Options & Common CI Errors

pg_dump writes a consistent snapshot of one Postgres database to a file.

pg_dump produces the backups and test fixtures pipelines restore later. The classic CI failure is a server-newer-than-client version mismatch, which pg_dump refuses outright.

What it does

pg_dump extracts a single database into a plain SQL script or a compressed archive (custom/directory/tar) that pg_restore can rebuild. It produces a transaction-consistent snapshot without blocking writers.

Common usage

Terminal

PGPASSWORD=secret pg_dump -h localhost -U postgres -d app -f dump.sql
pg_dump -h localhost -U postgres -Fc app > app.dump   # custom format
pg_dump -h localhost -U postgres -t users -d app > users.sql
pg_dump --no-owner --no-acl -h db -U postgres app > portable.sql

Options

Flag	What it does
-F c\|d\|t\|p	Format: custom / directory / tar / plain
-f <file>	Output file
-t <table>	Dump only matching tables
-n <schema>	Dump only matching schemas
--no-owner	Omit ownership (restore as any user)
--no-acl	Omit GRANT/REVOKE statements

Common errors in CI

pg_dump: error: server version: 16.x; pg_dump version: 15.x - pg_dump refuses to dump from a newer server. Install a client at least as new as the server (the postgresql-client-16 package) - this bites when the runner image lags the service container. "pg_dump: error: connection to server ... FATAL: password authentication failed" - same PGPASSWORD fix as psql. A plain-format dump restores with psql, but a custom/-Fc dump must be restored with pg_restore, not psql.