Back Up a PostgreSQL Cluster with pg_backupcluster

You will create and verify either a physical PostgreSQL base backup or a logical dump with pg_backupcluster, then see how to list and expire the resulting files. Allow 15 minutes for a first test, plus the time needed to copy your database. This guide uses postgresql-common version 257build1.1, installed on Debian or Ubuntu systems with PostgreSQL 16.

The command is a front-end for pg_basebackup, pg_dump, pg_dumpall, pg_receivewal and pg_archivecleanup. It uses the cluster's PostgreSQL version and name in every command, for example 16 main. Replace those two values when your cluster differs.

1. Check the cluster and the backup destination

Start by confirming the exact cluster name and its state. This is a read-only check and does not need elevated privileges on a normally readable system:

$ pg_lsclusters
Ver Cluster Port Status Owner    Data directory              Log file
16  main    5432 online postgres /var/lib/postgresql/16/main /var/log/postgresql/postgresql-16-main.log
$ ls -ld /var/backups

pg_backupcluster stores its files below /var/backups/16-main by default. The command can create that directory when it is missing, but only a root invocation can do so if the parent or destination requires root access. The backup work then runs as the cluster owner. In practice, arrange the directory first with the account and permissions your backup policy requires:

# pg_backupcluster 16 main createdirectory
$ pg_backupcluster 16 main list

The first command needs root privileges because it creates directories under /var/backups. The second is an ordinary inspection command when the destination is readable.

Checkpoint: continue only when the cluster is the one you intended to protect and list can inspect its backup directory. Do not guess the version from a package name; use the row printed by pg_lsclusters.

2. Create a physical base backup

A base backup copies the cluster data and includes the WAL files required for recovery on startup. It is the useful choice when you need a physical restore of the cluster rather than a set of SQL and custom-format database files:

$ pg_backupcluster 16 main basebackup

For a busy production database, this can consume substantial disk space and network bandwidth. Check available space before starting and make sure your PostgreSQL backup role can perform the operation. The command passes the checkpoint setting to pg_basebackup. Its default is spread, which avoids concentrating checkpoint I/O; use fast only when the shorter checkpoint matters more than the extra I/O burst:

$ pg_backupcluster --checkpoint=spread 16 main basebackup

By default, a failed backup directory is removed. Add --keep-on-error when you need the incomplete files for diagnosis, not as a routine retention setting:

$ pg_backupcluster --keep-on-error 16 main basebackup

On success, inspect the result rather than trusting the exit status alone:

$ pg_backupcluster 16 main list
Base backups:
  ...
WAL:
  ...

A base backup directory is named with a timestamp and ends in .basebackup. It contains configuration in config.tar.gz, WAL and tablespace tarballs, backup_manifest, and a status file. The exact timestamp and listing layout are produced by the installed command, so scripts should not hard-code a particular timestamp.

3. Create a logical dump

A dump is a different recovery tool. It writes global objects to globals.sql, database creation settings to databases.sql, and each database in PostgreSQL custom format. It is suitable when you want to restore into a newly created cluster, but it does not preserve every property of the original cluster:

$ pg_backupcluster 16 main dump

The dump directory ends in .dump. Alongside the SQL and custom-format files, it includes config.tar.gz, which records the cluster configuration, and status. Keep the original cluster configuration under review: dump-style backups do not carry every initdb option. The installed manual specifically identifies encoding, locale settings and data checksums among the supported restore options, and notes that the earliest supported dump source is PostgreSQL 9.3.

Checkpoint: use list and inspect the files before calling a dump complete:

$ pg_backupcluster 16 main list
$ find /var/backups/16-main -maxdepth 2 -type f -name 'status' -o -name 'globals.sql'

The find command is only an inspection example. Keep the path specific to this cluster; searching all of /var/backups can produce unrelated system backup files.

4. Keep WAL available when you need archive recovery

receivewal launches pg_receivewal and writes WAL below /var/backups/16-main/wal. On PostgreSQL 10 and later, the command gzip-compresses those WAL files:

$ pg_backupcluster 16 main receivewal

This is a long-running operation, not a one-shot backup. Run it under the service supervision and logging system you use for backup jobs. It requires a suitable replication connection and must be stopped through that supervisor when you intentionally retire it. compresswal compresses WAL already in the archive, while archivecleanup removes obsolete WAL using pg_archivecleanup. Neither command should be run casually: deleting WAL can remove the recovery path for a base backup that has not yet been validated.

5. Expire old backups carefully

Retention actions keep the newest N items and remove older ones. They change state and can destroy your only usable restore point, so first run list, confirm the count and copy the output into your change record:

$ pg_backupcluster 16 main list
$ pg_backupcluster 16 main expirebasebackups 3
$ pg_backupcluster 16 main expiredumps 3
$ pg_backupcluster 16 main list

The two expiry actions are independent. Keeping three base backups does not keep three dumps. If a retention run removes the wrong files, stop further cleanup and recover them from your secondary backup or filesystem snapshot. There is no undo action in pg_backupcluster, so test the policy on a disposable backup directory before automating it.

Common traps

• Do not confuse basebackup with dump. The first is physical and WAL-aware; the second produces logical restore material.
• Do not omit the cluster version or name. The canonical syntax is pg_backupcluster [options] version cluster action. An alternative systemd-friendly spelling is also accepted: pg_basebackup version-cluster action.
• Do not run backup commands as root merely because the destination is under /var/backups. Root may create the directory, but the tool switches to the cluster owner for the backup work.
• Do not treat a directory's existence as proof of a valid backup. Check the command status, the status file, the expected contents and, ideally, a restore test.