<!-- doc/src/sgml/backup-manifest.sgml -->

<chapter id="backup-manifest-format">
 <title>Backup Manifest Format</title>

  <indexterm>
   <primary>Backup Manifest</primary>
  </indexterm>

  <para>
   The backup manifest generated by <xref linkend="app-pgbasebackup" /> is
   primarily intended to permit the backup to be verified using
   <xref linkend="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.
  </para>

  <para>
   A backup manifest is a JSON document encoded as UTF-8. (Although in
   general JSON documents are required to be Unicode, PostgreSQL permits
   the <type>json</type> and <type>jsonb</type> 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.
  </para>

 <sect1 id="backup-manifest-toplevel">
  <title>Backup Manifest Top-level Object</title>

  <para>
   The backup manifest JSON document contains the following keys.
  </para>

  <variablelist>
   <varlistentry>
    <term><literal>PostgreSQL-Backup-Manifest-Version</literal></term>
    <listitem>
     <para>
      The associated value is an integer. Beginning in
      <productname>PostgreSQL</productname> <literal>17</literal>,
      it is <literal>2</literal>; in older versions, it is <literal>1</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>System-Identifier</literal></term>
    <listitem>
     <para>
      The database system identifier of the
      <productname>PostgreSQL</productname> instance where the backup was
      taken.  This field is present only when
      <literal>PostgreSQL-Backup-Manifest-Version</literal> is
      <literal>2</literal>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Files</literal></term>
    <listitem>
     <para>
      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 <xref linkend="backup-manifest-files" />.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>WAL-Ranges</literal></term>
    <listitem>
     <para>
      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 <xref linkend="backup-manifest-wal-ranges" />.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Manifest-Checksum</literal></term>
    <listitem>
     <para>
      This key is always present on the last line of the backup manifest file.
      The associated value is a SHA-256 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 SHA-256 checksum
      is significantly more expensive than a CRC-32C checksum, the manifest
      should normally be small enough that the extra computation won't matter
      very much.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </sect1>

 <sect1 id="backup-manifest-files">
  <title>Backup Manifest File Object</title>

  <para>
   The object which describes a single file contains either a
   <literal>Path</literal> key or an <literal>Encoded-Path</literal> key.
   Normally, the <literal>Path</literal> key will be present. The
   associated