Backup Manifest Format
======================

Backup Manifest

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.

Backup Manifest Top-level Object {#backup-manifest-toplevel}
================================

The backup manifest JSON document contains the following keys.

`PostgreSQL-Backup-Manifest-Version`

:   The associated value is always the integer 1.

`Files`

:   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 File
    Object](#backup-manifest-files).

`WAL-Ranges`

:   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 Range
    Object](#backup-manifest-wal-ranges).

`Manifest-Checksum`

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

Backup Manifest File Object {#backup-manifest-files}
===========================

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:

`Size`

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

`Last-Modified`

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

`Checksum-Algorithm`

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

`Checksum`

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

Backup Manifest WAL Range Object {#backup-manifest-wal-ranges}
================================

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

`Timeline`

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

`Start-LSN`

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

`End-LSN`

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