<!-- doc/src/sgml/generic-wal.sgml -->

<sect1 id="generic-wal">
 <title>Generic WAL Records</title>

  <para>
   Although all built-in WAL-logged modules have their own types of WAL
   records, there is also a generic WAL record type, which describes changes
   to pages in a generic way.
  </para>

  <note>
   <para>
    Generic WAL records are ignored during <link
    linkend="logicaldecoding">Logical Decoding</link>. If logical decoding is
    required for your extension, consider a Custom WAL Resource Manager.
   </para>
  </note>

  <para>
   The API for constructing generic WAL records is defined in
   <filename>access/generic_xlog.h</filename> and implemented
   in <filename>access/transam/generic_xlog.c</filename>.
  </para>

  <para>
   To perform a WAL-logged data update using the generic WAL record
   facility, follow these steps:

   <orderedlist>
    <listitem>
     <para>
      <function>state = GenericXLogStart(relation)</function> &mdash; start
      construction of a generic WAL record for the given relation.
     </para>
    </listitem>

    <listitem>
     <para>
      <function>page = GenericXLogRegisterBuffer(state, buffer, flags)</function>
      &mdash; register a buffer to be modified within the current generic WAL
      record.  This function returns a pointer to a temporary copy of the
      buffer's page, where modifications should be made.  (Do not modify the
      buffer's contents directly.)  The third argument is a bit mask of flags
      applicable to the operation.  Currently the only such flag is
      <literal>GENERIC_XLOG_FULL_IMAGE</literal>, which indicates that a full-page
      image rather than a delta update should be included in the WAL record.
      Typically this flag would be set if the page is new or has been
      rewritten completely.
      <function>GenericXLogRegisterBuffer</function> can be repeated if the
      WAL-logged action needs to modify multiple pages.
     </para>
    </listitem>

    <listitem>
     <para>
      Apply modifications to the page images obtained in the previous step.
     </para>
    </listitem>

    <listitem>
     <para>
      <function>GenericXLogFinish(state)</function> &mdash; apply the changes to
      the buffers and emit the generic WAL record.
     </para>
    </listitem>
   </orderedlist>
  </para>

  <para>
   WAL record construction can be canceled between any of the above steps by
   calling <function>GenericXLogAbort(state)</function>.  This will discard all
   changes to the page image copies.
  </para>

  <para>
   Please note the following points when using the generic WAL record
   facility:

   <itemizedlist>
    <listitem>
     <para>
      No direct modifications of buffers are allowed!  All modifications must
      be done in copies acquired from <function>GenericXLogRegisterBuffer()</function>.
      In other words, code that makes generic WAL records should never call
      <function>BufferGetPage()</function> for itself.  However,