Architecture

pg_basebackup in Practice: Full and Incremental PostgreSQL Backups

pg_basebackup is the backup tool that ships with PostgreSQL, and since version 17 it can take incremental backups too. Here is how to run it correctly, verify what it produced, restore it, and keep it from hurting a multi-terabyte primary.

· 14 min read · AG Data Team

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

-- 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:

Two options deserve a deliberate choice rather than a copy-paste:

Building a replica? Add -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

  1. Stop the server and move the old data directory aside rather than deleting it, if you have the space.
  2. Create an empty data directory with the right owner and 0700 permissions.
  3. For tar format, extract base.tar into it, each tablespace tar into its own location, and pg_wal.tar into pg_wal/. For incremental chains, run pg_combinebackup into the new directory instead.
  4. For a restore to "the end of the backup", just start the server: it replays the included WAL to a consistent state.
  5. For a restore to a later moment, add recovery.signal, a restore_command and 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:

Key takeaways

PostgreSQL pg_basebackup Backups Incremental backup
Work with us

Not sure your backups would restore?

We design and test PostgreSQL backup and restore for databases from a few hundred gigabytes to many terabytes, including real restore drills with measured recovery time.

Get in touch More from the blog