From 8a57b79219e2c400532af11046400814816de391 Mon Sep 17 00:00:00 2001 From: Robert Haas Date: Mon, 1 Apr 2024 11:25:29 -0400 Subject: [PATCH v3] 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. Per discussion, don't consolidate all of the SGML into a single file; instead, each has its own file, and there's an additional one for the chapter as a whole. --- doc/src/sgml/custom-rmgr.sgml | 11 ++++------ doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/generic-wal.sgml | 14 +++--------- doc/src/sgml/postgres.sgml | 3 +-- doc/src/sgml/wal-for-extensions.sgml | 32 ++++++++++++++++++++++++++++ 5 files changed, 41 insertions(+), 20 deletions(-) create mode 100644 doc/src/sgml/wal-for-extensions.sgml diff --git a/doc/src/sgml/custom-rmgr.sgml b/doc/src/sgml/custom-rmgr.sgml index 0d98229295..3032b2dc0d 100644 --- a/doc/src/sgml/custom-rmgr.sgml +++ b/doc/src/sgml/custom-rmgr.sgml @@ -1,10 +1,10 @@ - + Custom WAL Resource Managers - This chapter explains the interface between the core + This section explains the interface between the core PostgreSQL system and custom WAL resource managers, which enable extensions to integrate directly with the WAL. @@ -13,10 +13,7 @@ An extension, especially a Table Access Method or Index Access Method, may need to use WAL for recovery, replication, and/or Logical Decoding. Custom resource managers - are a more flexible alternative to Generic - WAL (which does not support logical decoding), but more complex for - an extension to implement. + linkend="logicaldecoding">Logical Decoding. 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. - + diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 3fb0709f5d..38ec362d8f 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -107,6 +107,7 @@ + diff --git a/doc/src/sgml/generic-wal.sgml b/doc/src/sgml/generic-wal.sgml index a028856d2e..41f97ad7dc 100644 --- a/doc/src/sgml/generic-wal.sgml +++ b/doc/src/sgml/generic-wal.sgml @@ -1,20 +1,12 @@ - + Generic WAL Records 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. - - - - In comparison with Custom WAL Resource - Managers, 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. @@ -171,4 +163,4 @@ - + diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index e9a350234e..ec9f90e283 100644 --- 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 index 0000000000..4c4fb29dd1 --- /dev/null +++ b/doc/src/sgml/wal-for-extensions.sgml @@ -0,0 +1,32 @@ + + + + Write Ahead Logging for Extensions + + + Certain extensions, principally extensions that implement custom access + methods, may need to perform write-ahead logging in order to ensure + crash-safety. PostgreSQL provides two ways + for extensions to achieve this goal. + + + + First, extensions can choose to use generic + WAL, 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. + + + + Second, extensions can choose to use a custom + resource manager. 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. + + +&generic-wal; +&custom-rmgr; + + -- 2.39.3 (Apple Git-145)