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

diff --git a/doc/src/sgml/custom-rmgr.sgml b/doc/src/sgml/custom-rmgr.sgml
index 0d982292951ea5b577d2b1f33cc6553314688ad3..3032b2dc0d2dfc142a1cef138ff3240ae461a9b6 100644 (file)
--- a/doc/src/sgml/custom-rmgr.sgml
+++ b/doc/src/sgml/custom-rmgr.sgml
@@ -1,10 +1,10 @@
 <!-- doc/src/sgml/custom-rmgr.sgml -->
 
-<chapter id="custom-rmgr">
+<sect1 id="custom-rmgr">
  <title>Custom WAL Resource Managers</title>
 
  <para>
-  This chapter explains the interface between the core
+  This section explains the interface between the core
   <productname>PostgreSQL</productname> system and custom WAL resource
   managers, which enable extensions to integrate directly with the <link
   linkend="wal"><acronym>WAL</acronym></link>.
@@ -13,10 +13,7 @@
   An extension, especially a <link linkend="tableam">Table Access
   Method</link> or <link linkend="indexam">Index Access Method</link>, may
   need to use WAL for recovery, replication, and/or <link
-  linkend="logicaldecoding">Logical Decoding</link>. Custom resource managers
-  are a more flexible alternative to <link linkend="generic-wal">Generic
-  WAL</link> (which does not support logical decoding), but more complex for
-  an extension to implement.
+  linkend="logicaldecoding">Logical Decoding</link>.
  </para>
  <para>
   To create a new custom WAL resource manager, first define an
@@ -102,4 +99,4 @@ extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
     the custom WAL records, which may prevent the server from starting.
    </para>
  </note>
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 3fb0709f5dfc868f240aa08be9bda6d4815da9bd..38ec362d8f469867e5d9bc6b6111675868ce9c97 100644 (file)
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -107,6 +107,7 @@
 <!ENTITY storage    SYSTEM "storage.sgml">
 <!ENTITY transaction     SYSTEM "xact.sgml">
 <!ENTITY tablesample-method SYSTEM "tablesample-method.sgml">
+<!ENTITY wal-for-extensions SYSTEM "wal-for-extensions.sgml">
 <!ENTITY generic-wal SYSTEM "generic-wal.sgml">
 <!ENTITY custom-rmgr SYSTEM "custom-rmgr.sgml">
 <!ENTITY backup-manifest SYSTEM "backup-manifest.sgml">

diff --git a/doc/src/sgml/generic-wal.sgml b/doc/src/sgml/generic-wal.sgml
index a028856d2eb5a22fcf0c2857a3089ea64f085cf6..41f97ad7dc8467c41bf8a29a6ebb3cad966a1f7a 100644 (file)
--- a/doc/src/sgml/generic-wal.sgml
+++ b/doc/src/sgml/generic-wal.sgml
@@ -1,20 +1,12 @@
 <!-- doc/src/sgml/generic-wal.sgml -->
 
-<chapter id="generic-wal">
+<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. This is useful for extensions that provide
-   custom access methods.
-  </para>
-
-  <para>
-   In comparison with <link linkend="custom-rmgr">Custom WAL Resource
-   Managers</link>, Generic WAL is simpler for an extension to implement and
-   does not require the extension library to be loaded in order to apply the
-   records.
+   to pages in a generic way.
   </para>
 
   <note>
@@ -171,4 +163,4 @@
     </listitem>
    </itemizedlist>
   </para>
-</chapter>
+</sect1>

diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml
index e9a350234e7a5fc26433613525962d33a4f9a894..ec9f90e283e5f15ac802ea4c81e88ceec12340de 100644 (file)
--- a/doc/src/sgml/postgres.sgml
+++ b/doc/src/sgml/postgres.sgml
@@ -256,8 +256,7 @@ break is not needed in a wider output rendering.
   &geqo;
   &tableam;
   &indexam;
-  &generic-wal;
-  &custom-rmgr;
+  &wal-for-extensions;
   &indextypes;
   &storage;
   &transaction;

diff --git a/doc/src/sgml/wal-for-extensions.sgml b/doc/src/sgml/wal-for-extensions.sgml
new file mode 100644 (file)
index 0000000..4c4fb29
--- /dev/null
+++ b/doc/src/sgml/wal-for-extensions.sgml
@@ -0,0 +1,32 @@
+<!-- doc/src/sgml/wal-for-extensions.sgml -->
+
+<chapter id="wal-for-extensions">
+ <title>Write Ahead Logging for Extensions</title>
+
+  <para>
+   Certain extensions, principally extensions that implement custom access
+   methods, may need to perform write-ahead logging in order to ensure
+   crash-safety. <productname>PostgreSQL</productname> provides two ways
+   for extensions to achieve this goal.
+  </para>
+
+  <para>
+   First, extensions can choose to use <link linkend="generic-wal">generic
+   WAL</link>, a special type of WAL record which describes changes to pages
+   in a generic way. This method is simple to implement and does not require
+   that an extension library be loaded in order to apply the records. However,
+   generic WAL records will be ignored when performing logical decoding.
+  </para>
+
+  <para>
+   Second, extensions can choose to use a <link linkend="custom-rmgr">custom
+   resource manager</link>. This method is more flexible, supports logical
+   decoding, and can sometimes generate much smaller write-ahead log records
+   than would be possible with generic WAL. However, it is more complex for an
+   extension to implement.
+  </para>
+
+&generic-wal;
+&custom-rmgr;
+
+</chapter>