1 /*-------------------------------------------------------------------------
4 * Support functions to rewrite tables.
6 * These functions provide a facility to completely rewrite a heap, while
7 * preserving visibility information and update chains.
11 * The caller is responsible for creating the new heap, all catalog
12 * changes, supplying the tuples to be written to the new heap, and
13 * rebuilding indexes. The caller must hold AccessExclusiveLock on the
14 * target table, because we assume no one else is writing into it.
16 * To use the facility:
19 * while (fetch next tuple)
22 * rewrite_heap_dead_tuple
25 * // do any transformations here if required
31 * The contents of the new relation shouldn't be relied on until after
32 * end_heap_rewrite is called.
37 * This would be a fairly trivial affair, except that we need to maintain
38 * the ctid chains that link versions of an updated tuple together.
39 * Since the newly stored tuples will have tids different from the original
40 * ones, if we just copied t_ctid fields to the new table the links would
41 * be wrong. When we are required to copy a (presumably recently-dead or
42 * delete-in-progress) tuple whose ctid doesn't point to itself, we have
43 * to substitute the correct ctid instead.
45 * For each ctid reference from A -> B, we might encounter either A first
46 * or B first. (Note that a tuple in the middle of a chain is both A and B
47 * of different pairs.)
49 * If we encounter A first, we'll store the tuple in the unresolved_tups
50 * hash table. When we later encounter B, we remove A from the hash table,
51 * fix the ctid to point to the new location of B, and insert both A and B
54 * If we encounter B first, we can insert B to the new heap right away.
55 * We then add an entry to the old_new_tid_map hash table showing B's
56 * original tid (in the old heap) and new tid (in the new heap).
57 * When we later encounter A, we get the new location of B from the table,
58 * and can write A immediately with the correct ctid.
60 * Entries in the hash tables can be removed as soon as the later tuple
61 * is encountered. That helps to keep the memory usage down. At the end,
62 * both tables are usually empty; we should have encountered both A and B
63 * of each pair. However, it's possible for A to be RECENTLY_DEAD and B
64 * entirely DEAD according to HeapTupleSatisfiesVacuum, because the test
65 * for deadness using OldestXmin is not exact. In such a case we might
66 * encounter B first, and skip it, and find A later. Then A would be added
67 * to unresolved_tups, and stay there until end of the rewrite. Since
68 * this case is very unusual, we don't worry about the memory usage.
70 * Using in-memory hash tables means that we use some memory for each live
71 * update chain in the table, from the time we find one end of the
72 * reference until we find the other end. That shouldn't be a problem in
73 * practice, but if you do something like an UPDATE without a where-clause
74 * on a large table, and then run CLUSTER in the same transaction, you
75 * could run out of memory. It doesn't seem worthwhile to add support for
76 * spill-to-disk, as there shouldn't be that many RECENTLY_DEAD tuples in a
77 * table under normal circumstances. Furthermore, in the typical scenario
78 * of CLUSTERing on an unchanging key column, we'll see all the versions
79 * of a given tuple together anyway, and so the peak memory usage is only
80 * proportional to the number of RECENTLY_DEAD versions of a single row, not
81 * in the whole table. Note that if we do fail halfway through a CLUSTER,
82 * the old table is still valid, so failure is not catastrophic.
84 * We can't use the normal heap_insert function to insert into the new
85 * heap, because heap_insert overwrites the visibility information.
86 * We use a special-purpose raw_heap_insert function instead, which
87 * is optimized for bulk inserting a lot of tuples, knowing that we have
88 * exclusive access to the heap. raw_heap_insert builds new pages in
89 * local storage. When a page is full, or at the end of the process,
90 * we insert it to WAL as a single record and then write it to disk
91 * directly through smgr. Note, however, that any data sent to the new
92 * heap's TOAST table will go through the normal bufmgr.
95 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
96 * Portions Copyright (c) 1994-5, Regents of the University of California
99 * src/backend/access/heap/rewriteheap.c
101 *-------------------------------------------------------------------------
103 #include "postgres.h"
105 #include <sys/stat.h>
108 #include "access/heapam.h"
109 #include "access/heapam_xlog.h"
110 #include "access/heaptoast.h"
111 #include "access/rewriteheap.h"
112 #include "access/transam.h"
113 #include "access/xact.h"
114 #include "access/xloginsert.h"
115 #include "catalog/catalog.h"
116 #include "lib/ilist.h"
117 #include "miscadmin.h"
119 #include "replication/logical.h"
120 #include "replication/slot.h"
121 #include "storage/bufmgr.h"
122 #include "storage/fd.h"
123 #include "storage/procarray.h"
124 #include "storage/smgr.h"
125 #include "utils/memutils.h"
126 #include "utils/rel.h"
129 * State associated with a rewrite operation. This is opaque to the user
130 * of the rewrite facility.
132 typedef struct RewriteStateData
134 Relation rs_old_rel
; /* source heap */
135 Relation rs_new_rel
; /* destination heap */
136 Page rs_buffer
; /* page currently being built */
137 BlockNumber rs_blockno
; /* block where page will go */
138 bool rs_buffer_valid
; /* T if any tuples in buffer */
139 bool rs_logical_rewrite
; /* do we need to do logical rewriting */
140 TransactionId rs_oldest_xmin
; /* oldest xmin used by caller to determine
141 * tuple visibility */
142 TransactionId rs_freeze_xid
; /* Xid that will be used as freeze cutoff
144 TransactionId rs_logical_xmin
; /* Xid that will be used as cutoff point
145 * for logical rewrites */
146 MultiXactId rs_cutoff_multi
; /* MultiXactId that will be used as cutoff
147 * point for multixacts */
148 MemoryContext rs_cxt
; /* for hash tables and entries and tuples in
150 XLogRecPtr rs_begin_lsn
; /* XLogInsertLsn when starting the rewrite */
151 HTAB
*rs_unresolved_tups
; /* unmatched A tuples */
152 HTAB
*rs_old_new_tid_map
; /* unmatched B tuples */
153 HTAB
*rs_logical_mappings
; /* logical remapping files */
154 uint32 rs_num_rewrite_mappings
; /* # in memory mappings */
158 * The lookup keys for the hash tables are tuple TID and xmin (we must check
159 * both to avoid false matches from dead tuples). Beware that there is
160 * probably some padding space in this struct; it must be zeroed out for
161 * correct hashtable operation.
165 TransactionId xmin
; /* tuple xmin */
166 ItemPointerData tid
; /* tuple location in old heap */
170 * Entry structures for the hash tables
174 TidHashKey key
; /* expected xmin/old location of B tuple */
175 ItemPointerData old_tid
; /* A's location in the old heap */
176 HeapTuple tuple
; /* A's tuple contents */
179 typedef UnresolvedTupData
*UnresolvedTup
;
183 TidHashKey key
; /* actual xmin/old location of B tuple */
184 ItemPointerData new_tid
; /* where we put it in the new heap */
185 } OldToNewMappingData
;
187 typedef OldToNewMappingData
*OldToNewMapping
;
190 * In-Memory data for an xid that might need logical remapping entries
193 typedef struct RewriteMappingFile
195 TransactionId xid
; /* xid that might need to see the row */
196 int vfd
; /* fd of mappings file */
197 off_t off
; /* how far have we written yet */
198 uint32 num_mappings
; /* number of in-memory mappings */
199 dlist_head mappings
; /* list of in-memory mappings */
200 char path
[MAXPGPATH
]; /* path, for error messages */
201 } RewriteMappingFile
;
204 * A single In-Memory logical rewrite mapping, hanging off
205 * RewriteMappingFile->mappings.
207 typedef struct RewriteMappingDataEntry
209 LogicalRewriteMappingData map
; /* map between old and new location of the
212 } RewriteMappingDataEntry
;
215 /* prototypes for internal functions */
216 static void raw_heap_insert(RewriteState state
, HeapTuple tup
);
218 /* internal logical remapping prototypes */
219 static void logical_begin_heap_rewrite(RewriteState state
);
220 static void logical_rewrite_heap_tuple(RewriteState state
, ItemPointerData old_tid
, HeapTuple new_tuple
);
221 static void logical_end_heap_rewrite(RewriteState state
);
225 * Begin a rewrite of a table
227 * old_heap old, locked heap relation tuples will be read from
228 * new_heap new, locked heap relation to insert tuples to
229 * oldest_xmin xid used by the caller to determine which tuples are dead
230 * freeze_xid xid before which tuples will be frozen
231 * cutoff_multi multixact before which multis will be removed
233 * Returns an opaque RewriteState, allocated in current memory context,
234 * to be used in subsequent calls to the other functions.
237 begin_heap_rewrite(Relation old_heap
, Relation new_heap
, TransactionId oldest_xmin
,
238 TransactionId freeze_xid
, MultiXactId cutoff_multi
)
241 MemoryContext rw_cxt
;
242 MemoryContext old_cxt
;
246 * To ease cleanup, make a separate context that will contain the
247 * RewriteState struct itself plus all subsidiary data.
249 rw_cxt
= AllocSetContextCreate(CurrentMemoryContext
,
251 ALLOCSET_DEFAULT_SIZES
);
252 old_cxt
= MemoryContextSwitchTo(rw_cxt
);
254 /* Create and fill in the state struct */
255 state
= palloc0(sizeof(RewriteStateData
));
257 state
->rs_old_rel
= old_heap
;
258 state
->rs_new_rel
= new_heap
;
259 state
->rs_buffer
= (Page
) palloc(BLCKSZ
);
260 /* new_heap needn't be empty, just locked */
261 state
->rs_blockno
= RelationGetNumberOfBlocks(new_heap
);
262 state
->rs_buffer_valid
= false;
263 state
->rs_oldest_xmin
= oldest_xmin
;
264 state
->rs_freeze_xid
= freeze_xid
;
265 state
->rs_cutoff_multi
= cutoff_multi
;
266 state
->rs_cxt
= rw_cxt
;
268 /* Initialize hash tables used to track update chains */
269 hash_ctl
.keysize
= sizeof(TidHashKey
);
270 hash_ctl
.entrysize
= sizeof(UnresolvedTupData
);
271 hash_ctl
.hcxt
= state
->rs_cxt
;
273 state
->rs_unresolved_tups
=
274 hash_create("Rewrite / Unresolved ctids",
275 128, /* arbitrary initial size */
277 HASH_ELEM
| HASH_BLOBS
| HASH_CONTEXT
);
279 hash_ctl
.entrysize
= sizeof(OldToNewMappingData
);
281 state
->rs_old_new_tid_map
=
282 hash_create("Rewrite / Old to new tid map",
283 128, /* arbitrary initial size */
285 HASH_ELEM
| HASH_BLOBS
| HASH_CONTEXT
);
287 MemoryContextSwitchTo(old_cxt
);
289 logical_begin_heap_rewrite(state
);
297 * state and any other resources are freed.
300 end_heap_rewrite(RewriteState state
)
302 HASH_SEQ_STATUS seq_status
;
303 UnresolvedTup unresolved
;
306 * Write any remaining tuples in the UnresolvedTups table. If we have any
307 * left, they should in fact be dead, but let's err on the safe side.
309 hash_seq_init(&seq_status
, state
->rs_unresolved_tups
);
311 while ((unresolved
= hash_seq_search(&seq_status
)) != NULL
)
313 ItemPointerSetInvalid(&unresolved
->tuple
->t_data
->t_ctid
);
314 raw_heap_insert(state
, unresolved
->tuple
);
317 /* Write the last page, if any */
318 if (state
->rs_buffer_valid
)
320 if (RelationNeedsWAL(state
->rs_new_rel
))
321 log_newpage(&state
->rs_new_rel
->rd_node
,
327 PageSetChecksumInplace(state
->rs_buffer
, state
->rs_blockno
);
329 smgrextend(RelationGetSmgr(state
->rs_new_rel
), MAIN_FORKNUM
,
330 state
->rs_blockno
, (char *) state
->rs_buffer
, true);
334 * When we WAL-logged rel pages, we must nonetheless fsync them. The
335 * reason is the same as in storage.c's RelationCopyStorage(): we're
336 * writing data that's not in shared buffers, and so a CHECKPOINT
337 * occurring during the rewriteheap operation won't have fsync'd data we
338 * wrote before the checkpoint.
340 if (RelationNeedsWAL(state
->rs_new_rel
))
341 smgrimmedsync(RelationGetSmgr(state
->rs_new_rel
), MAIN_FORKNUM
);
343 logical_end_heap_rewrite(state
);
345 /* Deleting the context frees everything */
346 MemoryContextDelete(state
->rs_cxt
);
350 * Add a tuple to the new heap.
352 * Visibility information is copied from the original tuple, except that
353 * we "freeze" very-old tuples. Note that since we scribble on new_tuple,
354 * it had better be temp storage not a pointer to the original tuple.
356 * state opaque state as returned by begin_heap_rewrite
357 * old_tuple original tuple in the old heap
358 * new_tuple new, rewritten tuple to be inserted to new heap
361 rewrite_heap_tuple(RewriteState state
,
362 HeapTuple old_tuple
, HeapTuple new_tuple
)
364 MemoryContext old_cxt
;
365 ItemPointerData old_tid
;
370 old_cxt
= MemoryContextSwitchTo(state
->rs_cxt
);
373 * Copy the original tuple's visibility information into new_tuple.
375 * XXX we might later need to copy some t_infomask2 bits, too? Right now,
376 * we intentionally clear the HOT status bits.
378 memcpy(&new_tuple
->t_data
->t_choice
.t_heap
,
379 &old_tuple
->t_data
->t_choice
.t_heap
,
380 sizeof(HeapTupleFields
));
382 new_tuple
->t_data
->t_infomask
&= ~HEAP_XACT_MASK
;
383 new_tuple
->t_data
->t_infomask2
&= ~HEAP2_XACT_MASK
;
384 new_tuple
->t_data
->t_infomask
|=
385 old_tuple
->t_data
->t_infomask
& HEAP_XACT_MASK
;
388 * While we have our hands on the tuple, we may as well freeze any
389 * eligible xmin or xmax, so that future VACUUM effort can be saved.
391 heap_freeze_tuple(new_tuple
->t_data
,
392 state
->rs_old_rel
->rd_rel
->relfrozenxid
,
393 state
->rs_old_rel
->rd_rel
->relminmxid
,
394 state
->rs_freeze_xid
,
395 state
->rs_cutoff_multi
);
398 * Invalid ctid means that ctid should point to the tuple itself. We'll
399 * override it later if the tuple is part of an update chain.
401 ItemPointerSetInvalid(&new_tuple
->t_data
->t_ctid
);
404 * If the tuple has been updated, check the old-to-new mapping hash table.
406 if (!((old_tuple
->t_data
->t_infomask
& HEAP_XMAX_INVALID
) ||
407 HeapTupleHeaderIsOnlyLocked(old_tuple
->t_data
)) &&
408 !HeapTupleHeaderIndicatesMovedPartitions(old_tuple
->t_data
) &&
409 !(ItemPointerEquals(&(old_tuple
->t_self
),
410 &(old_tuple
->t_data
->t_ctid
))))
412 OldToNewMapping mapping
;
414 memset(&hashkey
, 0, sizeof(hashkey
));
415 hashkey
.xmin
= HeapTupleHeaderGetUpdateXid(old_tuple
->t_data
);
416 hashkey
.tid
= old_tuple
->t_data
->t_ctid
;
418 mapping
= (OldToNewMapping
)
419 hash_search(state
->rs_old_new_tid_map
, &hashkey
,
425 * We've already copied the tuple that t_ctid points to, so we can
426 * set the ctid of this tuple to point to the new location, and
427 * insert it right away.
429 new_tuple
->t_data
->t_ctid
= mapping
->new_tid
;
431 /* We don't need the mapping entry anymore */
432 hash_search(state
->rs_old_new_tid_map
, &hashkey
,
433 HASH_REMOVE
, &found
);
439 * We haven't seen the tuple t_ctid points to yet. Stash this
440 * tuple into unresolved_tups to be written later.
442 UnresolvedTup unresolved
;
444 unresolved
= hash_search(state
->rs_unresolved_tups
, &hashkey
,
448 unresolved
->old_tid
= old_tuple
->t_self
;
449 unresolved
->tuple
= heap_copytuple(new_tuple
);
452 * We can't do anything more now, since we don't know where the
453 * tuple will be written.
455 MemoryContextSwitchTo(old_cxt
);
461 * Now we will write the tuple, and then check to see if it is the B tuple
462 * in any new or known pair. When we resolve a known pair, we will be
463 * able to write that pair's A tuple, and then we have to check if it
464 * resolves some other pair. Hence, we need a loop here.
466 old_tid
= old_tuple
->t_self
;
471 ItemPointerData new_tid
;
473 /* Insert the tuple and find out where it's put in new_heap */
474 raw_heap_insert(state
, new_tuple
);
475 new_tid
= new_tuple
->t_self
;
477 logical_rewrite_heap_tuple(state
, old_tid
, new_tuple
);
480 * If the tuple is the updated version of a row, and the prior version
481 * wouldn't be DEAD yet, then we need to either resolve the prior
482 * version (if it's waiting in rs_unresolved_tups), or make an entry
483 * in rs_old_new_tid_map (so we can resolve it when we do see it). The
484 * previous tuple's xmax would equal this one's xmin, so it's
485 * RECENTLY_DEAD if and only if the xmin is not before OldestXmin.
487 if ((new_tuple
->t_data
->t_infomask
& HEAP_UPDATED
) &&
488 !TransactionIdPrecedes(HeapTupleHeaderGetXmin(new_tuple
->t_data
),
489 state
->rs_oldest_xmin
))
492 * Okay, this is B in an update pair. See if we've seen A.
494 UnresolvedTup unresolved
;
496 memset(&hashkey
, 0, sizeof(hashkey
));
497 hashkey
.xmin
= HeapTupleHeaderGetXmin(new_tuple
->t_data
);
498 hashkey
.tid
= old_tid
;
500 unresolved
= hash_search(state
->rs_unresolved_tups
, &hashkey
,
503 if (unresolved
!= NULL
)
506 * We have seen and memorized the previous tuple already. Now
507 * that we know where we inserted the tuple its t_ctid points
508 * to, fix its t_ctid and insert it to the new heap.
511 heap_freetuple(new_tuple
);
512 new_tuple
= unresolved
->tuple
;
514 old_tid
= unresolved
->old_tid
;
515 new_tuple
->t_data
->t_ctid
= new_tid
;
518 * We don't need the hash entry anymore, but don't free its
521 hash_search(state
->rs_unresolved_tups
, &hashkey
,
522 HASH_REMOVE
, &found
);
525 /* loop back to insert the previous tuple in the chain */
531 * Remember the new tid of this tuple. We'll use it to set the
532 * ctid when we find the previous tuple in the chain.
534 OldToNewMapping mapping
;
536 mapping
= hash_search(state
->rs_old_new_tid_map
, &hashkey
,
540 mapping
->new_tid
= new_tid
;
544 /* Done with this (chain of) tuples, for now */
546 heap_freetuple(new_tuple
);
550 MemoryContextSwitchTo(old_cxt
);
554 * Register a dead tuple with an ongoing rewrite. Dead tuples are not
555 * copied to the new table, but we still make note of them so that we
556 * can release some resources earlier.
558 * Returns true if a tuple was removed from the unresolved_tups table.
559 * This indicates that that tuple, previously thought to be "recently dead",
560 * is now known really dead and won't be written to the output.
563 rewrite_heap_dead_tuple(RewriteState state
, HeapTuple old_tuple
)
566 * If we have already seen an earlier tuple in the update chain that
567 * points to this tuple, let's forget about that earlier tuple. It's in
568 * fact dead as well, our simple xmax < OldestXmin test in
569 * HeapTupleSatisfiesVacuum just wasn't enough to detect it. It happens
570 * when xmin of a tuple is greater than xmax, which sounds
571 * counter-intuitive but is perfectly valid.
573 * We don't bother to try to detect the situation the other way round,
574 * when we encounter the dead tuple first and then the recently dead one
575 * that points to it. If that happens, we'll have some unmatched entries
576 * in the UnresolvedTups hash table at the end. That can happen anyway,
577 * because a vacuum might have removed the dead tuple in the chain before
580 UnresolvedTup unresolved
;
584 memset(&hashkey
, 0, sizeof(hashkey
));
585 hashkey
.xmin
= HeapTupleHeaderGetXmin(old_tuple
->t_data
);
586 hashkey
.tid
= old_tuple
->t_self
;
588 unresolved
= hash_search(state
->rs_unresolved_tups
, &hashkey
,
591 if (unresolved
!= NULL
)
593 /* Need to free the contained tuple as well as the hashtable entry */
594 heap_freetuple(unresolved
->tuple
);
595 hash_search(state
->rs_unresolved_tups
, &hashkey
,
596 HASH_REMOVE
, &found
);
605 * Insert a tuple to the new relation. This has to track heap_insert
606 * and its subsidiary functions!
608 * t_self of the tuple is set to the new TID of the tuple. If t_ctid of the
609 * tuple is invalid on entry, it's replaced with the new TID as well (in
610 * the inserted data only, not in the caller's copy).
613 raw_heap_insert(RewriteState state
, HeapTuple tup
)
615 Page page
= state
->rs_buffer
;
623 * If the new tuple is too big for storage or contains already toasted
624 * out-of-line attributes from some other relation, invoke the toaster.
626 * Note: below this point, heaptup is the data we actually intend to store
627 * into the relation; tup is the caller's original untoasted data.
629 if (state
->rs_new_rel
->rd_rel
->relkind
== RELKIND_TOASTVALUE
)
631 /* toast table entries should never be recursively toasted */
632 Assert(!HeapTupleHasExternal(tup
));
635 else if (HeapTupleHasExternal(tup
) || tup
->t_len
> TOAST_TUPLE_THRESHOLD
)
637 int options
= HEAP_INSERT_SKIP_FSM
;
640 * While rewriting the heap for VACUUM FULL / CLUSTER, make sure data
641 * for the TOAST table are not logically decoded. The main heap is
642 * WAL-logged as XLOG FPI records, which are not logically decoded.
644 options
|= HEAP_INSERT_NO_LOGICAL
;
646 heaptup
= heap_toast_insert_or_update(state
->rs_new_rel
, tup
, NULL
,
652 len
= MAXALIGN(heaptup
->t_len
); /* be conservative */
655 * If we're gonna fail for oversize tuple, do it right away
657 if (len
> MaxHeapTupleSize
)
659 (errcode(ERRCODE_PROGRAM_LIMIT_EXCEEDED
),
660 errmsg("row is too big: size %zu, maximum size %zu",
661 len
, MaxHeapTupleSize
)));
663 /* Compute desired extra freespace due to fillfactor option */
664 saveFreeSpace
= RelationGetTargetPageFreeSpace(state
->rs_new_rel
,
665 HEAP_DEFAULT_FILLFACTOR
);
667 /* Now we can check to see if there's enough free space already. */
668 if (state
->rs_buffer_valid
)
670 pageFreeSpace
= PageGetHeapFreeSpace(page
);
672 if (len
+ saveFreeSpace
> pageFreeSpace
)
675 * Doesn't fit, so write out the existing page. It always
676 * contains a tuple. Hence, unlike RelationGetBufferForTuple(),
677 * enforce saveFreeSpace unconditionally.
681 if (RelationNeedsWAL(state
->rs_new_rel
))
682 log_newpage(&state
->rs_new_rel
->rd_node
,
689 * Now write the page. We say skipFsync = true because there's no
690 * need for smgr to schedule an fsync for this write; we'll do it
691 * ourselves in end_heap_rewrite.
693 PageSetChecksumInplace(page
, state
->rs_blockno
);
695 smgrextend(RelationGetSmgr(state
->rs_new_rel
), MAIN_FORKNUM
,
696 state
->rs_blockno
, (char *) page
, true);
699 state
->rs_buffer_valid
= false;
703 if (!state
->rs_buffer_valid
)
705 /* Initialize a new empty page */
706 PageInit(page
, BLCKSZ
, 0);
707 state
->rs_buffer_valid
= true;
710 /* And now we can insert the tuple into the page */
711 newoff
= PageAddItem(page
, (Item
) heaptup
->t_data
, heaptup
->t_len
,
712 InvalidOffsetNumber
, false, true);
713 if (newoff
== InvalidOffsetNumber
)
714 elog(ERROR
, "failed to add tuple");
716 /* Update caller's t_self to the actual position where it was stored */
717 ItemPointerSet(&(tup
->t_self
), state
->rs_blockno
, newoff
);
720 * Insert the correct position into CTID of the stored tuple, too, if the
721 * caller didn't supply a valid CTID.
723 if (!ItemPointerIsValid(&tup
->t_data
->t_ctid
))
726 HeapTupleHeader onpage_tup
;
728 newitemid
= PageGetItemId(page
, newoff
);
729 onpage_tup
= (HeapTupleHeader
) PageGetItem(page
, newitemid
);
731 onpage_tup
->t_ctid
= tup
->t_self
;
734 /* If heaptup is a private copy, release it. */
736 heap_freetuple(heaptup
);
739 /* ------------------------------------------------------------------------
740 * Logical rewrite support
742 * When doing logical decoding - which relies on using cmin/cmax of catalog
743 * tuples, via xl_heap_new_cid records - heap rewrites have to log enough
744 * information to allow the decoding backend to updates its internal mapping
745 * of (relfilenode,ctid) => (cmin, cmax) to be correct for the rewritten heap.
747 * For that, every time we find a tuple that's been modified in a catalog
748 * relation within the xmin horizon of any decoding slot, we log a mapping
749 * from the old to the new location.
751 * To deal with rewrites that abort the filename of a mapping file contains
752 * the xid of the transaction performing the rewrite, which then can be
753 * checked before being read in.
755 * For efficiency we don't immediately spill every single map mapping for a
756 * row to disk but only do so in batches when we've collected several of them
757 * in memory or when end_heap_rewrite() has been called.
759 * Crash-Safety: This module diverts from the usual patterns of doing WAL
760 * since it cannot rely on checkpoint flushing out all buffers and thus
761 * waiting for exclusive locks on buffers. Usually the XLogInsert() covering
762 * buffer modifications is performed while the buffer(s) that are being
763 * modified are exclusively locked guaranteeing that both the WAL record and
764 * the modified heap are on either side of the checkpoint. But since the
765 * mapping files we log aren't in shared_buffers that interlock doesn't work.
767 * Instead we simply write the mapping files out to disk, *before* the
768 * XLogInsert() is performed. That guarantees that either the XLogInsert() is
769 * inserted after the checkpoint's redo pointer or that the checkpoint (via
770 * CheckPointLogicalRewriteHeap()) has flushed the (partial) mapping file to
771 * disk. That leaves the tail end that has not yet been flushed open to
772 * corruption, which is solved by including the current offset in the
773 * xl_heap_rewrite_mapping records and truncating the mapping file to it
774 * during replay. Every time a rewrite is finished all generated mapping files
775 * are synced to disk.
777 * Note that if we were only concerned about crash safety we wouldn't have to
778 * deal with WAL logging at all - an fsync() at the end of a rewrite would be
779 * sufficient for crash safety. Any mapping that hasn't been safely flushed to
780 * disk has to be by an aborted (explicitly or via a crash) transaction and is
781 * ignored by virtue of the xid in its name being subject to a
782 * TransactionDidCommit() check. But we want to support having standbys via
783 * physical replication, both for availability and to do logical decoding
785 * ------------------------------------------------------------------------
789 * Do preparations for logging logical mappings during a rewrite if
790 * necessary. If we detect that we don't need to log anything we'll prevent
791 * any further action by the various logical rewrite functions.
794 logical_begin_heap_rewrite(RewriteState state
)
797 TransactionId logical_xmin
;
800 * We only need to persist these mappings if the rewritten table can be
801 * accessed during logical decoding, if not, we can skip doing any
804 state
->rs_logical_rewrite
=
805 RelationIsAccessibleInLogicalDecoding(state
->rs_old_rel
);
807 if (!state
->rs_logical_rewrite
)
810 ProcArrayGetReplicationSlotXmin(NULL
, &logical_xmin
);
813 * If there are no logical slots in progress we don't need to do anything,
814 * there cannot be any remappings for relevant rows yet. The relation's
815 * lock protects us against races.
817 if (logical_xmin
== InvalidTransactionId
)
819 state
->rs_logical_rewrite
= false;
823 state
->rs_logical_xmin
= logical_xmin
;
824 state
->rs_begin_lsn
= GetXLogInsertRecPtr();
825 state
->rs_num_rewrite_mappings
= 0;
827 hash_ctl
.keysize
= sizeof(TransactionId
);
828 hash_ctl
.entrysize
= sizeof(RewriteMappingFile
);
829 hash_ctl
.hcxt
= state
->rs_cxt
;
831 state
->rs_logical_mappings
=
832 hash_create("Logical rewrite mapping",
833 128, /* arbitrary initial size */
835 HASH_ELEM
| HASH_BLOBS
| HASH_CONTEXT
);
839 * Flush all logical in-memory mappings to disk, but don't fsync them yet.
842 logical_heap_rewrite_flush_mappings(RewriteState state
)
844 HASH_SEQ_STATUS seq_status
;
845 RewriteMappingFile
*src
;
846 dlist_mutable_iter iter
;
848 Assert(state
->rs_logical_rewrite
);
850 /* no logical rewrite in progress, no need to iterate over mappings */
851 if (state
->rs_num_rewrite_mappings
== 0)
854 elog(DEBUG1
, "flushing %u logical rewrite mapping entries",
855 state
->rs_num_rewrite_mappings
);
857 hash_seq_init(&seq_status
, state
->rs_logical_mappings
);
858 while ((src
= (RewriteMappingFile
*) hash_seq_search(&seq_status
)) != NULL
)
862 xl_heap_rewrite_mapping xlrec
;
867 /* this file hasn't got any new mappings */
868 if (src
->num_mappings
== 0)
871 if (state
->rs_old_rel
->rd_rel
->relisshared
)
874 dboid
= MyDatabaseId
;
876 xlrec
.num_mappings
= src
->num_mappings
;
877 xlrec
.mapped_rel
= RelationGetRelid(state
->rs_old_rel
);
878 xlrec
.mapped_xid
= src
->xid
;
879 xlrec
.mapped_db
= dboid
;
880 xlrec
.offset
= src
->off
;
881 xlrec
.start_lsn
= state
->rs_begin_lsn
;
883 /* write all mappings consecutively */
884 len
= src
->num_mappings
* sizeof(LogicalRewriteMappingData
);
885 waldata_start
= waldata
= palloc(len
);
888 * collect data we need to write out, but don't modify ondisk data yet
890 dlist_foreach_modify(iter
, &src
->mappings
)
892 RewriteMappingDataEntry
*pmap
;
894 pmap
= dlist_container(RewriteMappingDataEntry
, node
, iter
.cur
);
896 memcpy(waldata
, &pmap
->map
, sizeof(pmap
->map
));
897 waldata
+= sizeof(pmap
->map
);
899 /* remove from the list and free */
900 dlist_delete(&pmap
->node
);
903 /* update bookkeeping */
904 state
->rs_num_rewrite_mappings
--;
908 Assert(src
->num_mappings
== 0);
909 Assert(waldata
== waldata_start
+ len
);
912 * Note that we deviate from the usual WAL coding practices here,
913 * check the above "Logical rewrite support" comment for reasoning.
915 written
= FileWrite(src
->vfd
, waldata_start
, len
, src
->off
,
916 WAIT_EVENT_LOGICAL_REWRITE_WRITE
);
919 (errcode_for_file_access(),
920 errmsg("could not write to file \"%s\", wrote %d of %d: %m", src
->path
,
925 XLogRegisterData((char *) (&xlrec
), sizeof(xlrec
));
926 XLogRegisterData(waldata_start
, len
);
928 /* write xlog record */
929 XLogInsert(RM_HEAP2_ID
, XLOG_HEAP2_REWRITE
);
931 pfree(waldata_start
);
933 Assert(state
->rs_num_rewrite_mappings
== 0);
937 * Logical remapping part of end_heap_rewrite().
940 logical_end_heap_rewrite(RewriteState state
)
942 HASH_SEQ_STATUS seq_status
;
943 RewriteMappingFile
*src
;
945 /* done, no logical rewrite in progress */
946 if (!state
->rs_logical_rewrite
)
949 /* writeout remaining in-memory entries */
950 if (state
->rs_num_rewrite_mappings
> 0)
951 logical_heap_rewrite_flush_mappings(state
);
953 /* Iterate over all mappings we have written and fsync the files. */
954 hash_seq_init(&seq_status
, state
->rs_logical_mappings
);
955 while ((src
= (RewriteMappingFile
*) hash_seq_search(&seq_status
)) != NULL
)
957 if (FileSync(src
->vfd
, WAIT_EVENT_LOGICAL_REWRITE_SYNC
) != 0)
958 ereport(data_sync_elevel(ERROR
),
959 (errcode_for_file_access(),
960 errmsg("could not fsync file \"%s\": %m", src
->path
)));
963 /* memory context cleanup will deal with the rest */
967 * Log a single (old->new) mapping for 'xid'.
970 logical_rewrite_log_mapping(RewriteState state
, TransactionId xid
,
971 LogicalRewriteMappingData
*map
)
973 RewriteMappingFile
*src
;
974 RewriteMappingDataEntry
*pmap
;
978 relid
= RelationGetRelid(state
->rs_old_rel
);
980 /* look for existing mappings for this 'mapped' xid */
981 src
= hash_search(state
->rs_logical_mappings
, &xid
,
985 * We haven't yet had the need to map anything for this xid, create
986 * per-xid data structures.
990 char path
[MAXPGPATH
];
993 if (state
->rs_old_rel
->rd_rel
->relisshared
)
996 dboid
= MyDatabaseId
;
998 snprintf(path
, MAXPGPATH
,
999 "pg_logical/mappings/" LOGICAL_REWRITE_FORMAT
,
1001 LSN_FORMAT_ARGS(state
->rs_begin_lsn
),
1002 xid
, GetCurrentTransactionId());
1004 dlist_init(&src
->mappings
);
1005 src
->num_mappings
= 0;
1007 memcpy(src
->path
, path
, sizeof(path
));
1008 src
->vfd
= PathNameOpenFile(path
,
1009 O_CREAT
| O_EXCL
| O_WRONLY
| PG_BINARY
);
1012 (errcode_for_file_access(),
1013 errmsg("could not create file \"%s\": %m", path
)));
1016 pmap
= MemoryContextAlloc(state
->rs_cxt
,
1017 sizeof(RewriteMappingDataEntry
));
1018 memcpy(&pmap
->map
, map
, sizeof(LogicalRewriteMappingData
));
1019 dlist_push_tail(&src
->mappings
, &pmap
->node
);
1020 src
->num_mappings
++;
1021 state
->rs_num_rewrite_mappings
++;
1024 * Write out buffer every time we've too many in-memory entries across all
1027 if (state
->rs_num_rewrite_mappings
>= 1000 /* arbitrary number */ )
1028 logical_heap_rewrite_flush_mappings(state
);
1032 * Perform logical remapping for a tuple that's mapped from old_tid to
1033 * new_tuple->t_self by rewrite_heap_tuple() if necessary for the tuple.
1036 logical_rewrite_heap_tuple(RewriteState state
, ItemPointerData old_tid
,
1037 HeapTuple new_tuple
)
1039 ItemPointerData new_tid
= new_tuple
->t_self
;
1040 TransactionId cutoff
= state
->rs_logical_xmin
;
1043 bool do_log_xmin
= false;
1044 bool do_log_xmax
= false;
1045 LogicalRewriteMappingData map
;
1047 /* no logical rewrite in progress, we don't need to log anything */
1048 if (!state
->rs_logical_rewrite
)
1051 xmin
= HeapTupleHeaderGetXmin(new_tuple
->t_data
);
1052 /* use *GetUpdateXid to correctly deal with multixacts */
1053 xmax
= HeapTupleHeaderGetUpdateXid(new_tuple
->t_data
);
1056 * Log the mapping iff the tuple has been created recently.
1058 if (TransactionIdIsNormal(xmin
) && !TransactionIdPrecedes(xmin
, cutoff
))
1061 if (!TransactionIdIsNormal(xmax
))
1064 * no xmax is set, can't have any permanent ones, so this check is
1068 else if (HEAP_XMAX_IS_LOCKED_ONLY(new_tuple
->t_data
->t_infomask
))
1070 /* only locked, we don't care */
1072 else if (!TransactionIdPrecedes(xmax
, cutoff
))
1074 /* tuple has been deleted recently, log */
1078 /* if neither needs to be logged, we're done */
1079 if (!do_log_xmin
&& !do_log_xmax
)
1082 /* fill out mapping information */
1083 map
.old_node
= state
->rs_old_rel
->rd_node
;
1084 map
.old_tid
= old_tid
;
1085 map
.new_node
= state
->rs_new_rel
->rd_node
;
1086 map
.new_tid
= new_tid
;
1089 * Now persist the mapping for the individual xids that are affected. We
1090 * need to log for both xmin and xmax if they aren't the same transaction
1091 * since the mapping files are per "affected" xid.
1092 * We don't muster all that much effort detecting whether xmin and xmax
1093 * are actually the same transaction, we just check whether the xid is the
1094 * same disregarding subtransactions. Logging too much is relatively
1095 * harmless and we could never do the check fully since subtransaction
1096 * data is thrown away during restarts.
1100 logical_rewrite_log_mapping(state
, xmin
, &map
);
1101 /* separately log mapping for xmax unless it'd be redundant */
1102 if (do_log_xmax
&& !TransactionIdEquals(xmin
, xmax
))
1103 logical_rewrite_log_mapping(state
, xmax
, &map
);
1107 * Replay XLOG_HEAP2_REWRITE records
1110 heap_xlog_logical_rewrite(XLogReaderState
*r
)
1112 char path
[MAXPGPATH
];
1114 xl_heap_rewrite_mapping
*xlrec
;
1118 xlrec
= (xl_heap_rewrite_mapping
*) XLogRecGetData(r
);
1120 snprintf(path
, MAXPGPATH
,
1121 "pg_logical/mappings/" LOGICAL_REWRITE_FORMAT
,
1122 xlrec
->mapped_db
, xlrec
->mapped_rel
,
1123 LSN_FORMAT_ARGS(xlrec
->start_lsn
),
1124 xlrec
->mapped_xid
, XLogRecGetXid(r
));
1126 fd
= OpenTransientFile(path
,
1127 O_CREAT
| O_WRONLY
| PG_BINARY
);
1130 (errcode_for_file_access(),
1131 errmsg("could not create file \"%s\": %m", path
)));
1134 * Truncate all data that's not guaranteed to have been safely fsynced (by
1135 * previous record or by the last checkpoint).
1137 pgstat_report_wait_start(WAIT_EVENT_LOGICAL_REWRITE_TRUNCATE
);
1138 if (ftruncate(fd
, xlrec
->offset
) != 0)
1140 (errcode_for_file_access(),
1141 errmsg("could not truncate file \"%s\" to %u: %m",
1142 path
, (uint32
) xlrec
->offset
)));
1143 pgstat_report_wait_end();
1145 data
= XLogRecGetData(r
) + sizeof(*xlrec
);
1147 len
= xlrec
->num_mappings
* sizeof(LogicalRewriteMappingData
);
1149 /* write out tail end of mapping file (again) */
1151 pgstat_report_wait_start(WAIT_EVENT_LOGICAL_REWRITE_MAPPING_WRITE
);
1152 if (pg_pwrite(fd
, data
, len
, xlrec
->offset
) != len
)
1154 /* if write didn't set errno, assume problem is no disk space */
1158 (errcode_for_file_access(),
1159 errmsg("could not write to file \"%s\": %m", path
)));
1161 pgstat_report_wait_end();
1164 * Now fsync all previously written data. We could improve things and only
1165 * do this for the last write to a file, but the required bookkeeping
1166 * doesn't seem worth the trouble.
1168 pgstat_report_wait_start(WAIT_EVENT_LOGICAL_REWRITE_MAPPING_SYNC
);
1169 if (pg_fsync(fd
) != 0)
1170 ereport(data_sync_elevel(ERROR
),
1171 (errcode_for_file_access(),
1172 errmsg("could not fsync file \"%s\": %m", path
)));
1173 pgstat_report_wait_end();
1175 if (CloseTransientFile(fd
) != 0)
1177 (errcode_for_file_access(),
1178 errmsg("could not close file \"%s\": %m", path
)));
1182 * Perform a checkpoint for logical rewrite mappings
1184 * This serves two tasks:
1185 * 1) Remove all mappings not needed anymore based on the logical restart LSN
1186 * 2) Flush all remaining mappings to disk, so that replay after a checkpoint
1187 * only has to deal with the parts of a mapping that have been written out
1188 * after the checkpoint started.
1192 CheckPointLogicalRewriteHeap(void)
1197 struct dirent
*mapping_de
;
1198 char path
[MAXPGPATH
+ 20];
1201 * We start of with a minimum of the last redo pointer. No new decoding
1202 * slot will start before that, so that's a safe upper bound for removal.
1204 redo
= GetRedoRecPtr();
1206 /* now check for the restart ptrs from existing slots */
1207 cutoff
= ReplicationSlotsComputeLogicalRestartLSN();
1209 /* don't start earlier than the restart lsn */
1210 if (cutoff
!= InvalidXLogRecPtr
&& redo
< cutoff
)
1213 mappings_dir
= AllocateDir("pg_logical/mappings");
1214 while ((mapping_de
= ReadDir(mappings_dir
, "pg_logical/mappings")) != NULL
)
1216 struct stat statbuf
;
1220 TransactionId rewrite_xid
;
1221 TransactionId create_xid
;
1225 if (strcmp(mapping_de
->d_name
, ".") == 0 ||
1226 strcmp(mapping_de
->d_name
, "..") == 0)
1229 snprintf(path
, sizeof(path
), "pg_logical/mappings/%s", mapping_de
->d_name
);
1230 if (lstat(path
, &statbuf
) == 0 && !S_ISREG(statbuf
.st_mode
))
1233 /* Skip over files that cannot be ours. */
1234 if (strncmp(mapping_de
->d_name
, "map-", 4) != 0)
1237 if (sscanf(mapping_de
->d_name
, LOGICAL_REWRITE_FORMAT
,
1238 &dboid
, &relid
, &hi
, &lo
, &rewrite_xid
, &create_xid
) != 6)
1239 elog(ERROR
, "could not parse filename \"%s\"", mapping_de
->d_name
);
1241 lsn
= ((uint64
) hi
) << 32 | lo
;
1243 if (lsn
< cutoff
|| cutoff
== InvalidXLogRecPtr
)
1245 elog(DEBUG1
, "removing logical rewrite file \"%s\"", path
);
1246 if (unlink(path
) < 0)
1248 (errcode_for_file_access(),
1249 errmsg("could not remove file \"%s\": %m", path
)));
1253 /* on some operating systems fsyncing a file requires O_RDWR */
1254 int fd
= OpenTransientFile(path
, O_RDWR
| PG_BINARY
);
1257 * The file cannot vanish due to concurrency since this function
1258 * is the only one removing logical mappings and only one
1259 * checkpoint can be in progress at a time.
1263 (errcode_for_file_access(),
1264 errmsg("could not open file \"%s\": %m", path
)));
1267 * We could try to avoid fsyncing files that either haven't
1268 * changed or have only been created since the checkpoint's start,
1269 * but it's currently not deemed worth the effort.
1271 pgstat_report_wait_start(WAIT_EVENT_LOGICAL_REWRITE_CHECKPOINT_SYNC
);
1272 if (pg_fsync(fd
) != 0)
1273 ereport(data_sync_elevel(ERROR
),
1274 (errcode_for_file_access(),
1275 errmsg("could not fsync file \"%s\": %m", path
)));
1276 pgstat_report_wait_end();
1278 if (CloseTransientFile(fd
) != 0)
1280 (errcode_for_file_access(),
1281 errmsg("could not close file \"%s\": %m", path
)));
1284 FreeDir(mappings_dir
);