| 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> — 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 |
— 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> — 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> |