In PostgreSQL 17 and later, how do summarize_wal, pg_basebackup --incremental and pg_combinebackup fit together, and what breaks an incremental chain?
answer
- a background process records changed blocks
- pass the previous backup's manifest
- oldest to newest, full one first
- PostgreSQL does not track dependencies
basics
~20 sWith summarize_wal on, the server records which blocks WAL touched; pg_basebackup --incremental, given an earlier backup's manifest, copies only changed blocks; pg_combinebackup rebuilds a full backup from the chain. Missing summaries or a deleted earlier backup break it.
solid answer
~40 sSince PostgreSQL 17, `summarize_wal = on` (default `off`, reloadable) starts the WAL summarizer, which writes block-change summaries to `pg_wal/summaries`. `pg_basebackup --incremental=<earlier backup_manifest>` uploads that manifest; the server copies non-relation files whole and only changed blocks of relation files. An incremental backup cannot be started directly: `pg_combinebackup` takes the full backup then each incremental, oldest to newest, checks the chain, and writes a synthetic full backup with `-o`. A chain breaks when a backup it depends on is deleted (PostgreSQL does not track this), when summaries for the needed LSN range are gone (`wal_summary_keep_time`, default 10 days) or were never written, or when the reference was taken with `--no-manifest`. PostgreSQL 18 adds `pg_combinebackup --link`.
code
ini · 3 lines# postgresql.conf on claims-db1 (a reload is enough)
summarize_wal = on
wal_summary_keep_time = '14d'go deeper
Remember that PostgreSQL 17 added incremental pg_basebackup and that pg_combinebackup must rebuild a full backup before a restore.
Explain the three pieces: the WAL summarizer, passing the earlier backup's manifest to --incremental, and combining full plus incrementals oldest to newest.
Show you can run a chain: wal_summary_keep_time against your schedule, the failure messages, verifying inputs, and why deleting a full backup silently kills later incrementals.
Weigh incrementals against a backup manager's own incremental scheme, chain-management cost and restore time for a cluster whose data is mostly cold.
## The problem incremental backups solve A full base backup of the 2 TB insurance-claims cluster copies 2 TB every time, although most of it, years of settled claims, never changes. Since **PostgreSQL 17**, `pg_basebackup` can take an **incremental backup**: non-relation files are copied whole, but relation files are replaced by smaller files holding only the blocks changed since an earlier backup. `pg_combinebackup` later rebuilds a normal full backup from the chain. The nightly full copy can then be paired with cheap incrementals every few hours. ## Step 1: WAL summaries on the server The server finds changed blocks by reading **WAL summaries**, not by scanning files. - `summarize_wal = on` starts the **WAL summarizer** process. The default is `off`. It is set in `postgresql.conf` or on the command line and takes effect on reload. It works on a primary or a standby, and the server will not start with it on while `wal_level = minimal`. - Summaries are stored in `pg_wal/summaries`; each records which blocks of which relations the WAL in an LSN range modified. - `wal_summary_keep_time` (default 10 days; a bare number means minutes) deletes old summaries. Set it comfortably above the longest gap between a backup and the incremental that will depend on it. - `pg_get_wal_summarizer_state()` and `pg_available_wal_summaries()` show how far summarization has got. ## Step 2: taking the incremental `pg_basebackup --incremental=<path to an earlier backup's backup_manifest>` uploads that manifest. The reference may be a full backup or an earlier incremental. The server needs summaries covering every LSN from the **reference backup's start LSN** to the new backup's start LSN. It waits for the summarizer to catch up, and fails if it cannot: - with `summarize_wal` off: "incremental backups cannot be taken unless WAL summarization is enabled"; - with summaries removed or never written: "WAL summaries are required on timeline ... but no summaries for that timeline and LSN range exist". Changed relation files appear as `INCREMENTAL.<name>` files. An incremental backup **cannot be started as a server**. On a standby an incremental can also fail when almost nothing happened since the reference, because replay must begin at a later restartpoint than the reference backup used. ## Step 3: combining 1. List the backups **oldest to newest**: the full one first, then each incremental. 2. `pg_combinebackup` reads every `backup_label` and checks the chain: one system identifier, only the first backup full, and each backup starting at the LSN and timeline the next one was taken from. 3. It writes a **synthetic full backup**, plus a new `backup_manifest`, into the `-o` directory. It checks that the backups fit together, **not that each one is intact**; run `pg_verifybackup` on the inputs for that. It reads backup directories, so extract tar-format backups first. Its output can stand in for the chain in a later run, so the chain can be rolled forward. File transfer modes are `--copy` (default), `--clone` (reflinks on supporting file systems), `--copy-file-range`, and since **18** `-k`/`--link`, which hard-links files. With `--link`, starting a server on the output can modify the input backups, so use it only on copies you will throw away. ## What breaks a chain | Cause | Effect | |---|---| | The full or a middle incremental is deleted | every later incremental is useless; PostgreSQL keeps no record of dependencies | | Summaries aged out by `wal_summary_keep_time` | the next incremental fails to start | | `summarize_wal` switched off for a while | a gap in summaries; the next incremental fails | | Reference taken with `--no-manifest` | nothing to pass to `--incremental` | | Data checksums enabled with `pg_checksums` mid-chain | the combined output may hold pages with invalid checksums; take a new full backup | Incrementals pay off when much of the data is cold, as with closed claims. If nearly everything changes daily, they are barely smaller than fulls and only add a chain to manage. A restored synthetic full backup still needs WAL from its start onward and normal recovery, exactly like any full backup.
- pg_combinebackup succeeded. Does that prove the restored PostgreSQL backup is sound?No. It verifies only that the backups form a legal chain: same system identifier, a full first, matching start LSNs and timelines. It does not check each backup's files. Run `pg_verifybackup` on every input, and still restore with WAL replay to prove the result.
- How can you keep a PostgreSQL incremental chain from growing without limit?Take a new full backup on a schedule, or combine the existing chain into a synthetic full with `pg_combinebackup` and use that output as the base of the next run. Either way, delete old backups only when no retained incremental still depends on them.
- Why might an incremental pg_basebackup taken from a quiet PostgreSQL standby fail when the same command works on the primary?An incremental needs replay to start from a later checkpoint than its reference. On a primary each backup forces a checkpoint, so that always holds. A standby starts from its latest restartpoint, and with little activity no new restartpoint may exist since the previous backup.
A full backup is a base map and each incremental is a transparent overlay showing only the parcels redrawn since the previous sheet. Stack them in order and you see today's map; lose the base map or a middle overlay and the sheets above it show fragments of nothing.
- an incremental backup directory can be started as a server directly
- PostgreSQL tracks which incrementals depend on which full backup for you
- pg_combinebackup accepts the backups in any order and sorts them
- summarize_wal needs a restart and archive_mode = on
- pg_combinebackup also verifies that every file in each backup is intact
Assumes PostgreSQL 18; incremental pg_basebackup, pg_combinebackup and summarize_wal arrived in 17, and pg_combinebackup --link in 18.