1<!-- doc/src/sgml/backupmanifest.sgml -->
2
3<chapter id="backup-manifest-format">
4 <title>Backup Manifest Format</title>
5
6  <indexterm>
7   <primary>Backup Manifest</primary>
8  </indexterm>
9
10  <para>
11   The backup manifest generated by <xref linkend="app-pgbasebackup" /> is
12   primarily intended to permit the backup to be verified using
13   <xref linkend="app-pgverifybackup" />. However, it is
14   also possible for other tools to read the backup manifest file and use
15   the information contained therein for their own purposes. To that end,
16   this chapter describes the format of the backup manifest file.
17  </para>
18
19  <para>
20   A backup manifest is a JSON document encoded as UTF-8. (Although in
21   general JSON documents are required to be Unicode, PostgreSQL permits
22   the <type>json</type> and <type>jsonb</type> data types to be used with any
23   supported server encoding. There is no similar exception for backup
24   manifests.) The JSON document is always an object; the keys that are present
25   in this object are described in the next section.
26  </para>
27
28 <sect1 id="backup-manifest-toplevel">
29  <title>Backup Manifest Top-level Object</title>
30
31  <para>
32   The backup manifest JSON document contains the following keys.
33  </para>
34
35  <variablelist>
36   <varlistentry>
37    <term><literal>PostgreSQL-Backup-Manifest-Version</literal></term>
38    <listitem>
39     <para>
40      The associated value is always the integer 1.
41     </para>
42    </listitem>
43   </varlistentry>
44
45   <varlistentry>
46    <term><literal>Files</literal></term>
47    <listitem>
48     <para>
49      The associated value is always a list of objects, each describing one
50      file that is present in the backup. No entries are present in this
51      list for the WAL files that are needed in order to use the backup,
52      or for the backup manifest itself.  The structure of each object in the
53      list is described in <xref linkend="backup-manifest-files" />.
54     </para>
55    </listitem>
56   </varlistentry>
57
58   <varlistentry>
59    <term><literal>WAL-Ranges</literal></term>
60    <listitem>
61     <para>
62      The associated value is always a list of objects, each describing a
63      range of WAL records that must be readable from a particular timeline
64      in order to make use of the backup.  The structure of these objects is
65      further described in <xref linkend="backup-manifest-wal-ranges" />.
66     </para>
67    </listitem>
68   </varlistentry>
69
70   <varlistentry>
71    <term><literal>Manifest-Checksum</literal></term>
72    <listitem>
73     <para>
74      This key is always present on the last line of the backup manifest file.
75      The associated value is a SHA256 checksum of all the preceding lines.
76      We use a fixed checksum method here to make it possible for clients
77      to do incremental parsing of the manifest. While a SHA256 checksum
78      is significantly more expensive than a CRC32C checksum, the manifest
79      should normally be small enough that the extra computation won't matter
80      very much.
81     </para>
82    </listitem>
83   </varlistentry>
84  </variablelist>
85 </sect1>
86
87 <sect1 id="backup-manifest-files">
88  <title>Backup Manifest File Object</title>
89
90  <para>
91   The object which describes a single file contains either a
92   <literal>Path</literal> key or an <literal>Encoded-Path</literal> key.
93   Normally, the <literal>Path</literal> key will be present. The
94   associated string value is the path of the file relative to the root
95   of the backup directory. Files located in a user-defined tablespace
96   will have paths whose first two components are <filename>pg_tblspc</filename> and the OID
97   of the tablespace. If the path is not a string that is legal in UTF-8,
98   or if the user requests that encoded paths be used for all files, then
99   the <literal>Encoded-Path</literal> key will be present instead.  This
100   stores the same data, but it is encoded as a string of hexadecimal
101   digits. Each pair of hexadecimal digits in the string represents a
102   single octet.
103  </para>
104
105  <para>
106   The following two keys are always present:
107  </para>
108
109  <variablelist>
110   <varlistentry>
111    <term><literal>Size</literal></term>
112    <listitem>
113     <para>
114      The expected size of this file, as an integer.
115     </para>
116    </listitem>
117   </varlistentry>
118
119   <varlistentry>
120    <term><literal>Last-Modified</literal></term>
121    <listitem>
122     <para>
123      The last modification time of the file as reported by the server at
124      the time of the backup. Unlike the other fields stored in the backup,
125      this field is not used by <xref linkend="app-pgverifybackup" />.
126      It is included only for informational purposes.
127     </para>
128    </listitem>
129   </varlistentry>
130  </variablelist>
131
132  <para>
133   If the backup was taken with file checksums enabled, the following
134   keys will be present:
135  </para>
136
137  <variablelist>
138   <varlistentry>
139    <term><literal>Checksum-Algorithm</literal></term>
140    <listitem>
141     <para>
142      The checksum algorithm used to compute a checksum for this file.
143      Currently, this will be the same for every file in the backup
144      manifest, but this may change in future releases. At present, the
145      supported checksum algorithms are <literal>CRC32C</literal>,
146      <literal>SHA224</literal>,
147      <literal>SHA256</literal>,
148      <literal>SHA384</literal>, and
149      <literal>SHA512</literal>.
150     </para>
151    </listitem>
152   </varlistentry>
153
154   <varlistentry>
155    <term><literal>Checksum</literal></term>
156    <listitem>
157     <para>
158      The checksum computed for this file, stored as a series of
159      hexadecimal characters, two for each byte of the checksum.
160     </para>
161    </listitem>
162   </varlistentry>
163  </variablelist>
164 </sect1>
165
166 <sect1 id="backup-manifest-wal-ranges">
167  <title>Backup Manifest WAL Range Object</title>
168
169  <para>
170   The object which describes a WAL range always has three keys:
171  </para>
172
173  <variablelist>
174   <varlistentry>
175    <term><literal>Timeline</literal></term>
176    <listitem>
177     <para>
178      The timeline for this range of WAL records, as an integer.
179     </para>
180    </listitem>
181   </varlistentry>
182
183   <varlistentry>
184    <term><literal>Start-LSN</literal></term>
185    <listitem>
186     <para>
187      The LSN at which replay must begin on the indicated timeline in order to
188      make use of this backup.  The LSN is stored in the format normally used
189      by <productname>PostgreSQL</productname>; that is, it is a string
190      consisting of two strings of hexadecimal characters, each with a length
191      of between 1 and 8, separated by a slash.
192     </para>
193    </listitem>
194   </varlistentry>
195
196   <varlistentry>
197    <term><literal>End-LSN</literal></term>
198    <listitem>
199     <para>
200      The earliest LSN at which replay on the indicated timeline may end when
201      making use of this backup. This is stored in the same format as
202      <literal>Start-LSN</literal>.
203     </para>
204    </listitem>
205   </varlistentry>
206  </variablelist>
207
208  <para>
209   Ordinarily, there will be only a single WAL range. However, if a backup is
210   taken from a standby which switches timelines during the backup due to an
211   upstream promotion, it is possible for multiple ranges to be present, each
212   with a different timeline. There will never be multiple WAL ranges present
213   for the same timeline.
214  </para>
215 </sect1>
216</chapter>
217