| 1 |
<!-- doc/src/sgml/backup-manifest.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 an integer. Beginning in |
| 41 |
<productname>PostgreSQL</productname> <literal>17</literal>, |
| 42 |
it is <literal>2</literal>; in older versions, it is <literal>1</literal>. |
| 43 |
</para> |
| 44 |
</listitem> |
| 45 |
</varlistentry> |
| 46 |
|
| 47 |
<varlistentry> |
| 48 |
<term><literal>System-Identifier</literal></term> |
| 49 |
<listitem> |
| 50 |
<para> |
| 51 |
The database system identifier of the |
| 52 |
<productname>PostgreSQL</productname> instance where the backup was |
| 53 |
taken. This field is present only when |
| 54 |
<literal>PostgreSQL-Backup-Manifest-Version</literal> is |
| 55 |
<literal>2</literal>. |
| 56 |
</para> |
| 57 |
</listitem> |
| 58 |
</varlistentry> |
| 59 |
|
| 60 |
<varlistentry> |
| 61 |
<term><literal>Files</literal></term> |
| 62 |
<listitem> |
| 63 |
<para> |
| 64 |
The associated value is always a list of objects, each describing one |
| 65 |
file that is present in the backup. No entries are present in this |
| 66 |
list for the WAL files that are needed in order to use the backup, |
| 67 |
or for the backup manifest itself. The structure of each object in the |
| 68 |
list is described in <xref linkend="backup-manifest-files" />. |
| 69 |
</para> |
| 70 |
</listitem> |
| 71 |
</varlistentry> |
| 72 |
|
| 73 |
<varlistentry> |
| 74 |
<term><literal>WAL-Ranges</literal></term> |
| 75 |
<listitem> |
| 76 |
<para> |
| 77 |
The associated value is always a list of objects, each describing a |
| 78 |
range of WAL records that must be readable from a particular timeline |
| 79 |
in order to make use of the backup. The structure of these objects is |
| 80 |
further described in <xref linkend="backup-manifest-wal-ranges" />. |
| 81 |
</para> |
| 82 |
</listitem> |
| 83 |
</varlistentry> |
| 84 |
|
| 85 |
<varlistentry> |
| 86 |
<term><literal>Manifest-Checksum</literal></term> |
| 87 |
<listitem> |
| 88 |
<para> |
| 89 |
This key is always present on the last line of the backup manifest file. |
| 90 |
The associated value is a SHA-256 checksum of all the preceding lines. |
| 91 |
We use a fixed checksum method here to make it possible for clients |
| 92 |
to do incremental parsing of the manifest. While a SHA-256 checksum |
| 93 |
is significantly more expensive than a CRC-32C checksum, the manifest |
| 94 |
should normally be small enough that the extra computation won't matter |
| 95 |
very much. |
| 96 |
</para> |
| 97 |
</listitem> |
| 98 |
</varlistentry> |
| 99 |
</variablelist> |
| 100 |
</sect1> |
| 101 |
|
| 102 |
<sect1 id="backup-manifest-files"> |
| 103 |
<title>Backup Manifest File Object</title> |
| 104 |
|
| 105 |
<para> |
| 106 |
The object which describes a single file contains either a |
| 107 |
<literal>Path</literal> key or an <literal>Encoded-Path</literal> key. |
| 108 |
Normally, the <literal>Path</literal> key will be present. The |
| 109 |
associated string value is the path of the file relative to the root |
| 110 |
of the backup directory. Files located in a user-defined tablespace |
| 111 |
will have paths whose first two components are <filename>pg_tblspc</filename> and the OID |
| 112 |
of the tablespace. If the path is not a string that is legal in UTF-8, |
| 113 |
or if the user requests that encoded paths be used for all files, then |
| 114 |
the <literal>Encoded-Path</literal> key will be present instead. This |
| 115 |
stores the same data, but it is encoded as a string of hexadecimal |
| 116 |
digits. Each pair of hexadecimal digits in the string represents a |
| 117 |
single octet. |
| 118 |
</para> |
| 119 |
|
| 120 |
<para> |
| 121 |
The following two keys are always present: |
| 122 |
</para> |
| 123 |
|
| 124 |
<variablelist> |
| 125 |
<varlistentry> |
| 126 |
<term><literal>Size</literal></term> |
| 127 |
<listitem> |
| 128 |
<para> |
| 129 |
The expected size of this file, as an integer. |
| 130 |
</para> |
| 131 |
</listitem> |
| 132 |
</varlistentry> |
| 133 |
|
| 134 |
<varlistentry> |
| 135 |
<term><literal>Last-Modified</literal></term> |
| 136 |
<listitem> |
| 137 |
<para> |
| 138 |
The last modification time of the file as reported by the server at |
| 139 |
the time of the backup. Unlike the other fields stored in the backup, |
| 140 |
this field is not used by <xref linkend="app-pgverifybackup" />. |
| 141 |
It is included only for informational purposes. |
| 142 |
</para> |
| 143 |
</listitem> |
| 144 |
</varlistentry> |
| 145 |
</variablelist> |
| 146 |
|
| 147 |
<para> |
| 148 |
If the backup was taken with file checksums enabled, the following |
| 149 |
keys will be present: |
| 150 |
</para> |
| 151 |
|
| 152 |
<variablelist> |
| 153 |
<varlistentry> |
| 154 |
<term><literal>Checksum-Algorithm</literal></term> |
| 155 |
<listitem> |
| 156 |
<para> |
| 157 |
The checksum algorithm used to compute a checksum for this file. |
| 158 |
Currently, this will be the same for every file in the backup |
| 159 |
manifest, but this may change in future releases. At present, the |
| 160 |
supported checksum algorithms are <literal>CRC32C</literal>, |
| 161 |
<literal>SHA224</literal>, |
| 162 |
<literal>SHA256</literal>, |
| 163 |
<literal>SHA384</literal>, and |
| 164 |
<literal>SHA512</literal>. |
| 165 |
</para> |
| 166 |
</listitem> |
| 167 |
</varlistentry> |
| 168 |
|
| 169 |
<varlistentry> |
| 170 |
<term><literal>Checksum</literal></term> |
| 171 |
<listitem> |
| 172 |
<para> |
| 173 |
The checksum computed for this file, stored as a series of |
| 174 |
hexadecimal characters, two for each byte of the checksum. |
| 175 |
</para> |
| 176 |
</listitem> |
| 177 |
</varlistentry> |
| 178 |
</variablelist> |
| 179 |
</sect1> |
| 180 |
|
| 181 |
<sect1 id="backup-manifest-wal-ranges"> |
| 182 |
<title>Backup Manifest WAL Range Object</title> |
| 183 |
|
| 184 |
<para> |
| 185 |
The object which describes a WAL range always has three keys: |
| 186 |
</para> |
| 187 |
|
| 188 |
<variablelist> |
| 189 |
<varlistentry> |
| 190 |
<term><literal>Timeline</literal></term> |
| 191 |
<listitem> |
| 192 |
<para> |
| 193 |
The timeline for this range of WAL records, as an integer. |
| 194 |
</para> |
| 195 |
</listitem> |
| 196 |
</varlistentry> |
| 197 |
|
| 198 |
<varlistentry> |
| 199 |
<term><literal>Start-LSN</literal></term> |
| 200 |
<listitem> |
| 201 |
<para> |
| 202 |
The LSN at which replay must begin on the indicated timeline in order to |
| 203 |
make use of this backup. The LSN is stored in the format normally used |
| 204 |
by <productname>PostgreSQL</productname>; that is, it is a string |
| 205 |
consisting of two strings of hexadecimal characters, each with a length |
| 206 |
of between 1 and 8, separated by a slash. |
| 207 |
</para> |
| 208 |
</listitem> |
| 209 |
</varlistentry> |
| 210 |
|
| 211 |
<varlistentry> |
| 212 |
<term><literal>End-LSN</literal></term> |
| 213 |
<listitem> |
| 214 |
<para> |
| 215 |
The earliest LSN at which replay on the indicated timeline may end when |
| 216 |
making use of this backup. This is stored in the same format as |
| 217 |
<literal>Start-LSN</literal>. |
| 218 |
</para> |
| 219 |
</listitem> |
| 220 |
</varlistentry> |
| 221 |
</variablelist> |
| 222 |
|
| 223 |
<para> |
| 224 |
Ordinarily, there will be only a single WAL range. However, if a backup is |
| 225 |
taken from a standby which switches timelines during the backup due to an |
| 226 |
upstream promotion, it is possible for multiple ranges to be present, each |
| 227 |
with a different timeline. There will never be multiple WAL ranges present |
| 228 |
for the same timeline. |
| 229 |
</para> |
| 230 |
</sect1> |
| 231 |
</chapter> |