9.25. Backup Manifest Format

The backup manifest generated by app-pgbasebackup is primarily intended to permit the backup to be verified using app-pgverifybackup. However, it is also possible for other tools to read the backup manifest file and use the information contained therein for their own purposes. To that end, this chapter describes the format of the backup manifest file.

A backup manifest is a JSON document encoded as UTF-8. (Although in general JSON documents are required to be Unicode, PostgreSQL permits the json and jsonb data types to be used with any supported server encoding. There is no similar exception for backup manifests.) The JSON document is always an object; the keys that are present in this object are described in the next section.

9.25.1. Backup Manifest Top-level Object

The backup manifest JSON document contains the following keys.

  1. The associated value is always the integer 1.

  2. The associated value is always a list of objects, each describing one file that is present in the backup. No entries are present in this list for the WAL files that are needed in order to use the backup, or for the backup manifest itself. The structure of each object in the list is described in backup-manifest-files.

  3. The associated value is always a list of objects, each describing a range of WAL records that must be readable from a particular timeline in order to make use of the backup. The structure of these objects is further described in backup-manifest-wal-ranges.

  4. This key is always present on the last line of the backup manifest file. The associated value is a SHA256 checksum of all the preceding lines. We use a fixed checksum method here to make it possible for clients to do incremental parsing of the manifest. While a SHA256 checksum is significantly more expensive than a CRC32C checksum, the manifest should normally be small enough that the extra computation won’t matter very much.

9.25.2. Backup Manifest File Object

The object which describes a single file contains either a Path key or an Encoded-Path key. Normally, the Path key will be present. The associated string value is the path of the file relative to the root of the backup directory. Files located in a user-defined tablespace will have paths whose first two components are pg_tblspc and the OID of the tablespace. If the path is not a string that is legal in UTF-8, or if the user requests that encoded paths be used for all files, then the Encoded-Path key will be present instead. This stores the same data, but it is encoded as a string of hexadecimal digits. Each pair of hexadecimal digits in the string represents a single octet.

The following two keys are always present:

  1. The expected size of this file, as an integer.

  2. The last modification time of the file as reported by the server at the time of the backup. Unlike the other fields stored in the backup, this field is not used by app-pgverifybackup. It is included only for informational purposes.

If the backup was taken with file checksums enabled, the following keys will be present:

  1. The checksum algorithm used to compute a checksum for this file. Currently, this will be the same for every file in the backup manifest, but this may change in future releases. At present, the supported checksum algorithms are CRC32C, SHA224, SHA256, SHA384, and SHA512.

  2. The checksum computed for this file, stored as a series of hexadecimal characters, two for each byte of the checksum.

9.25.3. Backup Manifest WAL Range Object

The object which describes a WAL range always has three keys:

  1. The timeline for this range of WAL records, as an integer.

  2. The LSN at which replay must begin on the indicated timeline in order to make use of this backup. The LSN is stored in the format normally used by PostgreSQL; that is, it is a string consisting of two strings of hexadecimal characters, each with a length of between 1 and 8, separated by a slash.

  3. The earliest LSN at which replay on the indicated timeline may end when making use of this backup. This is stored in the same format as Start-LSN.

Ordinarily, there will be only a single WAL range. However, if a backup is taken from a standby which switches timelines during the backup due to an upstream promotion, it is possible for multiple ranges to be present, each with a different timeline. There will never be multiple WAL ranges present for the same timeline.