Physical backups and the low-level API · PostgreSQL

A physical backup is a copy of PGDATA. That sounds trivial and it is not, because the copy takes time and the cluster does not stop changing while it runs.

Why a naive copy is not a backup

Copying a 500 GB data directory takes minutes to hours. During that time PostgreSQL is writing. A file copied at the start reflects one instant; a file copied at the end reflects another. The result is torn: an index pointing at a heap page that did not exist when the index was copied, a page half-written by the copy itself.

There are exactly two ways to get a usable physical backup:

Stop the cluster and copy the directory. Correct, and unavailable on anything you cannot take down.
Tell PostgreSQL you are copying, copy while it runs, and replay WAL over the result until it is consistent again.

The second is what “online backup” means, and every physical backup tool implements it.

What the low-level API actually does

SELECT pg_backup_start('label', fast => true);
-- copy PGDATA by whatever means
SELECT pg_backup_stop();

pg_backup_start() does three things that make the copy legal:

Forces a checkpoint, so there is a known redo point from which replay can begin. fast => true makes it an immediate checkpoint; false spreads it over checkpoint_completion_target, which is gentler and slower.
Guarantees full page writes are on for the duration, so every page touched during the copy has a complete image in WAL. This is why the torn pages a naive copy produces do not matter: replay overwrites them wholesale. Lesson XII-01 measured that effect — 473 full page images in the first UPDATE round after a checkpoint against 2 in the rounds that followed.
Records the start LSN, which becomes the point replay begins from.

pg_backup_stop() records the end LSN and returns the label.

Read-only / Safea complete low-level backup, in one session— Captured on 18.6. Note what pg_backup_stop returns.

$ psql -U postgres -X -f llapi.sql
# the file contains:
#   SELECT pg_backup_start('after-disconnect-test', true);
#   SELECT pg_backup_stop();

 pg_backup_start
-----------------
0/F000028

(0/F000120,"START WAL LOCATION: 0/F000028 (file 00000001000000000000000F)+
CHECKPOINT LOCATION: 0/F000080                                           +
BACKUP METHOD: streamed                                                  +
BACKUP FROM: primary                                                     +
START TIME: 2026-08-27 21:32:58 UTC                                      +
LABEL: after-disconnect-test                                             +
START TIMELINE: 1                                                        +
","")
NOTICE:  all required WAL segments have been archived

pg_backup_stop RETURNS the backup_label; it does not write it

The second column of that result is the contents of backup_label. In the non-exclusive API — the only API since PostgreSQL 15 — PostgreSQL does not write that file. The operator must write it into the copied directory.

A physical backup missing backup_label is worse than a failed backup. It starts. Without the label, PostgreSQL believes it is recovering from an ordinary crash and begins replay from the checkpoint recorded in pg_control — which, in a copy taken while the cluster was running, is earlier than the copy’s own contents. The result is a cluster that comes up, reports no error, and is silently inconsistent.

This is the single most common way a hand-rolled physical backup script goes wrong, and it is invisible until something reads the corrupted part.

The failure mode that catches people

A non-exclusive backup belongs to the session that started it.

Read-only / Safewhat the server log says when the session ends first— Real warning from 18.6, captured after a psql session that had called pg_backup_start exited without calling pg_backup_stop.

$ docker logs rbpg-pitr 2>&1 | grep -i abort

2026-08-27 21:32:50.904 UTC [576] WARNING:  aborting backup due to backend exiting before pg_backup_stop was called

A WARNING. Not an error, not a FATAL. If nothing is watching the server log, the backup script’s own output shows a start, a successful file copy, and an exit status of zero.

The practical consequence is that the low-level API cannot be driven from separate commands:

# BROKEN. Three sessions. The backup is aborted the moment the first
# psql exits, and the copy is of a cluster that is not in backup mode.
psql -c "SELECT pg_backup_start('nightly', true)"
tar czf /backup/base.tar.gz -C /var/lib/postgresql/18/main .
psql -c "SELECT pg_backup_stop()"

The copy still happens, the tarball still exists, and it is not a backup. The whole sequence must run inside one connection, which is why correct implementations use a client library holding the connection open across the copy rather than a shell script calling psql three times.

Read-only / Safea second backup in the same session— Real error from 18.6. Concurrent backups from different sessions are permitted; a second one in the same session is not.

$ SELECT pg_backup_start('second', true);

ERROR:  a backup is already in progress in this session

Read-only / Safebackup_label is absent from PGDATA during a non-exclusive backup— Captured on 18.6 while a backup was in progress.

$ SELECT count(*) AS backup_label_in_pgdata FROM pg_ls_dir('.') f WHERE f = 'backup_label';

 backup_label_in_pgdata
------------------------
                    0

What a correct low-level backup requires

One session, held open for the whole backup.
pg_backup_start().
Copy PGDATA, excluding postmaster.pid, pg_wal/’s contents, and the standard exclusions the documentation lists.
pg_backup_stop(); write the returned label to backup_label in the copy.
Ensure every WAL segment between start and end LSN is archived — pg_backup_stop()’s NOTICE: all required WAL segments have been archived is the confirmation.
Verify. A backup you have not restored is a hypothesis.

Why the exclusive API was removed, and what it broke

Before PostgreSQL 15 there was an exclusive backup mode where pg_start_backup() wrote backup_label into PGDATA itself. It was simpler to script and it had a failure mode severe enough that the community removed it.

If the server crashed during an exclusive backup, backup_label remained in PGDATA. On restart PostgreSQL found it, concluded it was restoring from a backup, and demanded WAL from the backup’s start LSN onward. If that WAL was not available the cluster refused to start — on the production primary, not on a copy.

The fix was to delete the stale backup_label, which was safe in that situation and catastrophic in the situation it resembles: deleting a real backup_label from a real restored backup produces the silent corruption described above. Two nearly identical symptoms, opposite correct actions, under outage pressure.

The non-exclusive API removes the ambiguity entirely by never writing the file. backup_label present in a data directory now means exactly one thing: this is a restored backup, and it needs its WAL.

The cost is that the API became harder to script, which is the real argument for not scripting it at all. pg_basebackup and the established backup tools handle every step correctly, and the low-level API is worth reaching for only when something about the environment — a storage-level clone, a very large cluster where a tool’s copy method is unacceptable — genuinely requires it.

What to take from this

A running cluster cannot be copied naively. The API plus WAL replay is what makes an online physical backup consistent.
pg_backup_start() forces a checkpoint, guarantees full page writes, and records the start LSN.
pg_backup_stop() returns backup_label. You must write it. Omitting it produces a cluster that starts and is silently wrong.
The backup is session-scoped. Losing the connection aborts it with a WARNING and nothing else.
Prefer pg_basebackup or an established tool. Use the low-level API only when the environment requires it.

Cross-course references

Linux for Production Sysadmins — Part XLVIII (Backup tools) covers snapshot-based copies and whether a snapshot is atomic across the volumes a cluster spans.
Ceph & Distributed Storage — Part XXXVII (RBD snapshots) and Part CVI (RBD backup) cover the same question on distributed storage, where crash consistency across images is not free.
Proxmox — Part XIII (Proxmox Backup Server) covers hypervisor snapshots of a running database and what they do and do not guarantee.