PostgreSQL 17 Incremental Backup: pg_basebackup and pg_combinebackup Explained

If you manage a 2TB PostgreSQL database, you know the pain: daily full backups that chew through a 4-hour window, strain your storage budget, and leave a narrow margin for anything to go wrong before your backup overlaps with your next scheduled run. PostgreSQL has long relied on third-party tools like pgBackRest and Barman to handle incremental backups, leaving teams to bolt on complexity that the database core simply didn't support natively. PostgreSQL 17 finally changes that. With native incremental backup support built directly into pg_basebackup, you can now capture only the blocks that changed since your last backup — dramatically shrinking backup windows and storage costs without reaching for external tooling. This guide walks through everything you need to know to put it into production.

What's New in PostgreSQL 17 Backup?

Prior to PostgreSQL 17, pg_basebackup only supported full backups — every run copied every byte of every data file, regardless of what had changed since the last backup. Incremental backup was the domain of tools like pgBackRest, which tracked block-level changes using methods outside the core engine.

PostgreSQL 17 introduces two complementary features that together enable native incremental backup:

• WAL summarization (summarize_wal): A background process that reads WAL records and builds compact summary files tracking which blocks in which data files were modified during each WAL range.
• pg_combinebackup: A new standalone utility that takes a full backup plus one or more incremental backups and combines them into a single synthetic full backup ready for restore.

The incremental backup support in pg_basebackup is a server-side feature — the server generates WAL summaries, the backup client reads them to determine what to copy, and pg_combinebackup assembles the pieces offline. This means you get proper incremental backups without shipping a backup agent or installing a separate backup tool.

How Incremental Backup Works

WAL Summary Tracking

When summarize_wal = on is set, PostgreSQL runs a WAL summarizer background process. This process reads WAL records as they are generated and writes summary files to $PGDATA/pg_wal/summaries/. Each summary file covers a range of WAL (from LSN X to LSN Y) and records, for each data file modified during that range, the exact set of blocks that were written.

Summary files are small — a heavily-written database generating gigabytes of WAL per day might produce only a few megabytes of summary files. They are also cumulative: if block 42 of a relation is written 1,000 times during a WAL range, the summary records that block 42 was modified, not that it was modified 1,000 times.

Changed Block Detection

When you run pg_basebackup --incremental, you supply the manifest from your previous backup. The manifest records the LSN at which that backup ended. pg_basebackup asks the server: "which blocks changed between that LSN and now?" The server consults the WAL summaries and returns the list. The backup client then copies only those blocks, plus all WAL generated since the last backup, plus a new manifest for the incremental backup itself.

The result: an incremental backup contains only the data file blocks that actually changed, not full copies of unchanged relations. A database where 5% of blocks change daily produces an incremental backup roughly 5% the size of a full backup.

Setting Up the First Full Backup with pg_basebackup

Enable WAL Summarization

Before taking any backup, enable WAL summarization in postgresql.conf:

summarize_wal = on

Apply the change:

psql -U postgres -c "ALTER SYSTEM SET summarize_wal = on;"
psql -U postgres -c "SELECT pg_reload_conf();"

Verify the summarizer is running:

psql -U postgres -c "SELECT * FROM pg_stat_activity WHERE backend_type = 'walsummarizer';"

You also need WAL archiving or a replication slot to ensure WAL is retained long enough to cover the gap between your full backup and each incremental. Set wal_level = replica at minimum:

wal_level = replica
archive_mode = on
archive_command = 'cp %p /mnt/wal-archive/%f'

Take the Full Backup

Take an initial full backup with --checkpoint=fast and --manifest-checksums=sha256 to produce a manifest suitable for subsequent incrementals:

pg_basebackup \
  --host=localhost \
  --port=5432 \
  --username=replicator \
  --pgdata=/mnt/backups/full-2025-01-20 \
  --format=plain \
  --wal-method=stream \
  --checkpoint=fast \
  --manifest-checksums=sha256 \
  --progress \
  --verbose

After completion, the backup directory contains a backup_manifest file. This file is the key input for all subsequent incremental backups. Store it alongside the backup and never modify it.

ls /mnt/backups/full-2025-01-20/backup_manifest

Taking Incremental Backups

First Incremental

Reference the full backup's manifest using the --incremental flag:

