doc/src/sgml/generic-wal.sgml

   1 <!-- doc/src/sgml/generic-wal.sgml -->
   2
   3 <sect1 id="generic-wal">
   4  <title>Generic WAL Records</title>
   5
   6   <para>
   7    Although all built-in WAL-logged modules have their own types of WAL
   8    records, there is also a generic WAL record type, which describes changes
   9    to pages in a generic way.
  10   </para>
  11
  12   <note>
  13    <para>
  14     Generic WAL records are ignored during <link
  15     linkend="logicaldecoding">Logical Decoding</link>. If logical decoding is
  16     required for your extension, consider a Custom WAL Resource Manager.
  17    </para>
  18   </note>
  19
  20   <para>
  21    The API for constructing generic WAL records is defined in
  22    <filename>access/generic_xlog.h</filename> and implemented
  23    in <filename>access/transam/generic_xlog.c</filename>.
  24   </para>
  25
  26   <para>
  27    To perform a WAL-logged data update using the generic WAL record
  28    facility, follow these steps:
  29
  30    <orderedlist>
  31     <listitem>
  32      <para>
  33       <function>state = GenericXLogStart(relation)</function> &mdash; start
  34       construction of a generic WAL record for the given relation.
  35      </para>
  36     </listitem>
  37
  38     <listitem>
  39      <para>
  40       <function>page = GenericXLogRegisterBuffer(state, buffer, flags)</function>
  41       &mdash; register a buffer to be modified within the current generic WAL
  42       record.  This function returns a pointer to a temporary copy of the
  43       buffer's page, where modifications should be made.  (Do not modify the
  44       buffer's contents directly.)  The third argument is a bit mask of flags
  45       applicable to the operation.  Currently the only such flag is
  46       <literal>GENERIC_XLOG_FULL_IMAGE</literal>, which indicates that a full-page
  47       image rather than a delta update should be included in the WAL record.
  48       Typically this flag would be set if the page is new or has been
  49       rewritten completely.
  50       <function>GenericXLogRegisterBuffer</function> can be repeated if the
  51       WAL-logged action needs to modify multiple pages.
  52      </para>
  53     </listitem>
  54
  55     <listitem>
  56      <para>
  57       Apply modifications to the page images obtained in the previous step.
  58      </para>
  59     </listitem>
  60
  61     <listitem>
  62      <para>
  63       <function>GenericXLogFinish(state)</function> &mdash; apply the changes to
  64       the buffers and emit the generic WAL record.
  65      </para>
  66     </listitem>
  67    </orderedlist>
  68   </para>
  69
  70   <para>
  71    WAL record construction can be canceled between any of the above steps by
  72    calling <function>GenericXLogAbort(state)</function>.  This will discard all
  73    changes to the page image copies.
  74   </para>
  75
  76   <para>
  77    Please note the following points when using the generic WAL record
  78    facility:
  79
  80    <itemizedlist>
  81     <listitem>
  82      <para>
  83       No direct modifications of buffers are allowed!  All modifications must
  84       be done in copies acquired from <function>GenericXLogRegisterBuffer()</function>.
  85       In other words, code that makes generic WAL records should never call
  86       <function>BufferGetPage()</function> for itself.  However, it remains the
  87       caller's responsibility to pin/unpin and lock/unlock the buffers at
  88       appropriate times.  Exclusive lock must be held on each target buffer
  89       from before <function>GenericXLogRegisterBuffer()</function> until after
  90       <function>GenericXLogFinish()</function>.
  91      </para>
  92     </listitem>
  93
  94     <listitem>
  95      <para>
  96       Registrations of buffers (step 2) and modifications of page images
  97       (step 3) can be mixed freely, i.e., both steps may be repeated in any
  98       sequence.  Keep in mind that buffers should be registered in the same
  99       order in which locks are to be obtained on them during replay.
 100      </para>
 101     </listitem>
 102
 103     <listitem>
 104      <para>
 105       The maximum number of buffers that can be registered for a generic WAL
 106       record is <literal>MAX_GENERIC_XLOG_PAGES</literal>.  An error will be thrown
 107       if this limit is exceeded.
 108      </para>
 109     </listitem>
 110
 111     <listitem>
 112      <para>
 113       Generic WAL assumes that the pages to be modified have standard
 114       layout, and in particular that there is no useful data between
 115       <structfield>pd_lower</structfield> and <structfield>pd_upper</structfield>.
 116      </para>
 117     </listitem>
 118
 119     <listitem>
 120      <para>
 121       Since you are modifying copies of buffer
 122       pages, <function>GenericXLogStart()</function> does not start a critical
 123       section.  Thus, you can safely do memory allocation, error throwing,
 124       etc. between <function>GenericXLogStart()</function> and
 125       <function>GenericXLogFinish()</function>.  The only actual critical section is
 126       present inside <function>GenericXLogFinish()</function>.  There is no need to
 127       worry about calling  <function>GenericXLogAbort()</function> during an error
 128       exit, either.
 129      </para>
 130     </listitem>
 131
 132     <listitem>
 133      <para>
 134       <function>GenericXLogFinish()</function> takes care of marking buffers dirty
 135       and setting their LSNs.  You do not need to do this explicitly.
 136      </para>
 137     </listitem>
 138
 139     <listitem>
 140      <para>
 141       For unlogged relations, everything works the same except that no
 142       actual WAL record is emitted.  Thus, you typically do not need to do
 143       any explicit checks for unlogged relations.
 144      </para>
 145     </listitem>
 146
 147     <listitem>
 148      <para>
 149       The generic WAL redo function will acquire exclusive locks to buffers
 150       in the same order as they were registered.  After redoing all changes,
 151       the locks will be released in the same order.
 152      </para>
 153     </listitem>
 154
 155     <listitem>
 156      <para>
 157       If <literal>GENERIC_XLOG_FULL_IMAGE</literal> is not specified for a
 158       registered buffer, the generic WAL record contains a delta between
 159       the old and the new page images.  This delta is based on byte-by-byte
 160       comparison.  This is not very compact for the case of moving data
 161       within a page, and might be improved in the future.
 162      </para>
 163     </listitem>
 164    </itemizedlist>
 165   </para>
 166 </sect1>