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