1 /* 2 * xlogrecord.h 3 * 4 * Definitions for the WAL record format. 5 * 6 * Portions Copyright (c) 1996-2018, PostgreSQL Global Development Group 7 * Portions Copyright (c) 1994, Regents of the University of California 8 * 9 * src/include/access/xlogrecord.h 10 */ 11 #ifndef XLOGRECORD_H 12 #define XLOGRECORD_H 13 14 #include "access/rmgr.h" 15 #include "access/xlogdefs.h" 16 #include "port/pg_crc32c.h" 17 #include "storage/block.h" 18 #include "storage/relfilenode.h" 19 20 /* 21 * The overall layout of an XLOG record is: 22 * Fixed-size header (XLogRecord struct) 23 * XLogRecordBlockHeader struct 24 * XLogRecordBlockHeader struct 25 * ... 26 * XLogRecordDataHeader[Short|Long] struct 27 * block data 28 * block data 29 * ... 30 * main data 31 * 32 * There can be zero or more XLogRecordBlockHeaders, and 0 or more bytes of 33 * rmgr-specific data not associated with a block. XLogRecord structs 34 * always start on MAXALIGN boundaries in the WAL files, but the rest of 35 * the fields are not aligned. 36 * 37 * The XLogRecordBlockHeader, XLogRecordDataHeaderShort and 38 * XLogRecordDataHeaderLong structs all begin with a single 'id' byte. It's 39 * used to distinguish between block references, and the main data structs. 40 */ 41 typedef struct XLogRecord 42 { 43 uint32 xl_tot_len; /* total len of entire record */ 44 TransactionId xl_xid; /* xact id */ 45 XLogRecPtr xl_prev; /* ptr to previous record in log */ 46 uint8 xl_info; /* flag bits, see below */ 47 RmgrId xl_rmid; /* resource manager for this record */ 48 /* 2 bytes of padding here, initialize to zero */ 49 pg_crc32c xl_crc; /* CRC for this record */ 50 51 /* XLogRecordBlockHeaders and XLogRecordDataHeader follow, no padding */ 52 53 } XLogRecord; 54 55 #define SizeOfXLogRecord (offsetof(XLogRecord, xl_crc) + sizeof(pg_crc32c)) 56 57 /* 58 * The high 4 bits in xl_info may be used freely by rmgr. The 59 * XLR_SPECIAL_REL_UPDATE and XLR_CHECK_CONSISTENCY bits can be passed by 60 * XLogInsert caller. The rest are set internally by XLogInsert. 61 */ 62 #define XLR_INFO_MASK 0x0F 63 #define XLR_RMGR_INFO_MASK 0xF0 64 65 /* 66 * If a WAL record modifies any relation files, in ways not covered by the 67 * usual block references, this flag is set. This is not used for anything 68 * by PostgreSQL itself, but it allows external tools that read WAL and keep 69 * track of modified blocks to recognize such special record types. 70 */ 71 #define XLR_SPECIAL_REL_UPDATE 0x01 72 73 /* 74 * Enforces consistency checks of replayed WAL at recovery. If enabled, 75 * each record will log a full-page write for each block modified by the 76 * record and will reuse it afterwards for consistency checks. The caller 77 * of XLogInsert can use this value if necessary, but if 78 * wal_consistency_checking is enabled for a rmgr this is set unconditionally. 79 */ 80 #define XLR_CHECK_CONSISTENCY 0x02 81 82 /* 83 * Header info for block data appended to an XLOG record. 84 * 85 * 'data_length' is the length of the rmgr-specific payload data associated 86 * with this block. It does not include the possible full page image, nor 87 * XLogRecordBlockHeader struct itself. 88 * 89 * Note that we don't attempt to align the XLogRecordBlockHeader struct! 90 * So, the struct must be copied to aligned local storage before use. 91 */ 92 typedef struct XLogRecordBlockHeader 93 { 94 uint8 id; /* block reference ID */ 95 uint8 fork_flags; /* fork within the relation, and flags */ 96 uint16 data_length; /* number of payload bytes (not including page 97 * image) */ 98 99 /* If BKPBLOCK_HAS_IMAGE, an XLogRecordBlockImageHeader struct follows */ 100 /* If BKPBLOCK_SAME_REL is not set, a RelFileNode follows */ 101 /* BlockNumber follows */ 102 } XLogRecordBlockHeader; 103 104 #define SizeOfXLogRecordBlockHeader (offsetof(XLogRecordBlockHeader, data_length) + sizeof(uint16)) 105 106 /* 107 * Additional header information when a full-page image is included 108 * (i.e. when BKPBLOCK_HAS_IMAGE is set). 109 * 110 * As a trivial form of data compression, the XLOG code is aware that 111 * PG data pages usually contain an unused "hole" in the middle, which 112 * contains only zero bytes. If the length of "hole" > 0 then we have removed 113 * such a "hole" from the stored data (and it's not counted in the 114 * XLOG record's CRC, either). Hence, the amount of block data actually 115 * present is BLCKSZ - the length of "hole" bytes. 116 * 117 * When wal_compression is enabled, a full page image which "hole" was 118 * removed is additionally compressed using PGLZ compression algorithm. 119 * This can reduce the WAL volume, but at some extra cost of CPU spent 120 * on the compression during WAL logging. In this case, since the "hole" 121 * length cannot be calculated by subtracting the number of page image bytes 122 * from BLCKSZ, basically it needs to be stored as an extra information. 123 * But when no "hole" exists, we can assume that the "hole" length is zero 124 * and no such an extra information needs to be stored. Note that 125 * the original version of page image is stored in WAL instead of the 126 * compressed one if the number of bytes saved by compression is less than 127 * the length of extra information. Hence, when a page image is successfully 128 * compressed, the amount of block data actually present is less than 129 * BLCKSZ - the length of "hole" bytes - the length of extra information. 130 */ 131 typedef struct XLogRecordBlockImageHeader 132 { 133 uint16 length; /* number of page image bytes */ 134 uint16 hole_offset; /* number of bytes before "hole" */ 135 uint8 bimg_info; /* flag bits, see below */ 136 137 /* 138 * If BKPIMAGE_HAS_HOLE and BKPIMAGE_IS_COMPRESSED, an 139 * XLogRecordBlockCompressHeader struct follows. 140 */ 141 } XLogRecordBlockImageHeader; 142 143 #define SizeOfXLogRecordBlockImageHeader \ 144 (offsetof(XLogRecordBlockImageHeader, bimg_info) + sizeof(uint8)) 145 146 /* Information stored in bimg_info */ 147 #define BKPIMAGE_HAS_HOLE 0x01 /* page image has "hole" */ 148 #define BKPIMAGE_IS_COMPRESSED 0x02 /* page image is compressed */ 149 #define BKPIMAGE_APPLY 0x04 /* page image should be restored during 150 * replay */ 151 152 /* 153 * Extra header information used when page image has "hole" and 154 * is compressed. 155 */ 156 typedef struct XLogRecordBlockCompressHeader 157 { 158 uint16 hole_length; /* number of bytes in "hole" */ 159 } XLogRecordBlockCompressHeader; 160 161 #define SizeOfXLogRecordBlockCompressHeader \ 162 sizeof(XLogRecordBlockCompressHeader) 163 164 /* 165 * Maximum size of the header for a block reference. This is used to size a 166 * temporary buffer for constructing the header. 167 */ 168 #define MaxSizeOfXLogRecordBlockHeader \ 169 (SizeOfXLogRecordBlockHeader + \ 170 SizeOfXLogRecordBlockImageHeader + \ 171 SizeOfXLogRecordBlockCompressHeader + \ 172 sizeof(RelFileNode) + \ 173 sizeof(BlockNumber)) 174 175 /* 176 * The fork number fits in the lower 4 bits in the fork_flags field. The upper 177 * bits are used for flags. 178 */ 179 #define BKPBLOCK_FORK_MASK 0x0F 180 #define BKPBLOCK_FLAG_MASK 0xF0 181 #define BKPBLOCK_HAS_IMAGE 0x10 /* block data is an XLogRecordBlockImage */ 182 #define BKPBLOCK_HAS_DATA 0x20 183 #define BKPBLOCK_WILL_INIT 0x40 /* redo will re-init the page */ 184 #define BKPBLOCK_SAME_REL 0x80 /* RelFileNode omitted, same as previous */ 185 186 /* 187 * XLogRecordDataHeaderShort/Long are used for the "main data" portion of 188 * the record. If the length of the data is less than 256 bytes, the short 189 * form is used, with a single byte to hold the length. Otherwise the long 190 * form is used. 191 * 192 * (These structs are currently not used in the code, they are here just for 193 * documentation purposes). 194 */ 195 typedef struct XLogRecordDataHeaderShort 196 { 197 uint8 id; /* XLR_BLOCK_ID_DATA_SHORT */ 198 uint8 data_length; /* number of payload bytes */ 199 } XLogRecordDataHeaderShort; 200 201 #define SizeOfXLogRecordDataHeaderShort (sizeof(uint8) * 2) 202 203 typedef struct XLogRecordDataHeaderLong 204 { 205 uint8 id; /* XLR_BLOCK_ID_DATA_LONG */ 206 /* followed by uint32 data_length, unaligned */ 207 } XLogRecordDataHeaderLong; 208 209 #define SizeOfXLogRecordDataHeaderLong (sizeof(uint8) + sizeof(uint32)) 210 211 /* 212 * Block IDs used to distinguish different kinds of record fragments. Block 213 * references are numbered from 0 to XLR_MAX_BLOCK_ID. A rmgr is free to use 214 * any ID number in that range (although you should stick to small numbers, 215 * because the WAL machinery is optimized for that case). A couple of ID 216 * numbers are reserved to denote the "main" data portion of the record. 217 * 218 * The maximum is currently set at 32, quite arbitrarily. Most records only 219 * need a handful of block references, but there are a few exceptions that 220 * need more. 221 */ 222 #define XLR_MAX_BLOCK_ID 32 223 224 #define XLR_BLOCK_ID_DATA_SHORT 255 225 #define XLR_BLOCK_ID_DATA_LONG 254 226 #define XLR_BLOCK_ID_ORIGIN 253 227 228 #endif /* XLOGRECORD_H */ 229