begriffs open source - ai-pg/blob - full-docs/src/sgml/html/generic-wal.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>64.1. Generic WAL Records</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="wal-for-extensions.html" title="Chapter 64. Write Ahead Logging for Extensions" /><link rel="next" href="custom-rmgr.html" title="64.2. Custom WAL Resource Managers" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">64.1. Generic WAL Records</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="wal-for-extensions.html" title="Chapter 64. Write Ahead Logging for Extensions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="wal-for-extensions.html" title="Chapter 64. Write Ahead Logging for Extensions">Up</a></td><th width="60%" align="center">Chapter 64. Write Ahead Logging for Extensions</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="64.2. Custom WAL Resource Managers">Next</a></td></tr></table><hr /></div><div class="sect1" id="GENERIC-WAL"><div class="titlepage"><div><div><h2 class="title" style="clear: both">64.1. Generic WAL Records <a href="#GENERIC-WAL" class="id_link">#</a></h2></div></div></div><p>
   3    Although all built-in WAL-logged modules have their own types of WAL
   4    records, there is also a generic WAL record type, which describes changes
   5    to pages in a generic way.
   6   </p><div class="note"><h3 class="title">Note</h3><p>
   7     Generic WAL records are ignored during <a class="link" href="logicaldecoding.html" title="Chapter 47. Logical Decoding">Logical Decoding</a>. If logical decoding is
   8     required for your extension, consider a Custom WAL Resource Manager.
   9    </p></div><p>
  10    The API for constructing generic WAL records is defined in
  11    <code class="filename">access/generic_xlog.h</code> and implemented
  12    in <code class="filename">access/transam/generic_xlog.c</code>.
  13   </p><p>
  14    To perform a WAL-logged data update using the generic WAL record
  15    facility, follow these steps:
  16
  17    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
  18       <code class="function">state = GenericXLogStart(relation)</code> — start
  19       construction of a generic WAL record for the given relation.
  20      </p></li><li class="listitem"><p>
  21       <code class="function">page = GenericXLogRegisterBuffer(state, buffer, flags)</code>
  22       — register a buffer to be modified within the current generic WAL
  23       record.  This function returns a pointer to a temporary copy of the
  24       buffer's page, where modifications should be made.  (Do not modify the
  25       buffer's contents directly.)  The third argument is a bit mask of flags
  26       applicable to the operation.  Currently the only such flag is
  27       <code class="literal">GENERIC_XLOG_FULL_IMAGE</code>, which indicates that a full-page
  28       image rather than a delta update should be included in the WAL record.
  29       Typically this flag would be set if the page is new or has been
  30       rewritten completely.
  31       <code class="function">GenericXLogRegisterBuffer</code> can be repeated if the
  32       WAL-logged action needs to modify multiple pages.
  33      </p></li><li class="listitem"><p>
  34       Apply modifications to the page images obtained in the previous step.
  35      </p></li><li class="listitem"><p>
  36       <code class="function">GenericXLogFinish(state)</code> — apply the changes to
  37       the buffers and emit the generic WAL record.
  38      </p></li></ol></div><p>
  39   </p><p>
  40    WAL record construction can be canceled between any of the above steps by
  41    calling <code class="function">GenericXLogAbort(state)</code>.  This will discard all
  42    changes to the page image copies.
  43   </p><p>
  44    Please note the following points when using the generic WAL record
  45    facility:
  46
  47    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  48       No direct modifications of buffers are allowed!  All modifications must
  49       be done in copies acquired from <code class="function">GenericXLogRegisterBuffer()</code>.
  50       In other words, code that makes generic WAL records should never call
  51       <code class="function">BufferGetPage()</code> for itself.  However, it remains the
  52       caller's responsibility to pin/unpin and lock/unlock the buffers at
  53       appropriate times.  Exclusive lock must be held on each target buffer
  54       from before <code class="function">GenericXLogRegisterBuffer()</code> until after
  55       <code class="function">GenericXLogFinish()</code>.
  56      </p></li><li class="listitem"><p>
  57       Registrations of buffers (step 2) and modifications of page images
  58       (step 3) can be mixed freely, i.e., both steps may be repeated in any
  59       sequence.  Keep in mind that buffers should be registered in the same
  60       order in which locks are to be obtained on them during replay.
  61      </p></li><li class="listitem"><p>
  62       The maximum number of buffers that can be registered for a generic WAL
  63       record is <code class="literal">MAX_GENERIC_XLOG_PAGES</code>.  An error will be thrown
  64       if this limit is exceeded.
  65      </p></li><li class="listitem"><p>
  66       Generic WAL assumes that the pages to be modified have standard
  67       layout, and in particular that there is no useful data between
  68       <code class="structfield">pd_lower</code> and <code class="structfield">pd_upper</code>.
  69      </p></li><li class="listitem"><p>
  70       Since you are modifying copies of buffer
  71       pages, <code class="function">GenericXLogStart()</code> does not start a critical
  72       section.  Thus, you can safely do memory allocation, error throwing,
  73       etc. between <code class="function">GenericXLogStart()</code> and
  74       <code class="function">GenericXLogFinish()</code>.  The only actual critical section is
  75       present inside <code class="function">GenericXLogFinish()</code>.  There is no need to
  76       worry about calling  <code class="function">GenericXLogAbort()</code> during an error
  77       exit, either.
  78      </p></li><li class="listitem"><p>
  79       <code class="function">GenericXLogFinish()</code> takes care of marking buffers dirty
  80       and setting their LSNs.  You do not need to do this explicitly.
  81      </p></li><li class="listitem"><p>
  82       For unlogged relations, everything works the same except that no
  83       actual WAL record is emitted.  Thus, you typically do not need to do
  84       any explicit checks for unlogged relations.
  85      </p></li><li class="listitem"><p>
  86       The generic WAL redo function will acquire exclusive locks to buffers
  87       in the same order as they were registered.  After redoing all changes,
  88       the locks will be released in the same order.
  89      </p></li><li class="listitem"><p>
  90       If <code class="literal">GENERIC_XLOG_FULL_IMAGE</code> is not specified for a
  91       registered buffer, the generic WAL record contains a delta between
  92       the old and the new page images.  This delta is based on byte-by-byte
  93       comparison.  This is not very compact for the case of moving data
  94       within a page, and might be improved in the future.
  95      </p></li></ul></div><p>
  96   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="wal-for-extensions.html" title="Chapter 64. Write Ahead Logging for Extensions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="wal-for-extensions.html" title="Chapter 64. Write Ahead Logging for Extensions">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="64.2. Custom WAL Resource Managers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 64. Write Ahead Logging for Extensions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 64.2. Custom WAL Resource Managers</td></tr></table></div></body></html>