pg_basebackup \
  --host=localhost \
  --port=5432 \
  --username=replicator \
  --pgdata=/mnt/backups/incr-2025-01-21 \
  --incremental=/mnt/backups/full-2025-01-20/backup_manifest \
  --format=plain \
  --wal-method=stream \
  --checkpoint=fast \
  --manifest-checksums=sha256 \
  --progress \
  --verbose

The incremental backup directory has the same structure as a full backup but data files contain only the changed blocks. The backup size on a lightly-modified database may be a fraction of the full backup.

Chaining Incrementals

Each incremental backup produces its own backup_manifest. To chain incrementals, reference the previous incremental's manifest:

# Second incremental — references the first incremental's manifest
pg_basebackup \
  --host=localhost \
  --port=5432 \
  --username=replicator \
  --pgdata=/mnt/backups/incr-2025-01-22 \
  --incremental=/mnt/backups/incr-2025-01-21/backup_manifest \
  --format=plain \
  --wal-method=stream \
  --checkpoint=fast \
  --manifest-checksums=sha256 \
  --progress \
  --verbose

You can chain as many incrementals as needed. Each one only captures blocks that changed since the previous backup in the chain.

Restoring with pg_combinebackup

How pg_combinebackup Works

pg_combinebackup takes your full backup plus all incrementals in chronological order and produces a single synthetic full backup directory. You then restore from that synthetic backup exactly as you would from a plain full backup.

Combining a Full Backup with Two Incrementals

pg_combinebackup \
  /mnt/backups/full-2025-01-20 \
  /mnt/backups/incr-2025-01-21 \
  /mnt/backups/incr-2025-01-22 \
  --output=/mnt/restore/combined-2025-01-22

The order matters: full backup first, then each incremental in the sequence they were taken. pg_combinebackup verifies the manifest chain as it goes — if you supply them out of order or skip one, it will error out.

Completing the Restore

After combining, the output directory is a valid PostgreSQL data directory. Copy it into place and apply WAL to reach your target recovery point:

# Stop PostgreSQL if running
pg_ctl stop -D /var/lib/postgresql/17/main

# Copy combined backup into place
rsync -av --delete /mnt/restore/combined-2025-01-22/ /var/lib/postgresql/17/main/

# Configure recovery target (if using PITR)
cat > /var/lib/postgresql/17/main/postgresql.conf <

#!/usr/bin/env bash
# /usr/local/bin/pg-incremental-backup.sh

set -euo pipefail

BACKUP_BASE="/mnt/backups"
HOST="localhost"
PORT="5432"
USER="replicator"
DATE=$(date +%Y-%m-%d)
DAY_OF_WEEK=$(date +%u)  # 1=Monday, 7=Sunday

if [ "$DAY_OF_WEEK" -eq 7 ]; then
  # Sunday: full backup
  BACKUP_DIR="$BACKUP_BASE/full-$DATE"
  pg_basebackup \
    --host="$HOST" --port="$PORT" --username="$USER" \
    --pgdata="$BACKUP_DIR" \
    --format=plain --wal-method=stream \
    --checkpoint=fast --manifest-checksums=sha256 \
    --progress
  # Record manifest path for this week's chain
  echo "$BACKUP_DIR/backup_manifest" > "$BACKUP_BASE/latest_manifest"
else
  # Mon–Sat: incremental backup
  PREV_MANIFEST=$(cat "$BACKUP_BASE/latest_manifest")
  BACKUP_DIR="$BACKUP_BASE/incr-$DATE"
  pg_basebackup \
    --host="$HOST" --port="$PORT" --username="$USER" \
    --pgdata="$BACKUP_DIR" \
    --incremental="$PREV_MANIFEST" \
    --format=plain --wal-method=stream \
    --checkpoint=fast --manifest-checksums=sha256 \
    --progress
  # Update manifest pointer to latest incremental
  echo "$BACKUP_DIR/backup_manifest" > "$BACKUP_BASE/latest_manifest"
fi

echo "Backup completed: $BACKUP_DIR"

# Add to cron
0 2 * * * /usr/local/bin/pg-incremental-backup.sh >> /var/log/pg-backup.log 2>&1

# Remove backups older than 14 days
find /mnt/backups -maxdepth 1 -type d -mtime +14 -exec rm -rf {} \;