pg_basebackup: Usage, Options & Common CI Errors
pg_basebackup copies an entire running PostgreSQL cluster at the file level.
pg_basebackup creates the physical backups used to seed replicas or restore an entire cluster. Unlike pg_dump it copies the whole data directory and needs replication privileges.
What it does
pg_basebackup connects to a running server over the replication protocol and produces a binary copy of the entire database cluster - all databases at once - suitable for point-in-time recovery or standby setup. It is physical, not logical like pg_dump.
Common usage
pg_basebackup -h primary -U repl -D ./backup -Fp -Xs -P
pg_basebackup -h primary -U repl -D ./backup.tar -Ft -z # tar + gzip
pg_basebackup -h db -U repl -D ./standby -R # write standby config
PGPASSWORD=secret pg_basebackup -h primary -U repl -D ./b -c fastOptions
| Flag | What it does |
|---|---|
| -D <dir> | Destination directory |
| -F p|t | Output format: plain / tar |
| -X s|f | Include WAL via stream / fetch |
| -z / -Z | gzip-compress tar output |
| -R | Write standby.signal + connection config |
| -P | Show progress |
Common errors in CI
FATAL: no pg_hba.conf entry for replication connection from host ... - the server is not configured to allow replication from the runner; add a replication entry and a role with the REPLICATION attribute. "FATAL: number of requested standby connections exceeds max_wal_senders" means max_wal_senders is too low. The destination directory must be empty; otherwise pg_basebackup errors that it is not empty.