pg_basebackup takes a physical copy of a running PostgreSQL cluster over the replication protocol, without stopping the server or affecting other clients. It is the base for point-in-time recovery, for building new replicas, and, since PostgreSQL 17, for incremental backups. It is also easy to run in a way that looks fine until the day you need to restore.
What pg_basebackup is, and what it is not
pg_basebackup copies the data files of the whole cluster: every database, every tablespace, plus the WAL needed to make that copy consistent. The documentation is explicit that you cannot back up a single database or a single table with it (pg_basebackup). If that is what you need, use a logical dump, and read our notes on pg_dump for large databases first.
The trade-off is simple. A physical backup restores much faster than a logical dump on a big database, because nothing has to be re-inserted and no indexes have to be rebuilt. But it only restores to the same PostgreSQL major version, and it carries bloat and everything else along with the data.
Prerequisites
- A role with the
REPLICATIONattribute, or a superuser. - A
pg_hba.confline that allows a replication connection from the backup host. - Enough
max_wal_senders. The default is 10 (replication settings). In the default streaming mode pg_basebackup opens two replication connections, one for the data and one for WAL, so a busy cluster with several replicas can run out.
-- on the server
CREATE ROLE replicator WITH LOGIN REPLICATION PASSWORD '...';
# pg_hba.conf: replication connections are matched by the keyword "replication"
host replication replicator 10.0.0.0/24 scram-sha-256
A sensible full backup command
pg_basebackup -h db1 -U replicator \
-D /backups/full-2026-11-17 \
-F t -Z zstd -X stream \
-P -v -l "nightly full"
What each part does, according to the reference page:
-Dis required. The directory is created if missing and must be empty if it exists.-F twrites tar files:base.tar, one tar per extra tablespace named by its OID, andpg_wal.tarfor the streamed WAL. The default is plain format, a ready-to-use data directory.-Z zstdcompresses on the client by default;-Z server-zstdmoves the work to the server and saves network bandwidth. Plain format allows only server-side compression. One gotcha: with streamed WAL,pg_wal.taris compressed only with client-side gzip, not with zstd or lz4.-X streamis the default. WAL is streamed while the copy runs, and on PostgreSQL 10 and later a temporary replication slot is used automatically so the primary does not recycle WAL the backup still needs. As long as WAL is included, you can start a server on the backup without the WAL archive at all.-lsets the label that ends up in the backup history file in your WAL archive.
Two options deserve a deliberate choice rather than a copy-paste:
-c fastversus the defaultspread. Withspreadthe backup waits for a normal spread-out checkpoint, so it can look idle for minutes at the start.faststarts immediately but forces an immediate checkpoint, which on a write-heavy server is a burst of I/O. For nightly jobs we keepspread; for "I need a copy now" we usefast.-X fetchcollects WAL only at the end. If the needed segments were recycled in the meantime, the docs say plainly that the backup will fail and be unusable. Withwal_keep_sizeat its default of 0, stick withstream.
-R. It creates standby.signal and appends the connection settings to postgresql.auto.conf, so the copy starts as a standby of the server you backed up.Verify every backup with pg_verifybackup
By default pg_basebackup writes a backup_manifest with a CRC32C checksum for every file. pg_verifybackup reads that manifest and checks that every expected file is present with the right size and checksum, and, for plain-format backups, parses the WAL required for recovery with pg_waldump.
# plain format: checks files, checksums and the WAL needed for recovery
pg_verifybackup /backups/full-plain
# tar format: WAL parsing is not supported, so skip it
pg_verifybackup -F t -n /backups/full-2026-11-17
It catches truncated copies, missing files and bit rot on the backup disk. The documentation is honest about the limit: it cannot find every problem a running server would hit, so it does not replace a test restore. CRC32C is fast but not resistant to deliberate tampering; if that matters, choose a SHA algorithm and keep the manifest somewhere separate.
Incremental backups in PostgreSQL 17 and later
Since PostgreSQL 17, pg_basebackup can take an incremental backup that contains only the blocks changed since an earlier backup. It needs the WAL summarizer, which is off by default (WAL settings):
# postgresql.conf or server command line, not per session
wal_level = replica # summarize_wal does not work with minimal
summarize_wal = on # default off
wal_summary_keep_time = 10d # the default
# Sunday: full backup
pg_basebackup -h db1 -U replicator -D /backups/full -c fast
# Monday: incremental against Sunday's manifest
pg_basebackup -h db1 -U replicator -D /backups/incr1 \
--incremental=/backups/full/backup_manifest
# Tuesday: incremental against Monday
pg_basebackup -h db1 -U replicator -D /backups/incr2 \
--incremental=/backups/incr1/backup_manifest
The server works out which blocks changed from WAL summaries in pg_wal/summaries. Those summaries must cover every LSN from the start of the reference backup to the start of the new one, or the incremental backup fails (continuous archiving). Summaries are removed after wal_summary_keep_time, 10 days by default, so a reference backup older than that may no longer work as a base. Keep your full-backup cycle well inside that window, or raise it.
An incremental backup cannot be started directly. pg_combinebackup rebuilds a synthetic full backup from the chain, listed from oldest to newest:
# oldest first, newest last; -o is required
pg_combinebackup /backups/full /backups/incr1 /backups/incr2 \
-o /restore/pgdata
# same file system with reflink support: near-instant copy
pg_combinebackup --clone /backups/full /backups/incr1 /backups/incr2 -o /restore/pgdata
The chain is only as strong as its weakest link. Delete one earlier backup and every incremental after it is unrestorable. pg_combinebackup checks that the backups form a valid chain, not that each one is intact, so run pg_verifybackup on each piece as well.
Restoring a pg_basebackup
- Stop the server and move the old data directory aside rather than deleting it, if you have the space.
- Create an empty data directory with the right owner and
0700permissions. - For tar format, extract
base.tarinto it, each tablespace tar into its own location, andpg_wal.tarintopg_wal/. For incremental chains, run pg_combinebackup into the new directory instead. - For a restore to "the end of the backup", just start the server: it replays the included WAL to a consistent state.
- For a restore to a later moment, add
recovery.signal, arestore_commandand a recovery target. The full procedure is in our PostgreSQL point-in-time recovery guide.
pg_basebackup on large databases
Everything above works on a 20 GB test instance. At several terabytes, a few things change, and they are the ones that cause real incidents:
- Duration and WAL retention. A multi-terabyte copy takes hours. For that whole time the temporary slot holds WAL on the primary. With
max_slot_wal_keep_sizeat its default of -1 there is no cap, so on a write-heavy systempg_walcan grow by hundreds of gigabytes. Size the disk for it, or set a cap and accept that a too-slow backup will be invalidated rather than filling the disk. - Throughput. In our experience a single pg_basebackup run tends to be limited by one stream's throughput long before the storage is saturated. Measure it once on production-sized data and multiply: if a full copy takes nine hours, nightly fulls are a bad plan. For very large clusters, tools with parallel transfer such as pgBackRest are often the better fit.
- Load on the primary.
--max-rate(32 kB/s to 1024 MB/s) throttles the transfer so the backup does not starve production reads. Server-side compression trades network for primary CPU, so decide which one you are short of. - Back up from a standby. This takes the read load off the primary. The documented conditions:
full_page_writeson the primary, a replication-enabledpg_hba.confon the standby, and the knowledge that if the standby is promoted mid-backup, the backup fails. - Incremental changes the maths. Daily incrementals can cut transfer and storage dramatically on a database where most data is cold. But pg_combinebackup needs room for a full-size output;
--cloneor--linkon the same file system avoids most of the copying. - Restore time is the number that matters. Measure it: extraction, combining, WAL replay. A backup you have never restored at full size is a hope, not a recovery plan.
Key takeaways
- pg_basebackup copies the whole cluster; for single databases use pg_dump.
- Keep the default
-X stream; choose-c fastorspreaddeliberately. - Run pg_verifybackup after every backup, and still do test restores.
- PostgreSQL 17+ incremental backups need
summarize_wal = on, an unbroken chain and pg_combinebackup to restore. - At terabyte scale, plan for hours of WAL retention, throttle with
--max-rate, consider a standby as the source and measure real restore time.