A file created providing meta-information about a backup

A backup_label is a file created at the top level of the data directory on the source node when an exclusive backup is started with pg_start_backup(), or in the target node's data directory when a backup is made via the replication protocol. It contains meta-information about a backup, in particular the backup start LSN, so the backed-up server knows when to start applying WAL when starting up for the first time.

The backup_label file is removed on the source node when pg_stop_backup() is executed, and on the target node renamed to backup_label.old once the server has successfully started.

Caveats with backup_label and exclusive backups

If an exclusive backup is in progress, and a crash situation occurs, the presence of the backup_label file means PostgreSQL is not able to determine whether it is starting as a backup or not, and will attempt to recover from the checkpoint location recorded in the file, which may reference WAL files no longer available.

For this reason, non-exclusive backups (supported by the replication protocol since PostgreSQL 9.1, and by pg_start_backup() since PostgreSQL 9.6) are the preferred method of making backups.

backup_label and non-exclusive backups

If the backup is made via the replication protocol's BASE_BACKUP command (which makes non-exclusive backups), the backup_label file is included in the streamed data.

If pg_start_backup() is called innon-exclusive backup mode, a backup_label file is not written; instead, the equivalent contents are returned by pg_start_backup(), and the caller is responsible for writing the file to the target node's data directory.

Source code

The backup label filenames are defined in src/include/access/xlog.h:

access/xlog.h:#define BACKUP_LABEL_FILE         "backup_label"
access/xlog.h:#define BACKUP_LABEL_OLD          "backup_label.old"


After starting an exclusive backup with SELECT pg_start_backup('test backup'), the following file is created in $PGDATA/backup_label:

START WAL LOCATION: 0/2000028 (file 000000010000000000000002)
BACKUP METHOD: pg_start_backup
BACKUP FROM: primary
START TIME: 2020-11-05 11:11:02 UTC
LABEL: test backup


Backup, Replication

See also

pg_start_backup(), Backup history file