backup_label
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 streaming 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 streaming 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 in non-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"
Examples
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) CHECKPOINT LOCATION: 0/2000098 BACKUP METHOD: pg_start_backup BACKUP FROM: primary START TIME: 2020-11-05 11:11:02 UTC LABEL: test backup START TIMELINE: 1