How to back up a PostgreSQL Docker container (2026)
PostgreSQL needs a consistent dump before it touches restic. Dockstash runs `pg_dumpall -U "$POSTGRES_USER"` inside the container, captures the output, and stores it encrypted off-site — it never copies /var/lib/postgresql/data live, because pg_dumpall reads a consistent MVCC snapshot, so every database is captured at one point in time without blocking writers.
What Dockstash detects
| Env keys detected | POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
|---|---|
| Default port | 5432 |
| Live data paths (never copied live) | /var/lib/postgresql/data |
| Example images | postgres:16-alpine, postgres:16, postgres:15, postgres |
The dump command
pg_dumpall -U "$POSTGRES_USER"The restore command
psql -U "$POSTGRES_USER"pg_dumpall reads a consistent MVCC snapshot, so every database is captured at one point in time without blocking writers.
Gotchas to avoid
- Never restic the live /var/lib/postgresql/data directory — a heap page copied mid-write is torn and unrestorable.
- pg_dumpall captures roles and all databases; a single pg_dump misses global objects like roles and tablespaces.
- Extensions (PostGIS, pgvector) must be installed in the target image before restore or the SQL will error.
Do it in one click with Dockstash
Dockstash runs the exact dump above, restics it off-site, and drill-tests the restore automatically — no script to maintain.
Last updated: July 2026
Frequently asked questions
Why pg_dumpall instead of copying the data directory?
A live Postgres data directory is being written to constantly. Copying it captures a torn, inconsistent state that will not start. pg_dumpall reads a consistent MVCC snapshot from the running server, producing a dump that restores cleanly.
Does Dockstash lock the database during backup?
No. pg_dumpall uses MVCC snapshots, so reads are consistent without blocking writes. Your application keeps serving traffic during the dump.
How do I restore a single database instead of all of them?
A pg_dumpall archive is plain SQL; you can restore the whole cluster with psql, or use per-database pg_dump/pg_restore if you only need one. Dockstash restores the full consistent snapshot by default.
What about extensions like PostGIS or pgvector?
The dump references CREATE EXTENSION but does not ship the extension binaries. Make sure the restore-target image has the same extensions available before restoring.