Skip to content

Commit 09d9800

Browse files
robertmhaasrobertmhaas
committed
docs: Consolidate into new "WAL for Extensions" chapter.
Previously, we had consecutive, very short chapters called "Generic WAL" and "Custom WAL Resource Managers," explaining different approaches to the same problem. Merge them into a single chapter. Explain most of the differences between the approaches in the chapter's introductory text, rather than in the individual sections. Discussion: http://postgr.es/m/46ac50c1-6b2a-404f-a683-b67af6ab56e9@eisentraut.org
1 parent 953cf49 commit 09d9800

File tree

5 files changed

+41
-20
lines changed

5 files changed

+41
-20
lines changed

‎doc/src/sgml/custom-rmgr.sgml

+4-7
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
<!-- doc/src/sgml/custom-rmgr.sgml -->
22

3-
<chapter id="custom-rmgr">
3+
<sect1 id="custom-rmgr">
44
<title>Custom WAL Resource Managers</title>
55

66
<para>
7-
This chapter explains the interface between the core
7+
This section explains the interface between the core
88
<productname>PostgreSQL</productname> system and custom WAL resource
99
managers, which enable extensions to integrate directly with the <link
1010
linkend="wal"><acronym>WAL</acronym></link>.
@@ -13,10 +13,7 @@
1313
An extension, especially a <link linkend="tableam">Table Access
1414
Method</link> or <link linkend="indexam">Index Access Method</link>, may
1515
need to use WAL for recovery, replication, and/or <link
16-
linkend="logicaldecoding">Logical Decoding</link>. Custom resource managers
17-
are a more flexible alternative to <link linkend="generic-wal">Generic
18-
WAL</link> (which does not support logical decoding), but more complex for
19-
an extension to implement.
16+
linkend="logicaldecoding">Logical Decoding</link>.
2017
</para>
2118
<para>
2219
To create a new custom WAL resource manager, first define an
@@ -102,4 +99,4 @@ extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
10299
the custom WAL records, which may prevent the server from starting.
103100
</para>
104101
</note>
105-
</chapter>
102+
</sect1>

‎doc/src/sgml/filelist.sgml

+1
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,7 @@
107107
<!ENTITY storage SYSTEM "storage.sgml">
108108
<!ENTITY transaction SYSTEM "xact.sgml">
109109
<!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
110+
<!ENTITY wal-for-extensions SYSTEM "wal-for-extensions.sgml">
110111
<!ENTITY generic-wal SYSTEM "generic-wal.sgml">
111112
<!ENTITY custom-rmgr SYSTEM "custom-rmgr.sgml">
112113
<!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">

‎doc/src/sgml/generic-wal.sgml

+3-11
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,12 @@
11
<!-- doc/src/sgml/generic-wal.sgml -->
22

3-
<chapter id="generic-wal">
3+
<sect1 id="generic-wal">
44
<title>Generic WAL Records</title>
55

66
<para>
77
Although all built-in WAL-logged modules have their own types of WAL
88
records, there is also a generic WAL record type, which describes changes
9-
to pages in a generic way. This is useful for extensions that provide
10-
custom access methods.
11-
</para>
12-
13-
<para>
14-
In comparison with <link linkend="custom-rmgr">Custom WAL Resource
15-
Managers</link>, Generic WAL is simpler for an extension to implement and
16-
does not require the extension library to be loaded in order to apply the
17-
records.
9+
to pages in a generic way.
1810
</para>
1911

2012
<note>
@@ -171,4 +163,4 @@
171163
</listitem>
172164
</itemizedlist>
173165
</para>
174-
</chapter>
166+
</sect1>

‎doc/src/sgml/postgres.sgml

+1-2
Original file line numberDiff line numberDiff line change
@@ -256,8 +256,7 @@ break is not needed in a wider output rendering.
256256
&geqo;
257257
&tableam;
258258
&indexam;
259-
&generic-wal;
260-
&custom-rmgr;
259+
&wal-for-extensions;
261260
&indextypes;
262261
&storage;
263262
&transaction;

‎doc/src/sgml/wal-for-extensions.sgml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
<!-- doc/src/sgml/wal-for-extensions.sgml -->
2+
3+
<chapter id="wal-for-extensions">
4+
<title>Write Ahead Logging for Extensions</title>
5+
6+
<para>
7+
Certain extensions, principally extensions that implement custom access
8+
methods, may need to perform write-ahead logging in order to ensure
9+
crash-safety. <productname>PostgreSQL</productname> provides two ways
10+
for extensions to achieve this goal.
11+
</para>
12+
13+
<para>
14+
First, extensions can choose to use <link linkend="generic-wal">generic
15+
WAL</link>, a special type of WAL record which describes changes to pages
16+
in a generic way. This method is simple to implement and does not require
17+
that an extension library be loaded in order to apply the records. However,
18+
generic WAL records will be ignored when performing logical decoding.
19+
</para>
20+
21+
<para>
22+
Second, extensions can choose to use a <link linkend="custom-rmgr">custom
23+
resource manager</link>. This method is more flexible, supports logical
24+
decoding, and can sometimes generate much smaller write-ahead log records
25+
than would be possible with generic WAL. However, it is more complex for an
26+
extension to implement.
27+
</para>
28+
29+
&generic-wal;
30+
&custom-rmgr;
31+
32+
</chapter>

0 commit comments

Comments
 (0)