codekingpro/portable-devtools

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>Chapter 65. 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="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions" /><link rel="next" href="custom-rmgr.html" title="Chapter 66. 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">Chapter 65. Generic WAL Records</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><th width="60%" align="center">Part VII. Internals</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Next</a></td></tr></table><hr /></div><div class="chapter" id="GENERIC-WAL"><div class="titlepage"><div><div><h2 class="title">Chapter 65. Generic WAL Records</h2></div></div></div><p>3   Although all built-in WAL-logged modules have their own types of WAL4   records, there is also a generic WAL record type, which describes changes5   to pages in a generic way. This is useful for extensions that provide6   custom access methods.7  </p><p>8   In comparison with <a class="link" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Custom WAL Resource9   Managers</a>, Generic WAL is simpler for an extension to implement and10   does not require the extension library to be loaded in order to apply the11   records.12  </p><div class="note"><h3 class="title">Note</h3><p>13    Generic WAL records are ignored during <a class="link" href="logicaldecoding.html" title="Chapter 49. Logical Decoding">Logical Decoding</a>. If logical decoding is14    required for your extension, consider a Custom WAL Resource Manager.15   </p></div><p>16   The API for constructing generic WAL records is defined in17   <code class="filename">access/generic_xlog.h</code> and implemented18   in <code class="filename">access/transam/generic_xlog.c</code>.19  </p><p>20   To perform a WAL-logged data update using the generic WAL record21   facility, follow these steps:22 23   </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>24      <code class="function">state = GenericXLogStart(relation)</code> — start25      construction of a generic WAL record for the given relation.26     </p></li><li class="listitem"><p>27      <code class="function">page = GenericXLogRegisterBuffer(state, buffer, flags)</code>28      — register a buffer to be modified within the current generic WAL29      record.  This function returns a pointer to a temporary copy of the30      buffer's page, where modifications should be made.  (Do not modify the31      buffer's contents directly.)  The third argument is a bit mask of flags32      applicable to the operation.  Currently the only such flag is33      <code class="literal">GENERIC_XLOG_FULL_IMAGE</code>, which indicates that a full-page34      image rather than a delta update should be included in the WAL record.35      Typically this flag would be set if the page is new or has been36      rewritten completely.37      <code class="function">GenericXLogRegisterBuffer</code> can be repeated if the38      WAL-logged action needs to modify multiple pages.39     </p></li><li class="listitem"><p>40      Apply modifications to the page images obtained in the previous step.41     </p></li><li class="listitem"><p>42      <code class="function">GenericXLogFinish(state)</code> — apply the changes to43      the buffers and emit the generic WAL record.44     </p></li></ol></div><p>45  </p><p>46   WAL record construction can be canceled between any of the above steps by47   calling <code class="function">GenericXLogAbort(state)</code>.  This will discard all48   changes to the page image copies.49  </p><p>50   Please note the following points when using the generic WAL record51   facility:52 53   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>54      No direct modifications of buffers are allowed!  All modifications must55      be done in copies acquired from <code class="function">GenericXLogRegisterBuffer()</code>.56      In other words, code that makes generic WAL records should never call57      <code class="function">BufferGetPage()</code> for itself.  However, it remains the58      caller's responsibility to pin/unpin and lock/unlock the buffers at59      appropriate times.  Exclusive lock must be held on each target buffer60      from before <code class="function">GenericXLogRegisterBuffer()</code> until after61      <code class="function">GenericXLogFinish()</code>.62     </p></li><li class="listitem"><p>63      Registrations of buffers (step 2) and modifications of page images64      (step 3) can be mixed freely, i.e., both steps may be repeated in any65      sequence.  Keep in mind that buffers should be registered in the same66      order in which locks are to be obtained on them during replay.67     </p></li><li class="listitem"><p>68      The maximum number of buffers that can be registered for a generic WAL69      record is <code class="literal">MAX_GENERIC_XLOG_PAGES</code>.  An error will be thrown70      if this limit is exceeded.71     </p></li><li class="listitem"><p>72      Generic WAL assumes that the pages to be modified have standard73      layout, and in particular that there is no useful data between74      <code class="structfield">pd_lower</code> and <code class="structfield">pd_upper</code>.75     </p></li><li class="listitem"><p>76      Since you are modifying copies of buffer77      pages, <code class="function">GenericXLogStart()</code> does not start a critical78      section.  Thus, you can safely do memory allocation, error throwing,79      etc. between <code class="function">GenericXLogStart()</code> and80      <code class="function">GenericXLogFinish()</code>.  The only actual critical section is81      present inside <code class="function">GenericXLogFinish()</code>.  There is no need to82      worry about calling  <code class="function">GenericXLogAbort()</code> during an error83      exit, either.84     </p></li><li class="listitem"><p>85      <code class="function">GenericXLogFinish()</code> takes care of marking buffers dirty86      and setting their LSNs.  You do not need to do this explicitly.87     </p></li><li class="listitem"><p>88      For unlogged relations, everything works the same except that no89      actual WAL record is emitted.  Thus, you typically do not need to do90      any explicit checks for unlogged relations.91     </p></li><li class="listitem"><p>92      The generic WAL redo function will acquire exclusive locks to buffers93      in the same order as they were registered.  After redoing all changes,94      the locks will be released in the same order.95     </p></li><li class="listitem"><p>96      If <code class="literal">GENERIC_XLOG_FULL_IMAGE</code> is not specified for a97      registered buffer, the generic WAL record contains a delta between98      the old and the new page images.  This delta is based on byte-by-byte99      comparison.  This is not very compact for the case of moving data100      within a page, and might be improved in the future.101     </p></li></ul></div><p>102  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index-cost-estimation.html" title="64.6. Index Cost Estimation Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="internals.html" title="Part VII. Internals">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="custom-rmgr.html" title="Chapter 66. Custom WAL Resource Managers">Next</a></td></tr><tr><td width="40%" align="left" valign="top">64.6. Index Cost Estimation Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> Chapter 66. Custom WAL Resource Managers</td></tr></table></div></body></html>