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.
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.
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.
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.
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
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