pg_restore Command Reference: Flags, Usage & CI Examples

pg_restore rebuilds a database from a pg_dump custom, directory, or tar archive.

pg_restore reads an archive produced by pg_dump and recreates the database objects and data, optionally in parallel. It is the counterpart to pg_dump for archive formats.

Common flags and usage

-d <db>: target database to restore into
-C: create the database first (connect to another db)
--clean: drop objects before recreating them
-j <N>: restore with N parallel jobs
--no-owner: do not set object ownership
--exit-on-error: stop and fail on the first error

Example

shell

PGPASSWORD=${PGPASSWORD} pg_restore -h localhost -U postgres -d app --clean --no-owner app.dump
PGPASSWORD=${PGPASSWORD} pg_restore -h localhost -U postgres -d app -j4 --exit-on-error app.dump

In CI

pg_restore reads only archive formats; handing it a plain-SQL dump fails with "input file does not appear to be a valid archive" (use psql -f instead). Errors during data load do not stop the restore by default, so add --exit-on-error to fail the step.

Key takeaways

pg_restore loads custom/directory/tar archives, not plain SQL.
-j runs parallel jobs; --clean drops objects before recreating.
Add --exit-on-error so data-load failures fail the CI step.