Physical Base Backups, pg_basebackup, Tablespaces, and Backup Manifests

Learning outcomes

Logical dumps are excellent when you need SQL-level portability or selected objects. They are not the same artifact used for fast whole-cluster physical recovery or as the starting point for continuous WAL replay. A physical base backup captures PostgreSQL's cluster files in a recovery-consistent form. pg_basebackup obtains that backup from a running server through the replication protocol.

1. Prerequisites are operational, not only syntax

pg_basebackup uses a replication connection. The source must allow replication authentication, and the connecting role needs the appropriate replication privilege. On a local disposable lab you can use a dedicated servicehub_backup login rather than normal application credentials.

CREATE ROLE servicehub_backupLOGIN REPLICATIONPASSWORD 'replace-this-disposable-lab-secret';

host replication servicehub_backup 127.0.0.1/32 scram-sha-256

Reload pg_hba.conf after adding an authentication rule. Do not paste production credentials into shell history; use a controlled .pgpass or equivalent secret mechanism.

2. Take a full base backup with streamed WAL

pg_basebackup \  --host=localhost --port=55432 --username=servicehub_backup \  --pgdata=./ch13_base_full \  --format=plain \  --wal-method=stream \  --progress --verbose \  --manifest-checksums=SHA256

With streamed WAL, pg_basebackup opens an additional replication connection and streams the WAL required to make the backup recoverable. A temporary replication slot is normally used when streaming without an explicit slot, preventing required WAL from disappearing during the backup. That protects the backup process, but it also means replication-slot capacity and max_wal_senders matter.

SELECT pid, phase,       backup_total, backup_streamed,       tablespaces_total, tablespaces_streamedFROM pg_stat_progress_basebackup;

3. Tablespaces change where physical files must land

In plain format, user tablespaces normally map to their original filesystem locations unless --tablespace-mapping is supplied. That can make same-host lab backups fail or overwrite assumptions. Tar format produces separate tar archives for additional tablespaces; correct extraction locations are still the operator's responsibility.

pg_basebackup -h localhost -p 55432 -U servicehub_backup \  -D ./ch13_base_mapped -Fp -X stream -P \  -T /srv/postgres/ts_fast=$(pwd)/ch13_base_mapped/ts_fast

Only use a mapping that corresponds to an actual tablespace path on the source. The example is a pattern, not a request to create that path.

4. The backup manifest is evidence, not a boot test

By default a base backup includes backup_manifest. It lists backed-up files and metadata and can contain checksums. pg_verifybackup checks the backup against that manifest and verifies required WAL records when available. This is valuable integrity evidence, but it is still not the same as successfully starting a restored cluster and validating the application.

head -40 ch13_base_full/backup_manifestpg_verifybackup --progress ch13_base_full

5. Physical backups are version-sensitive

A physical backup is an exact representation of a PostgreSQL cluster's storage. Restore it with a compatible PostgreSQL server environment; do not use a physical copy as a major-version migration technique. Logical dump/restore and pg_upgrade are the normal migration families for major-version changes. Architecture, filesystem semantics, tablespaces, extensions, and configuration files also need review.

PostgreSQL 18 also supports incremental base backups, but an incremental backup is not directly startable: it must be combined with its dependency chain using pg_combinebackup. Because Prompt 13 centers on base-backup/PITR fundamentals, the mandatory lab uses a full backup; incremental backup is an optional extension of the same restore-first discipline.

ls -lah ch13_base_fullls -lah ch13_base_full/pg_wal | head

6. WAL method and backup completeness

--wal-method=stream streams the WAL needed by the backup while the files are copied. --wal-method=fetch waits until the end and then fetches required WAL, which means the source must retain those segments for the whole backup duration. Streaming is therefore the safer general default when enough replication connections are available. A backup that finishes without the WAL required for consistency is not a startable recovery point.

The resulting backup contains backup_label information that identifies the checkpoint/start positions required for recovery. Treat this as server-managed recovery metadata; do not hand-edit it to make a damaged backup “work.” The manifest is separate: it describes expected files and checksums for verification.

Client/server compatibility

pg_basebackup can connect to servers of the same or older major versions within its documented compatibility range, but the produced physical backup remains a backup of the source server's storage format. The practical restore target should run the matching PostgreSQL major and compatible extensions/operating environment. This is fundamentally different from pg_dump's logical cross-version role.

Restore proof after pg_verifybackup

After pg_verifybackup, copy the verified backup to a disposable restore directory, map any tablespaces, start PostgreSQL on a nonproduction port, and validate pg_control, catalogs, extensions, row counts, and business invariants. The startup test catches configuration, permission, platform, and recovery issues that manifest verification cannot prove.

Authoritative references

Backup and recovery behavior is version-, topology-, privilege-, and storage-sensitive. These primary PostgreSQL sources define the mechanisms used in this lesson.

• PostgreSQL 18 — pg_basebackup
• PostgreSQL 18 — pg_verifybackup
• PostgreSQL 18 — Backup Manifest Format
• PostgreSQL 18 — Backup and Restore