1 src/backend/access/transam/README
6 PostgreSQL's transaction system is a three-layer system. The bottom layer
7 implements low-level transactions and subtransactions, on top of which rests
8 the mainloop's control code, which in turn implements user-visible
9 transactions and savepoints.
11 The middle layer of code is called by postgres.c before and after the
12 processing of each query, or after detecting an error:
14 StartTransactionCommand
15 CommitTransactionCommand
16 AbortCurrentTransaction
18 Meanwhile, the user can alter the system's state by issuing the SQL commands
19 BEGIN, COMMIT, ROLLBACK, SAVEPOINT, ROLLBACK TO or RELEASE. The traffic cop
20 redirects these calls to the toplevel routines
24 UserAbortTransactionBlock
29 respectively. Depending on the current state of the system, these functions
30 call low level functions to activate the real transaction system:
41 Additionally, within a transaction, CommandCounterIncrement is called to
42 increment the command counter, which allows future commands to "see" the
43 effects of previous commands within the same transaction. Note that this is
44 done automatically by CommitTransactionCommand after each query inside a
45 transaction block, but some utility functions also do it internally to allow
46 some operations (usually in the system catalogs) to be seen by future
47 operations in the same utility command. (For example, in DefineRelation it is
48 done after creating the heap so the pg_class row is visible, to be able to
52 For example, consider the following sequence of user commands:
56 3) INSERT INTO foo VALUES (...)
59 In the main processing loop, this results in the following function call
62 / StartTransactionCommand;
64 1) < ProcessUtility; << BEGIN
65 \ BeginTransactionBlock;
66 \ CommitTransactionCommand;
68 / StartTransactionCommand;
69 2) / PortalRunSelect; << SELECT ...
70 \ CommitTransactionCommand;
71 \ CommandCounterIncrement;
73 / StartTransactionCommand;
74 3) / ProcessQuery; << INSERT ...
75 \ CommitTransactionCommand;
76 \ CommandCounterIncrement;
78 / StartTransactionCommand;
79 / ProcessUtility; << COMMIT
80 4) < EndTransactionBlock;
81 \ CommitTransactionCommand;
84 The point of this example is to demonstrate the need for
85 StartTransactionCommand and CommitTransactionCommand to be state smart -- they
86 should call CommandCounterIncrement between the calls to BeginTransactionBlock
87 and EndTransactionBlock and outside these calls they need to do normal start,
88 commit or abort processing.
90 Furthermore, suppose the "SELECT * FROM foo" caused an abort condition. In
91 this case AbortCurrentTransaction is called, and the transaction is put in
92 aborted state. In this state, any user input is ignored except for
93 transaction-termination statements, or ROLLBACK TO <savepoint> commands.
95 Transaction aborts can occur in two ways:
97 1) system dies from some internal cause (syntax error, etc)
98 2) user types ROLLBACK
100 The reason we have to distinguish them is illustrated by the following two
105 1) user types BEGIN 1) user types BEGIN
106 2) user does something 2) user does something
107 3) user does not like what 3) system aborts for some reason
108 she sees and types ABORT (syntax error, etc)
110 In case 1, we want to abort the transaction and return to the default state.
111 In case 2, there may be more commands coming our way which are part of the
112 same transaction block; we have to ignore these commands until we see a COMMIT
115 Internal aborts are handled by AbortCurrentTransaction, while user aborts are
116 handled by UserAbortTransactionBlock. Both of them rely on AbortTransaction
117 to do all the real work. The only difference is what state we enter after
118 AbortTransaction does its work:
120 * AbortCurrentTransaction leaves us in TBLOCK_ABORT,
121 * UserAbortTransactionBlock leaves us in TBLOCK_ABORT_END
123 Low-level transaction abort handling is divided in two phases:
124 * AbortTransaction executes as soon as we realize the transaction has
125 failed. It should release all shared resources (locks etc) so that we do
126 not delay other backends unnecessarily.
127 * CleanupTransaction executes when we finally see a user COMMIT
128 or ROLLBACK command; it cleans things up and gets us out of the transaction
129 completely. In particular, we mustn't destroy TopTransactionContext until
132 Also, note that when a transaction is committed, we don't close it right away.
133 Rather it's put in TBLOCK_END state, which means that when
134 CommitTransactionCommand is called after the query has finished processing,
135 the transaction has to be closed. The distinction is subtle but important,
136 because it means that control will leave the xact.c code with the transaction
137 open, and the main loop will be able to keep processing inside the same
138 transaction. So, in a sense, transaction commit is also handled in two
139 phases, the first at EndTransactionBlock and the second at
140 CommitTransactionCommand (which is where CommitTransaction is actually
143 The rest of the code in xact.c are routines to support the creation and
144 finishing of transactions and subtransactions. For example, AtStart_Memory
145 takes care of initializing the memory subsystem at main transaction start.
148 Subtransaction Handling
149 -----------------------
151 Subtransactions are implemented using a stack of TransactionState structures,
152 each of which has a pointer to its parent transaction's struct. When a new
153 subtransaction is to be opened, PushTransaction is called, which creates a new
154 TransactionState, with its parent link pointing to the current transaction.
155 StartSubTransaction is in charge of initializing the new TransactionState to
156 sane values, and properly initializing other subsystems (AtSubStart routines).
158 When closing a subtransaction, either CommitSubTransaction has to be called
159 (if the subtransaction is committing), or AbortSubTransaction and
160 CleanupSubTransaction (if it's aborting). In either case, PopTransaction is
161 called so the system returns to the parent transaction.
163 One important point regarding subtransaction handling is that several may need
164 to be closed in response to a single user command. That's because savepoints
165 have names, and we allow to commit or rollback a savepoint by name, which is
166 not necessarily the one that was last opened. Also a COMMIT or ROLLBACK
167 command must be able to close out the entire stack. We handle this by having
168 the utility command subroutine mark all the state stack entries as commit-
169 pending or abort-pending, and then when the main loop reaches
170 CommitTransactionCommand, the real work is done. The main point of doing
171 things this way is that if we get an error while popping state stack entries,
172 the remaining stack entries still show what we need to do to finish up.
174 In the case of ROLLBACK TO <savepoint>, we abort all the subtransactions up
175 through the one identified by the savepoint name, and then re-create that
176 subtransaction level with the same name. So it's a completely new
177 subtransaction as far as the internals are concerned.
179 Other subsystems are allowed to start "internal" subtransactions, which are
180 handled by BeginInternalSubtransaction. This is to allow implementing
181 exception handling, e.g. in PL/pgSQL. ReleaseCurrentSubTransaction and
182 RollbackAndReleaseCurrentSubTransaction allows the subsystem to close said
183 subtransactions. The main difference between this and the savepoint/release
184 path is that we execute the complete state transition immediately in each
185 subroutine, rather than deferring some work until CommitTransactionCommand.
186 Another difference is that BeginInternalSubtransaction is allowed when no
187 explicit transaction block has been established, while DefineSavepoint is not.
190 Transaction and Subtransaction Numbering
191 ----------------------------------------
193 Transactions and subtransactions are assigned permanent XIDs only when/if
194 they first do something that requires one --- typically, insert/update/delete
195 a tuple, though there are a few other places that need an XID assigned.
196 If a subtransaction requires an XID, we always first assign one to its
197 parent. This maintains the invariant that child transactions have XIDs later
198 than their parents, which is assumed in a number of places.
200 The subsidiary actions of obtaining a lock on the XID and entering it into
201 pg_subtrans and PG_PROC are done at the time it is assigned.
203 A transaction that has no XID still needs to be identified for various
204 purposes, notably holding locks. For this purpose we assign a "virtual
205 transaction ID" or VXID to each top-level transaction. VXIDs are formed from
206 two fields, the backendID and a backend-local counter; this arrangement allows
207 assignment of a new VXID at transaction start without any contention for
208 shared memory. To ensure that a VXID isn't re-used too soon after backend
209 exit, we store the last local counter value into shared memory at backend
210 exit, and initialize it from the previous value for the same backendID slot
211 at backend start. All these counters go back to zero at shared memory
212 re-initialization, but that's OK because VXIDs never appear anywhere on-disk.
214 Internally, a backend needs a way to identify subtransactions whether or not
215 they have XIDs; but this need only lasts as long as the parent top transaction
216 endures. Therefore, we have SubTransactionId, which is somewhat like
217 CommandId in that it's generated from a counter that we reset at the start of
218 each top transaction. The top-level transaction itself has SubTransactionId 1,
219 and subtransactions have IDs 2 and up. (Zero is reserved for
220 InvalidSubTransactionId.) Note that subtransactions do not have their
221 own VXIDs; they use the parent top transaction's VXID.
224 Interlocking Transaction Begin, Transaction End, and Snapshots
225 --------------------------------------------------------------
227 We try hard to minimize the amount of overhead and lock contention involved
228 in the frequent activities of beginning/ending a transaction and taking a
229 snapshot. Unfortunately, we must have some interlocking for this, because
230 we must ensure consistency about the commit order of transactions.
231 For example, suppose an UPDATE in xact A is blocked by xact B's prior
232 update of the same row, and xact B is doing commit while xact C gets a
233 snapshot. Xact A can complete and commit as soon as B releases its locks.
234 If xact C's GetSnapshotData sees xact B as still running, then it had
235 better see xact A as still running as well, or it will be able to see two
236 tuple versions - one deleted by xact B and one inserted by xact A. Another
237 reason why this would be bad is that C would see (in the row inserted by A)
238 earlier changes by B, and it would be inconsistent for C not to see any
239 of B's changes elsewhere in the database.
241 Formally, the correctness requirement is "if a snapshot A considers
242 transaction X as committed, and any of transaction X's snapshots considered
243 transaction Y as committed, then snapshot A must consider transaction Y as
246 What we actually enforce is strict serialization of commits and rollbacks
247 with snapshot-taking: we do not allow any transaction to exit the set of
248 running transactions while a snapshot is being taken. (This rule is
249 stronger than necessary for consistency, but is relatively simple to
250 enforce, and it assists with some other issues as explained below.) The
251 implementation of this is that GetSnapshotData takes the ProcArrayLock in
252 shared mode (so that multiple backends can take snapshots in parallel),
253 but ProcArrayEndTransaction must take the ProcArrayLock in exclusive mode
254 while clearing MyPgXact->xid at transaction end (either commit or abort).
255 (To reduce context switching, when multiple transactions commit nearly
256 simultaneously, we have one backend take ProcArrayLock and clear the XIDs
257 of multiple processes at once.)
259 ProcArrayEndTransaction also holds the lock while advancing the shared
260 latestCompletedXid variable. This allows GetSnapshotData to use
261 latestCompletedXid + 1 as xmax for its snapshot: there can be no
262 transaction >= this xid value that the snapshot needs to consider as
265 In short, then, the rule is that no transaction may exit the set of
266 currently-running transactions between the time we fetch latestCompletedXid
267 and the time we finish building our snapshot. However, this restriction
268 only applies to transactions that have an XID --- read-only transactions
269 can end without acquiring ProcArrayLock, since they don't affect anyone
270 else's snapshot nor latestCompletedXid.
272 Transaction start, per se, doesn't have any interlocking with these
273 considerations, since we no longer assign an XID immediately at transaction
274 start. But when we do decide to allocate an XID, GetNewTransactionId must
275 store the new XID into the shared ProcArray before releasing XidGenLock.
276 This ensures that all top-level XIDs <= latestCompletedXid are either
277 present in the ProcArray, or not running anymore. (This guarantee doesn't
278 apply to subtransaction XIDs, because of the possibility that there's not
279 room for them in the subxid array; instead we guarantee that they are
280 present or the overflow flag is set.) If a backend released XidGenLock
281 before storing its XID into MyPgXact, then it would be possible for another
282 backend to allocate and commit a later XID, causing latestCompletedXid to
283 pass the first backend's XID, before that value became visible in the
284 ProcArray. That would break GetOldestXmin, as discussed below.
286 We allow GetNewTransactionId to store the XID into MyPgXact->xid (or the
287 subxid array) without taking ProcArrayLock. This was once necessary to
288 avoid deadlock; while that is no longer the case, it's still beneficial for
289 performance. We are thereby relying on fetch/store of an XID to be atomic,
290 else other backends might see a partially-set XID. This also means that
291 readers of the ProcArray xid fields must be careful to fetch a value only
292 once, rather than assume they can read it multiple times and get the same
293 answer each time. (Use volatile-qualified pointers when doing this, to
294 ensure that the C compiler does exactly what you tell it to.)
296 Another important activity that uses the shared ProcArray is GetOldestXmin,
297 which must determine a lower bound for the oldest xmin of any active MVCC
298 snapshot, system-wide. Each individual backend advertises the smallest
299 xmin of its own snapshots in MyPgXact->xmin, or zero if it currently has no
300 live snapshots (eg, if it's between transactions or hasn't yet set a
301 snapshot for a new transaction). GetOldestXmin takes the MIN() of the
302 valid xmin fields. It does this with only shared lock on ProcArrayLock,
303 which means there is a potential race condition against other backends
304 doing GetSnapshotData concurrently: we must be certain that a concurrent
305 backend that is about to set its xmin does not compute an xmin less than
306 what GetOldestXmin returns. We ensure that by including all the active
307 XIDs into the MIN() calculation, along with the valid xmins. The rule that
308 transactions can't exit without taking exclusive ProcArrayLock ensures that
309 concurrent holders of shared ProcArrayLock will compute the same minimum of
310 currently-active XIDs: no xact, in particular not the oldest, can exit
311 while we hold shared ProcArrayLock. So GetOldestXmin's view of the minimum
312 active XID will be the same as that of any concurrent GetSnapshotData, and
313 so it can't produce an overestimate. If there is no active transaction at
314 all, GetOldestXmin returns latestCompletedXid + 1, which is a lower bound
315 for the xmin that might be computed by concurrent or later GetSnapshotData
316 calls. (We know that no XID less than this could be about to appear in
317 the ProcArray, because of the XidGenLock interlock discussed above.)
319 GetSnapshotData also performs an oldest-xmin calculation (which had better
320 match GetOldestXmin's) and stores that into RecentGlobalXmin, which is used
321 for some tuple age cutoff checks where a fresh call of GetOldestXmin seems
322 too expensive. Note that while it is certain that two concurrent
323 executions of GetSnapshotData will compute the same xmin for their own
324 snapshots, as argued above, it is not certain that they will arrive at the
325 same estimate of RecentGlobalXmin. This is because we allow XID-less
326 transactions to clear their MyPgXact->xmin asynchronously (without taking
327 ProcArrayLock), so one execution might see what had been the oldest xmin,
328 and another not. This is OK since RecentGlobalXmin need only be a valid
329 lower bound. As noted above, we are already assuming that fetch/store
330 of the xid fields is atomic, so assuming it for xmin as well is no extra
334 pg_clog and pg_subtrans
335 -----------------------
337 pg_clog and pg_subtrans are permanent (on-disk) storage of transaction related
338 information. There is a limited number of pages of each kept in memory, so
339 in many cases there is no need to actually read from disk. However, if
340 there's a long running transaction or a backend sitting idle with an open
341 transaction, it may be necessary to be able to read and write this information
342 from disk. They also allow information to be permanent across server restarts.
344 pg_clog records the commit status for each transaction that has been assigned
345 an XID. A transaction can be in progress, committed, aborted, or
346 "sub-committed". This last state means that it's a subtransaction that's no
347 longer running, but its parent has not updated its state yet. It is not
348 necessary to update a subtransaction's transaction status to subcommit, so we
349 can just defer it until main transaction commit. The main role of marking
350 transactions as sub-committed is to provide an atomic commit protocol when
351 transaction status is spread across multiple clog pages. As a result, whenever
352 transaction status spreads across multiple pages we must use a two-phase commit
353 protocol: the first phase is to mark the subtransactions as sub-committed, then
354 we mark the top level transaction and all its subtransactions committed (in
355 that order). Thus, subtransactions that have not aborted appear as in-progress
356 even when they have already finished, and the subcommit status appears as a
357 very short transitory state during main transaction commit. Subtransaction
358 abort is always marked in clog as soon as it occurs. When the transaction
359 status all fit in a single CLOG page, we atomically mark them all as committed
360 without bothering with the intermediate sub-commit state.
362 Savepoints are implemented using subtransactions. A subtransaction is a
363 transaction inside a transaction; its commit or abort status is not only
364 dependent on whether it committed itself, but also whether its parent
365 transaction committed. To implement multiple savepoints in a transaction we
366 allow unlimited transaction nesting depth, so any particular subtransaction's
367 commit state is dependent on the commit status of each and every ancestor
370 The "subtransaction parent" (pg_subtrans) mechanism records, for each
371 transaction with an XID, the TransactionId of its parent transaction. This
372 information is stored as soon as the subtransaction is assigned an XID.
373 Top-level transactions do not have a parent, so they leave their pg_subtrans
374 entries set to the default value of zero (InvalidTransactionId).
376 pg_subtrans is used to check whether the transaction in question is still
377 running --- the main Xid of a transaction is recorded in the PGXACT struct,
378 but since we allow arbitrary nesting of subtransactions, we can't fit all Xids
379 in shared memory, so we have to store them on disk. Note, however, that for
380 each transaction we keep a "cache" of Xids that are known to be part of the
381 transaction tree, so we can skip looking at pg_subtrans unless we know the
382 cache has been overflowed. See storage/ipc/procarray.c for the gory details.
384 slru.c is the supporting mechanism for both pg_clog and pg_subtrans. It
385 implements the LRU policy for in-memory buffer pages. The high-level routines
386 for pg_clog are implemented in transam.c, while the low-level functions are in
387 clog.c. pg_subtrans is contained completely in subtrans.c.
390 Write-Ahead Log Coding
391 ----------------------
393 The WAL subsystem (also called XLOG in the code) exists to guarantee crash
394 recovery. It can also be used to provide point-in-time recovery, as well as
395 hot-standby replication via log shipping. Here are some notes about
396 non-obvious aspects of its design.
398 A basic assumption of a write AHEAD log is that log entries must reach stable
399 storage before the data-page changes they describe. This ensures that
400 replaying the log to its end will bring us to a consistent state where there
401 are no partially-performed transactions. To guarantee this, each data page
402 (either heap or index) is marked with the LSN (log sequence number --- in
403 practice, a WAL file location) of the latest XLOG record affecting the page.
404 Before the bufmgr can write out a dirty page, it must ensure that xlog has
405 been flushed to disk at least up to the page's LSN. This low-level
406 interaction improves performance by not waiting for XLOG I/O until necessary.
407 The LSN check exists only in the shared-buffer manager, not in the local
408 buffer manager used for temp tables; hence operations on temp tables must not
411 During WAL replay, we can check the LSN of a page to detect whether the change
412 recorded by the current log entry is already applied (it has been, if the page
413 LSN is >= the log entry's WAL location).
415 Usually, log entries contain just enough information to redo a single
416 incremental update on a page (or small group of pages). This will work only
417 if the filesystem and hardware implement data page writes as atomic actions,
418 so that a page is never left in a corrupt partly-written state. Since that's
419 often an untenable assumption in practice, we log additional information to
420 allow complete reconstruction of modified pages. The first WAL record
421 affecting a given page after a checkpoint is made to contain a copy of the
422 entire page, and we implement replay by restoring that page copy instead of
423 redoing the update. (This is more reliable than the data storage itself would
424 be because we can check the validity of the WAL record's CRC.) We can detect
425 the "first change after checkpoint" by noting whether the page's old LSN
426 precedes the end of WAL as of the last checkpoint (the RedoRecPtr).
428 The general schema for executing a WAL-logged action is
430 1. Pin and exclusive-lock the shared buffer(s) containing the data page(s)
433 2. START_CRIT_SECTION() (Any error during the next three steps must cause a
434 PANIC because the shared buffers will contain unlogged changes, which we
435 have to ensure don't get to disk. Obviously, you should check conditions
436 such as whether there's enough free space on the page before you start the
439 3. Apply the required changes to the shared buffer(s).
441 4. Mark the shared buffer(s) as dirty with MarkBufferDirty(). (This must
442 happen before the WAL record is inserted; see notes in SyncOneBuffer().)
443 Note that marking a buffer dirty with MarkBufferDirty() should only
444 happen iff you write a WAL record; see Writing Hints below.
446 5. If the relation requires WAL-logging, build a WAL record using
447 XLogBeginInsert and XLogRegister* functions, and insert it. (See
448 "Constructing a WAL record" below). Then update the page's LSN using the
449 returned XLOG location. For instance,
452 XLogRegisterBuffer(...)
453 XLogRegisterData(...)
454 recptr = XLogInsert(rmgr_id, info);
456 PageSetLSN(dp, recptr);
458 6. END_CRIT_SECTION()
460 7. Unlock and unpin the buffer(s).
462 Complex changes (such as a multilevel index insertion) normally need to be
463 described by a series of atomic-action WAL records. The intermediate states
464 must be self-consistent, so that if the replay is interrupted between any
465 two actions, the system is fully functional. In btree indexes, for example,
466 a page split requires a new page to be allocated, and an insertion of a new
467 key in the parent btree level, but for locking reasons this has to be
468 reflected by two separate WAL records. Replaying the first record, to
469 allocate the new page and move tuples to it, sets a flag on the page to
470 indicate that the key has not been inserted to the parent yet. Replaying the
471 second record clears the flag. This intermediate state is never seen by
472 other backends during normal operation, because the lock on the child page
473 is held across the two actions, but will be seen if the operation is
474 interrupted before writing the second WAL record. The search algorithm works
475 with the intermediate state as normal, but if an insertion encounters a page
476 with the incomplete-split flag set, it will finish the interrupted split by
477 inserting the key to the parent, before proceeding.
480 Constructing a WAL record
481 -------------------------
483 A WAL record consists of a header common to all WAL record types,
484 record-specific data, and information about the data blocks modified. Each
485 modified data block is identified by an ID number, and can optionally have
486 more record-specific data associated with the block. If XLogInsert decides
487 that a full-page image of a block needs to be taken, the data associated
488 with that block is not included.
490 The API for constructing a WAL record consists of five functions:
491 XLogBeginInsert, XLogRegisterBuffer, XLogRegisterData, XLogRegisterBufData,
492 and XLogInsert. First, call XLogBeginInsert(). Then register all the buffers
493 modified, and data needed to replay the changes, using XLogRegister*
494 functions. Finally, insert the constructed record to the WAL by calling
499 /* register buffers modified as part of this WAL-logged action */
500 XLogRegisterBuffer(0, lbuffer, REGBUF_STANDARD);
501 XLogRegisterBuffer(1, rbuffer, REGBUF_STANDARD);
503 /* register data that is always included in the WAL record */
504 XLogRegisterData(&xlrec, SizeOfFictionalAction);
507 * register data associated with a buffer. This will not be included
508 * in the record if a full-page image is taken.
510 XLogRegisterBufData(0, tuple->data, tuple->len);
512 /* more data associated with the buffer */
513 XLogRegisterBufData(0, data2, len2);
516 * Ok, all the data and buffers to include in the WAL record have
517 * been registered. Insert the record.
519 recptr = XLogInsert(RM_FOO_ID, XLOG_FOOBAR_DO_STUFF);
521 Details of the API functions:
523 void XLogBeginInsert(void)
525 Must be called before XLogRegisterBuffer and XLogRegisterData.
527 void XLogResetInsertion(void)
529 Clear any currently registered data and buffers from the WAL record
530 construction workspace. This is only needed if you have already called
531 XLogBeginInsert(), but decide to not insert the record after all.
533 void XLogEnsureRecordSpace(int max_block_id, int nrdatas)
535 Normally, the WAL record construction buffers have the following limits:
537 * highest block ID that can be used is 4 (allowing five block references)
538 * Max 20 chunks of registered data
540 These default limits are enough for most record types that change some
541 on-disk structures. For the odd case that requires more data, or needs to
542 modify more buffers, these limits can be raised by calling
543 XLogEnsureRecordSpace(). XLogEnsureRecordSpace() must be called before
544 XLogBeginInsert(), and outside a critical section.
546 void XLogRegisterBuffer(uint8 block_id, Buffer buf, uint8 flags);
548 XLogRegisterBuffer adds information about a data block to the WAL record.
549 block_id is an arbitrary number used to identify this page reference in
550 the redo routine. The information needed to re-find the page at redo -
551 relfilenode, fork, and block number - are included in the WAL record.
553 XLogInsert will automatically include a full copy of the page contents, if
554 this is the first modification of the buffer since the last checkpoint.
555 It is important to register every buffer modified by the action with
556 XLogRegisterBuffer, to avoid torn-page hazards.
558 The flags control when and how the buffer contents are included in the
559 WAL record. Normally, a full-page image is taken only if the page has not
560 been modified since the last checkpoint, and only if full_page_writes=on
561 or an online backup is in progress. The REGBUF_FORCE_IMAGE flag can be
562 used to force a full-page image to always be included; that is useful
563 e.g. for an operation that rewrites most of the page, so that tracking the
564 details is not worth it. For the rare case where it is not necessary to
565 protect from torn pages, REGBUF_NO_IMAGE flag can be used to suppress
566 full page image from being taken. REGBUF_WILL_INIT also suppresses a full
567 page image, but the redo routine must re-generate the page from scratch,
568 without looking at the old page contents. Re-initializing the page
569 protects from torn page hazards like a full page image does.
571 The REGBUF_STANDARD flag can be specified together with the other flags to
572 indicate that the page follows the standard page layout. It causes the
573 area between pd_lower and pd_upper to be left out from the image, reducing
576 If the REGBUF_KEEP_DATA flag is given, any per-buffer data registered with
577 XLogRegisterBufData() is included in the WAL record even if a full-page
580 void XLogRegisterData(char *data, int len);
582 XLogRegisterData is used to include arbitrary data in the WAL record. If
583 XLogRegisterData() is called multiple times, the data are appended, and
584 will be made available to the redo routine as one contiguous chunk.
586 void XLogRegisterBufData(uint8 block_id, char *data, int len);
588 XLogRegisterBufData is used to include data associated with a particular
589 buffer that was registered earlier with XLogRegisterBuffer(). If
590 XLogRegisterBufData() is called multiple times with the same block ID, the
591 data are appended, and will be made available to the redo routine as one
594 If a full-page image of the buffer is taken at insertion, the data is not
595 included in the WAL record, unless the REGBUF_KEEP_DATA flag is used.
598 Writing a REDO routine
599 ----------------------
601 A REDO routine uses the data and page references included in the WAL record
602 to reconstruct the new state of the page. The record decoding functions
603 and macros in xlogreader.c/h can be used to extract the data from the record.
605 When replaying a WAL record that describes changes on multiple pages, you
606 must be careful to lock the pages properly to prevent concurrent Hot Standby
607 queries from seeing an inconsistent state. If this requires that two
608 or more buffer locks be held concurrently, you must lock the pages in
609 appropriate order, and not release the locks until all the changes are done.
611 Note that we must only use PageSetLSN/PageGetLSN() when we know the action
612 is serialised. Only Startup process may modify data blocks during recovery,
613 so Startup process may execute PageGetLSN() without fear of serialisation
614 problems. All other processes must only call PageSet/GetLSN when holding
615 either an exclusive buffer lock or a shared lock plus buffer header lock,
616 or be writing the data block directly rather than through shared buffers
617 while holding AccessExclusiveLock on the relation.
623 In some cases, we write additional information to data blocks without
624 writing a preceding WAL record. This should only happen iff the data can
625 be reconstructed later following a crash and the action is simply a way
626 of optimising for performance. When a hint is written we use
627 MarkBufferDirtyHint() to mark the block dirty.
629 If the buffer is clean and checksums are in use then
630 MarkBufferDirtyHint() inserts an XLOG_HINT record to ensure that we
631 take a full page image that includes the hint. We do this to avoid
632 a partial page write, when we write the dirtied page. WAL is not
633 written during recovery, so we simply skip dirtying blocks because
634 of hints when in recovery.
636 If you do decide to optimise away a WAL record, then any calls to
637 MarkBufferDirty() must be replaced by MarkBufferDirtyHint(),
638 otherwise you will expose the risk of partial page writes.
641 Write-Ahead Logging for Filesystem Actions
642 ------------------------------------------
644 The previous section described how to WAL-log actions that only change page
645 contents within shared buffers. For that type of action it is generally
646 possible to check all likely error cases (such as insufficient space on the
647 page) before beginning to make the actual change. Therefore we can make
648 the change and the creation of the associated WAL log record "atomic" by
649 wrapping them into a critical section --- the odds of failure partway
650 through are low enough that PANIC is acceptable if it does happen.
652 Clearly, that approach doesn't work for cases where there's a significant
653 probability of failure within the action to be logged, such as creation
654 of a new file or database. We don't want to PANIC, and we especially don't
655 want to PANIC after having already written a WAL record that says we did
656 the action --- if we did, replay of the record would probably fail again
657 and PANIC again, making the failure unrecoverable. This means that the
658 ordinary WAL rule of "write WAL before the changes it describes" doesn't
659 work, and we need a different design for such cases.
661 There are several basic types of filesystem actions that have this
662 issue. Here is how we deal with each:
664 1. Adding a disk page to an existing table.
666 This action isn't WAL-logged at all. We extend a table by writing a page
667 of zeroes at its end. We must actually do this write so that we are sure
668 the filesystem has allocated the space. If the write fails we can just
669 error out normally. Once the space is known allocated, we can initialize
670 and fill the page via one or more normal WAL-logged actions. Because it's
671 possible that we crash between extending the file and writing out the WAL
672 entries, we have to treat discovery of an all-zeroes page in a table or
673 index as being a non-error condition. In such cases we can just reclaim
674 the space for re-use.
676 2. Creating a new table, which requires a new file in the filesystem.
678 We try to create the file, and if successful we make a WAL record saying
679 we did it. If not successful, we can just throw an error. Notice that
680 there is a window where we have created the file but not yet written any
681 WAL about it to disk. If we crash during this window, the file remains
682 on disk as an "orphan". It would be possible to clean up such orphans
683 by having database restart search for files that don't have any committed
684 entry in pg_class, but that currently isn't done because of the possibility
685 of deleting data that is useful for forensic analysis of the crash.
686 Orphan files are harmless --- at worst they waste a bit of disk space ---
687 because we check for on-disk collisions when allocating new relfilenode
688 OIDs. So cleaning up isn't really necessary.
690 3. Deleting a table, which requires an unlink() that could fail.
692 Our approach here is to WAL-log the operation first, but to treat failure
693 of the actual unlink() call as a warning rather than error condition.
694 Again, this can leave an orphan file behind, but that's cheap compared to
695 the alternatives. Since we can't actually do the unlink() until after
696 we've committed the DROP TABLE transaction, throwing an error would be out
697 of the question anyway. (It may be worth noting that the WAL entry about
698 the file deletion is actually part of the commit record for the dropping
701 4. Creating and deleting databases and tablespaces, which requires creating
702 and deleting directories and entire directory trees.
704 These cases are handled similarly to creating individual files, ie, we
705 try to do the action first and then write a WAL entry if it succeeded.
706 The potential amount of wasted disk space is rather larger, of course.
707 In the creation case we try to delete the directory tree again if creation
708 fails, so as to reduce the risk of wasted space. Failure partway through
709 a deletion operation results in a corrupt database: the DROP failed, but
710 some of the data is gone anyway. There is little we can do about that,
711 though, and in any case it was presumably data the user no longer wants.
713 In all of these cases, if WAL replay fails to redo the original action
714 we must panic and abort recovery. The DBA will have to manually clean up
715 (for instance, free up some disk space or fix directory permissions) and
716 then restart recovery. This is part of the reason for not writing a WAL
717 entry until we've successfully done the original action.
723 As of PostgreSQL 8.3 it is possible to perform asynchronous commits - i.e.,
724 we don't wait while the WAL record for the commit is fsync'ed.
725 We perform an asynchronous commit when synchronous_commit = off. Instead
726 of performing an XLogFlush() up to the LSN of the commit, we merely note
727 the LSN in shared memory. The backend then continues with other work.
728 We record the LSN only for an asynchronous commit, not an abort; there's
729 never any need to flush an abort record, since the presumption after a
730 crash would be that the transaction aborted anyway.
732 We always force synchronous commit when the transaction is deleting
733 relations, to ensure the commit record is down to disk before the relations
734 are removed from the filesystem. Also, certain utility commands that have
735 non-roll-backable side effects (such as filesystem changes) force sync
736 commit to minimize the window in which the filesystem change has been made
737 but the transaction isn't guaranteed committed.
739 The walwriter regularly wakes up (via wal_writer_delay) or is woken up
740 (via its latch, which is set by backends committing asynchronously) and
741 performs an XLogBackgroundFlush(). This checks the location of the last
742 completely filled WAL page. If that has moved forwards, then we write all
743 the changed buffers up to that point, so that under full load we write
744 only whole buffers. If there has been a break in activity and the current
745 WAL page is the same as before, then we find out the LSN of the most
746 recent asynchronous commit, and write up to that point, if required (i.e.
747 if it's in the current WAL page). If more than wal_writer_delay has
748 passed, or more than wal_writer_flush_after blocks have been written, since
749 the last flush, WAL is also flushed up to the current location. This
750 arrangement in itself would guarantee that an async commit record reaches
751 disk after at most two times wal_writer_delay after the transaction
752 completes. However, we also allow XLogFlush to write/flush full buffers
753 "flexibly" (ie, not wrapping around at the end of the circular WAL buffer
754 area), so as to minimize the number of writes issued under high load when
755 multiple WAL pages are filled per walwriter cycle. This makes the worst-case
756 delay three wal_writer_delay cycles.
758 There are some other subtle points to consider with asynchronous commits.
759 First, for each page of CLOG we must remember the LSN of the latest commit
760 affecting the page, so that we can enforce the same flush-WAL-before-write
761 rule that we do for ordinary relation pages. Otherwise the record of the
762 commit might reach disk before the WAL record does. Again, abort records
763 need not factor into this consideration.
765 In fact, we store more than one LSN for each clog page. This relates to
766 the way we set transaction status hint bits during visibility tests.
767 We must not set a transaction-committed hint bit on a relation page and
768 have that record make it to disk prior to the WAL record of the commit.
769 Since visibility tests are normally made while holding buffer share locks,
770 we do not have the option of changing the page's LSN to guarantee WAL
771 synchronization. Instead, we defer the setting of the hint bit if we have
772 not yet flushed WAL as far as the LSN associated with the transaction.
773 This requires tracking the LSN of each unflushed async commit. It is
774 convenient to associate this data with clog buffers: because we will flush
775 WAL before writing a clog page, we know that we do not need to remember a
776 transaction's LSN longer than the clog page holding its commit status
777 remains in memory. However, the naive approach of storing an LSN for each
778 clog position is unattractive: the LSNs are 32x bigger than the two-bit
779 commit status fields, and so we'd need 256K of additional shared memory for
780 each 8K clog buffer page. We choose instead to store a smaller number of
781 LSNs per page, where each LSN is the highest LSN associated with any
782 transaction commit in a contiguous range of transaction IDs on that page.
783 This saves storage at the price of some possibly-unnecessary delay in
784 setting transaction hint bits.
786 How many transactions should share the same cached LSN (N)? If the
787 system's workload consists only of small async-commit transactions, then
788 it's reasonable to have N similar to the number of transactions per
789 walwriter cycle, since that is the granularity with which transactions will
790 become truly committed (and thus hintable) anyway. The worst case is where
791 a sync-commit xact shares a cached LSN with an async-commit xact that
792 commits a bit later; even though we paid to sync the first xact to disk,
793 we won't be able to hint its outputs until the second xact is sync'd, up to
794 three walwriter cycles later. This argues for keeping N (the group size)
795 as small as possible. For the moment we are setting the group size to 32,
796 which makes the LSN cache space the same size as the actual clog buffer
797 space (independently of BLCKSZ).
799 It is useful that we can run both synchronous and asynchronous commit
800 transactions concurrently, but the safety of this is perhaps not
801 immediately obvious. Assume we have two transactions, T1 and T2. The Log
802 Sequence Number (LSN) is the point in the WAL sequence where a transaction
803 commit is recorded, so LSN1 and LSN2 are the commit records of those
804 transactions. If T2 can see changes made by T1 then when T2 commits it
805 must be true that LSN2 follows LSN1. Thus when T2 commits it is certain
806 that all of the changes made by T1 are also now recorded in the WAL. This
807 is true whether T1 was asynchronous or synchronous. As a result, it is
808 safe for asynchronous commits and synchronous commits to work concurrently
809 without endangering data written by synchronous commits. Sub-transactions
810 are not important here since the final write to disk only occurs at the
811 commit of the top level transaction.
813 Changes to data blocks cannot reach disk unless WAL is flushed up to the
814 point of the LSN of the data blocks. Any attempt to write unsafe data to
815 disk will trigger a write which ensures the safety of all data written by
816 that and prior transactions. Data blocks and clog pages are both protected
819 Changes to a temp table are not WAL-logged, hence could reach disk in
820 advance of T1's commit, but we don't care since temp table contents don't
821 survive crashes anyway.
823 Database writes made via any of the paths we have introduced to avoid WAL
824 overhead for bulk updates are also safe. In these cases it's entirely
825 possible for the data to reach disk before T1's commit, because T1 will
826 fsync it down to disk without any sort of interlock, as soon as it finishes
827 the bulk update. However, all these paths are designed to write data that
828 no other transaction can see until after T1 commits. The situation is thus
829 not different from ordinary WAL-logged updates.
831 Transaction Emulation during Recovery
832 -------------------------------------
834 During Recovery we replay transaction changes in the order they occurred.
835 As part of this replay we emulate some transactional behaviour, so that
836 read only backends can take MVCC snapshots. We do this by maintaining a
837 list of XIDs belonging to transactions that are being replayed, so that
838 each transaction that has recorded WAL records for database writes exist
839 in the array until it commits. Further details are given in comments in
842 Many actions write no WAL records at all, for example read only transactions.
843 These have no effect on MVCC in recovery and we can pretend they never
844 occurred at all. Subtransaction commit does not write a WAL record either
845 and has very little effect, since lock waiters need to wait for the
846 parent transaction to complete.
848 Not all transactional behaviour is emulated, for example we do not insert
849 a transaction entry into the lock table, nor do we maintain the transaction
850 stack in memory. Clog, multixact and commit_ts entries are made normally.
851 Subtrans is maintained during recovery but the details of the transaction
852 tree are ignored and all subtransactions reference the top-level TransactionId
853 directly. Since commit is atomic this provides correct lock wait behaviour
854 yet simplifies emulation of subtransactions considerably.
856 Further details on locking mechanics in recovery are given in comments
857 with the Lock rmgr code.