PostgreSQL Source Code  git master
heapam_xlog.h
Go to the documentation of this file.
1 /*-------------------------------------------------------------------------
2  *
3  * heapam_xlog.h
4  * POSTGRES heap access XLOG definitions.
5  *
6  *
7  * Portions Copyright (c) 1996-2023, PostgreSQL Global Development Group
8  * Portions Copyright (c) 1994, Regents of the University of California
9  *
10  * src/include/access/heapam_xlog.h
11  *
12  *-------------------------------------------------------------------------
13  */
14 #ifndef HEAPAM_XLOG_H
15 #define HEAPAM_XLOG_H
16 
17 #include "access/htup.h"
18 #include "access/xlogreader.h"
19 #include "lib/stringinfo.h"
20 #include "storage/buf.h"
21 #include "storage/bufpage.h"
22 #include "storage/relfilelocator.h"
23 #include "utils/relcache.h"
24 
25 
26 /*
27  * WAL record definitions for heapam.c's WAL operations
28  *
29  * XLOG allows to store some information in high 4 bits of log
30  * record xl_info field. We use 3 for opcode and one for init bit.
31  */
32 #define XLOG_HEAP_INSERT 0x00
33 #define XLOG_HEAP_DELETE 0x10
34 #define XLOG_HEAP_UPDATE 0x20
35 #define XLOG_HEAP_TRUNCATE 0x30
36 #define XLOG_HEAP_HOT_UPDATE 0x40
37 #define XLOG_HEAP_CONFIRM 0x50
38 #define XLOG_HEAP_LOCK 0x60
39 #define XLOG_HEAP_INPLACE 0x70
40 
41 #define XLOG_HEAP_OPMASK 0x70
42 /*
43  * When we insert 1st item on new page in INSERT, UPDATE, HOT_UPDATE,
44  * or MULTI_INSERT, we can (and we do) restore entire page in redo
45  */
46 #define XLOG_HEAP_INIT_PAGE 0x80
47 /*
48  * We ran out of opcodes, so heapam.c now has a second RmgrId. These opcodes
49  * are associated with RM_HEAP2_ID, but are not logically different from
50  * the ones above associated with RM_HEAP_ID. XLOG_HEAP_OPMASK applies to
51  * these, too.
52  */
53 #define XLOG_HEAP2_REWRITE 0x00
54 #define XLOG_HEAP2_PRUNE 0x10
55 #define XLOG_HEAP2_VACUUM 0x20
56 #define XLOG_HEAP2_FREEZE_PAGE 0x30
57 #define XLOG_HEAP2_VISIBLE 0x40
58 #define XLOG_HEAP2_MULTI_INSERT 0x50
59 #define XLOG_HEAP2_LOCK_UPDATED 0x60
60 #define XLOG_HEAP2_NEW_CID 0x70
61 
62 /*
63  * xl_heap_insert/xl_heap_multi_insert flag values, 8 bits are available.
64  */
65 /* PD_ALL_VISIBLE was cleared */
66 #define XLH_INSERT_ALL_VISIBLE_CLEARED (1<<0)
67 #define XLH_INSERT_LAST_IN_MULTI (1<<1)
68 #define XLH_INSERT_IS_SPECULATIVE (1<<2)
69 #define XLH_INSERT_CONTAINS_NEW_TUPLE (1<<3)
70 #define XLH_INSERT_ON_TOAST_RELATION (1<<4)
71 
72 /* all_frozen_set always implies all_visible_set */
73 #define XLH_INSERT_ALL_FROZEN_SET (1<<5)
74 
75 /*
76  * xl_heap_update flag values, 8 bits are available.
77  */
78 /* PD_ALL_VISIBLE was cleared */
79 #define XLH_UPDATE_OLD_ALL_VISIBLE_CLEARED (1<<0)
80 /* PD_ALL_VISIBLE was cleared in the 2nd page */
81 #define XLH_UPDATE_NEW_ALL_VISIBLE_CLEARED (1<<1)
82 #define XLH_UPDATE_CONTAINS_OLD_TUPLE (1<<2)
83 #define XLH_UPDATE_CONTAINS_OLD_KEY (1<<3)
84 #define XLH_UPDATE_CONTAINS_NEW_TUPLE (1<<4)
85 #define XLH_UPDATE_PREFIX_FROM_OLD (1<<5)
86 #define XLH_UPDATE_SUFFIX_FROM_OLD (1<<6)
87 
88 /* convenience macro for checking whether any form of old tuple was logged */
89 #define XLH_UPDATE_CONTAINS_OLD \
90  (XLH_UPDATE_CONTAINS_OLD_TUPLE | XLH_UPDATE_CONTAINS_OLD_KEY)
91 
92 /*
93  * xl_heap_delete flag values, 8 bits are available.
94  */
95 /* PD_ALL_VISIBLE was cleared */
96 #define XLH_DELETE_ALL_VISIBLE_CLEARED (1<<0)
97 #define XLH_DELETE_CONTAINS_OLD_TUPLE (1<<1)
98 #define XLH_DELETE_CONTAINS_OLD_KEY (1<<2)
99 #define XLH_DELETE_IS_SUPER (1<<3)
100 #define XLH_DELETE_IS_PARTITION_MOVE (1<<4)
101 
102 /* convenience macro for checking whether any form of old tuple was logged */
103 #define XLH_DELETE_CONTAINS_OLD \
104  (XLH_DELETE_CONTAINS_OLD_TUPLE | XLH_DELETE_CONTAINS_OLD_KEY)
105 
106 /* This is what we need to know about delete */
107 typedef struct xl_heap_delete
108 {
109  TransactionId xmax; /* xmax of the deleted tuple */
110  OffsetNumber offnum; /* deleted tuple's offset */
111  uint8 infobits_set; /* infomask bits */
114 
115 #define SizeOfHeapDelete (offsetof(xl_heap_delete, flags) + sizeof(uint8))
116 
117 /*
118  * xl_heap_truncate flag values, 8 bits are available.
119  */
120 #define XLH_TRUNCATE_CASCADE (1<<0)
121 #define XLH_TRUNCATE_RESTART_SEQS (1<<1)
122 
123 /*
124  * For truncate we list all truncated relids in an array, followed by all
125  * sequence relids that need to be restarted, if any.
126  * All rels are always within the same database, so we just list dbid once.
127  */
128 typedef struct xl_heap_truncate
129 {
135 
136 #define SizeOfHeapTruncate (offsetof(xl_heap_truncate, relids))
137 
138 /*
139  * We don't store the whole fixed part (HeapTupleHeaderData) of an inserted
140  * or updated tuple in WAL; we can save a few bytes by reconstructing the
141  * fields that are available elsewhere in the WAL record, or perhaps just
142  * plain needn't be reconstructed. These are the fields we must store.
143  */
144 typedef struct xl_heap_header
145 {
150 
151 #define SizeOfHeapHeader (offsetof(xl_heap_header, t_hoff) + sizeof(uint8))
152 
153 /* This is what we need to know about insert */
154 typedef struct xl_heap_insert
155 {
156  OffsetNumber offnum; /* inserted tuple's offset */
158 
159  /* xl_heap_header & TUPLE DATA in backup block 0 */
161 
162 #define SizeOfHeapInsert (offsetof(xl_heap_insert, flags) + sizeof(uint8))
163 
164 /*
165  * This is what we need to know about a multi-insert.
166  *
167  * The main data of the record consists of this xl_heap_multi_insert header.
168  * 'offsets' array is omitted if the whole page is reinitialized
169  * (XLOG_HEAP_INIT_PAGE).
170  *
171  * In block 0's data portion, there is an xl_multi_insert_tuple struct,
172  * followed by the tuple data for each tuple. There is padding to align
173  * each xl_multi_insert_tuple struct.
174  */
175 typedef struct xl_heap_multi_insert
176 {
181 
182 #define SizeOfHeapMultiInsert offsetof(xl_heap_multi_insert, offsets)
183 
184 typedef struct xl_multi_insert_tuple
185 {
186  uint16 datalen; /* size of tuple data that follows */
190  /* TUPLE DATA FOLLOWS AT END OF STRUCT */
192 
193 #define SizeOfMultiInsertTuple (offsetof(xl_multi_insert_tuple, t_hoff) + sizeof(uint8))
194 
195 /*
196  * This is what we need to know about update|hot_update
197  *
198  * Backup blk 0: new page
199  *
200  * If XLH_UPDATE_PREFIX_FROM_OLD or XLH_UPDATE_SUFFIX_FROM_OLD flags are set,
201  * the prefix and/or suffix come first, as one or two uint16s.
202  *
203  * After that, xl_heap_header and new tuple data follow. The new tuple
204  * data doesn't include the prefix and suffix, which are copied from the
205  * old tuple on replay.
206  *
207  * If XLH_UPDATE_CONTAINS_NEW_TUPLE flag is given, the tuple data is
208  * included even if a full-page image was taken.
209  *
210  * Backup blk 1: old page, if different. (no data, just a reference to the blk)
211  */
212 typedef struct xl_heap_update
213 {
214  TransactionId old_xmax; /* xmax of the old tuple */
215  OffsetNumber old_offnum; /* old tuple's offset */
216  uint8 old_infobits_set; /* infomask bits to set on old tuple */
218  TransactionId new_xmax; /* xmax of the new tuple */
219  OffsetNumber new_offnum; /* new tuple's offset */
220 
221  /*
222  * If XLH_UPDATE_CONTAINS_OLD_TUPLE or XLH_UPDATE_CONTAINS_OLD_KEY flags
223  * are set, xl_heap_header and tuple data for the old tuple follow.
224  */
226 
227 #define SizeOfHeapUpdate (offsetof(xl_heap_update, new_offnum) + sizeof(OffsetNumber))
228 
229 /*
230  * This is what we need to know about page pruning (both during VACUUM and
231  * during opportunistic pruning)
232  *
233  * The array of OffsetNumbers following the fixed part of the record contains:
234  * * for each redirected item: the item offset, then the offset redirected to
235  * * for each now-dead item: the item offset
236  * * for each now-unused item: the item offset
237  * The total number of OffsetNumbers is therefore 2*nredirected+ndead+nunused.
238  * Note that nunused is not explicitly stored, but may be found by reference
239  * to the total record length.
240  *
241  * Acquires a full cleanup lock.
242  */
243 typedef struct xl_heap_prune
244 {
248  bool isCatalogRel; /* to handle recovery conflict during logical
249  * decoding on standby */
250  /* OFFSET NUMBERS are in the block reference 0 */
252 
253 #define SizeOfHeapPrune (offsetof(xl_heap_prune, isCatalogRel) + sizeof(bool))
254 
255 /*
256  * The vacuum page record is similar to the prune record, but can only mark
257  * already LP_DEAD items LP_UNUSED (during VACUUM's second heap pass)
258  *
259  * Acquires an ordinary exclusive lock only.
260  */
261 typedef struct xl_heap_vacuum
262 {
264  /* OFFSET NUMBERS are in the block reference 0 */
266 
267 #define SizeOfHeapVacuum (offsetof(xl_heap_vacuum, nunused) + sizeof(uint16))
268 
269 /* flags for infobits_set */
270 #define XLHL_XMAX_IS_MULTI 0x01
271 #define XLHL_XMAX_LOCK_ONLY 0x02
272 #define XLHL_XMAX_EXCL_LOCK 0x04
273 #define XLHL_XMAX_KEYSHR_LOCK 0x08
274 #define XLHL_KEYS_UPDATED 0x10
275 
276 /* flag bits for xl_heap_lock / xl_heap_lock_updated's flag field */
277 #define XLH_LOCK_ALL_FROZEN_CLEARED 0x01
278 
279 /* This is what we need to know about lock */
280 typedef struct xl_heap_lock
281 {
282  TransactionId xmax; /* might be a MultiXactId */
283  OffsetNumber offnum; /* locked tuple's offset on page */
284  uint8 infobits_set; /* infomask and infomask2 bits to set */
285  uint8 flags; /* XLH_LOCK_* flag bits */
287 
288 #define SizeOfHeapLock (offsetof(xl_heap_lock, flags) + sizeof(uint8))
289 
290 /* This is what we need to know about locking an updated version of a row */
291 typedef struct xl_heap_lock_updated
292 {
298 
299 #define SizeOfHeapLockUpdated (offsetof(xl_heap_lock_updated, flags) + sizeof(uint8))
300 
301 /* This is what we need to know about confirmation of speculative insertion */
302 typedef struct xl_heap_confirm
303 {
304  OffsetNumber offnum; /* confirmed tuple's offset on page */
306 
307 #define SizeOfHeapConfirm (offsetof(xl_heap_confirm, offnum) + sizeof(OffsetNumber))
308 
309 /* This is what we need to know about in-place update */
310 typedef struct xl_heap_inplace
311 {
312  OffsetNumber offnum; /* updated tuple's offset on page */
313  /* TUPLE DATA FOLLOWS AT END OF STRUCT */
315 
316 #define SizeOfHeapInplace (offsetof(xl_heap_inplace, offnum) + sizeof(OffsetNumber))
317 
318 /*
319  * This struct represents a 'freeze plan', which describes how to freeze a
320  * group of one or more heap tuples (appears in xl_heap_freeze_page record)
321  */
322 /* 0x01 was XLH_FREEZE_XMIN */
323 #define XLH_FREEZE_XVAC 0x02
324 #define XLH_INVALID_XVAC 0x04
325 
326 typedef struct xl_heap_freeze_plan
327 {
332 
333  /* Length of individual page offset numbers array for this plan */
336 
337 /*
338  * This is what we need to know about a block being frozen during vacuum
339  *
340  * Backup block 0's data contains an array of xl_heap_freeze_plan structs
341  * (with nplans elements), followed by one or more page offset number arrays.
342  * Each such page offset number array corresponds to a single freeze plan
343  * (REDO routine freezes corresponding heap tuples using freeze plan).
344  */
345 typedef struct xl_heap_freeze_page
346 {
349  bool isCatalogRel; /* to handle recovery conflict during logical
350  * decoding on standby */
351 
352  /*
353  * In payload of blk 0 : FREEZE PLANS and OFFSET NUMBER ARRAY
354  */
356 
357 #define SizeOfHeapFreezePage (offsetof(xl_heap_freeze_page, isCatalogRel) + sizeof(bool))
358 
359 /*
360  * This is what we need to know about setting a visibility map bit
361  *
362  * Backup blk 0: visibility map buffer
363  * Backup blk 1: heap buffer
364  */
365 typedef struct xl_heap_visible
366 {
370 
371 #define SizeOfHeapVisible (offsetof(xl_heap_visible, flags) + sizeof(uint8))
372 
373 typedef struct xl_heap_new_cid
374 {
375  /*
376  * store toplevel xid so we don't have to merge cids from different
377  * transactions
378  */
382  CommandId combocid; /* just for debugging */
383 
384  /*
385  * Store the relfilelocator/ctid pair to facilitate lookups.
386  */
390 
391 #define SizeOfHeapNewCid (offsetof(xl_heap_new_cid, target_tid) + sizeof(ItemPointerData))
392 
393 /* logical rewrite xlog record header */
395 {
396  TransactionId mapped_xid; /* xid that might need to see the row */
397  Oid mapped_db; /* DbOid or InvalidOid for shared rels */
398  Oid mapped_rel; /* Oid of the mapped relation */
399  off_t offset; /* How far have we written so far */
400  uint32 num_mappings; /* Number of in-memory mappings */
401  XLogRecPtr start_lsn; /* Insert LSN at begin of rewrite */
403 
405  TransactionId *snapshotConflictHorizon);
406 
407 extern void heap_redo(XLogReaderState *record);
408 extern void heap_desc(StringInfo buf, XLogReaderState *record);
409 extern const char *heap_identify(uint8 info);
410 extern void heap_mask(char *pagedata, BlockNumber blkno);
411 extern void heap2_redo(XLogReaderState *record);
412 extern void heap2_desc(StringInfo buf, XLogReaderState *record);
413 extern const char *heap2_identify(uint8 info);
415 
416 extern XLogRecPtr log_heap_visible(Relation rel, Buffer heap_buffer,
417  Buffer vm_buffer,
418  TransactionId snapshotConflictHorizon,
419  uint8 vmflags);
420 
421 #endif /* HEAPAM_XLOG_H */
uint32 BlockNumber
Definition: block.h:31
int Buffer
Definition: buf.h:23
unsigned short uint16
Definition: c.h:494
unsigned int uint32
Definition: c.h:495
#define FLEXIBLE_ARRAY_MEMBER
Definition: c.h:387
unsigned char uint8
Definition: c.h:493
uint32 CommandId
Definition: c.h:655
uint32 TransactionId
Definition: c.h:641
struct xl_heap_rewrite_mapping xl_heap_rewrite_mapping
XLogRecPtr log_heap_visible(Relation rel, Buffer heap_buffer, Buffer vm_buffer, TransactionId snapshotConflictHorizon, uint8 vmflags)
Definition: heapam.c:8316
struct xl_heap_delete xl_heap_delete
void heap_desc(StringInfo buf, XLogReaderState *record)
Definition: heapdesc.c:95
void heap_redo(XLogReaderState *record)
Definition: heapam.c:9954
const char * heap_identify(uint8 info)
Definition: heapdesc.c:305
void heap2_desc(StringInfo buf, XLogReaderState *record)
Definition: heapdesc.c:172
void heap_mask(char *pagedata, BlockNumber blkno)
Definition: heapam.c:10043
void HeapTupleHeaderAdvanceConflictHorizon(HeapTupleHeader tuple, TransactionId *snapshotConflictHorizon)
Definition: heapam.c:7484
struct xl_heap_new_cid xl_heap_new_cid
const char * heap2_identify(uint8 info)
Definition: heapdesc.c:350
struct xl_heap_lock xl_heap_lock
void heap_xlog_logical_rewrite(XLogReaderState *r)
Definition: rewriteheap.c:1107
struct xl_heap_prune xl_heap_prune
struct xl_heap_multi_insert xl_heap_multi_insert
struct xl_heap_confirm xl_heap_confirm
struct xl_heap_vacuum xl_heap_vacuum
struct xl_heap_freeze_plan xl_heap_freeze_plan
struct xl_heap_insert xl_heap_insert
struct xl_heap_lock_updated xl_heap_lock_updated
struct xl_heap_freeze_page xl_heap_freeze_page
struct xl_heap_inplace xl_heap_inplace
void heap2_redo(XLogReaderState *record)
Definition: heapam.c:10000
struct xl_heap_header xl_heap_header
struct xl_multi_insert_tuple xl_multi_insert_tuple
struct xl_heap_visible xl_heap_visible
struct xl_heap_update xl_heap_update
struct xl_heap_truncate xl_heap_truncate
uint16 OffsetNumber
Definition: off.h:24
static char * buf
Definition: pg_test_fsync.c:67
unsigned int Oid
Definition: postgres_ext.h:31
OffsetNumber offnum
Definition: heapam_xlog.h:304
TransactionId xmax
Definition: heapam_xlog.h:109
OffsetNumber offnum
Definition: heapam_xlog.h:110
uint8 infobits_set
Definition: heapam_xlog.h:111
TransactionId snapshotConflictHorizon
Definition: heapam_xlog.h:347
TransactionId xmax
Definition: heapam_xlog.h:328
uint16 t_infomask
Definition: heapam_xlog.h:147
uint16 t_infomask2
Definition: heapam_xlog.h:146
OffsetNumber offnum
Definition: heapam_xlog.h:312
OffsetNumber offnum
Definition: heapam_xlog.h:156
TransactionId xmax
Definition: heapam_xlog.h:293
OffsetNumber offnum
Definition: heapam_xlog.h:294
uint8 infobits_set
Definition: heapam_xlog.h:284
OffsetNumber offnum
Definition: heapam_xlog.h:283
TransactionId xmax
Definition: heapam_xlog.h:282
OffsetNumber offsets[FLEXIBLE_ARRAY_MEMBER]
Definition: heapam_xlog.h:179
CommandId cmin
Definition: heapam_xlog.h:380
CommandId combocid
Definition: heapam_xlog.h:382
ItemPointerData target_tid
Definition: heapam_xlog.h:388
TransactionId top_xid
Definition: heapam_xlog.h:379
CommandId cmax
Definition: heapam_xlog.h:381
RelFileLocator target_locator
Definition: heapam_xlog.h:387
TransactionId snapshotConflictHorizon
Definition: heapam_xlog.h:245
uint16 nredirected
Definition: heapam_xlog.h:246
TransactionId mapped_xid
Definition: heapam_xlog.h:396
Oid relids[FLEXIBLE_ARRAY_MEMBER]
Definition: heapam_xlog.h:133
TransactionId new_xmax
Definition: heapam_xlog.h:218
uint8 old_infobits_set
Definition: heapam_xlog.h:216
TransactionId old_xmax
Definition: heapam_xlog.h:214
OffsetNumber old_offnum
Definition: heapam_xlog.h:215
OffsetNumber new_offnum
Definition: heapam_xlog.h:219
TransactionId snapshotConflictHorizon
Definition: heapam_xlog.h:367
uint64 XLogRecPtr
Definition: xlogdefs.h:21