1
0
mirror of https://github.com/postgres/postgres.git synced 2025-08-28 18:48:04 +03:00
Files
postgres/doc/src/sgml/custom-rmgr.sgml
Robert Haas 09d9800e52 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
2024-04-15 15:57:13 -04:00

103 lines
3.9 KiB
Plaintext

<!-- doc/src/sgml/custom-rmgr.sgml -->
<sect1 id="custom-rmgr">
<title>Custom WAL Resource Managers</title>
<para>
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>.
</para>
<para>
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>.
</para>
<para>
To create a new custom WAL resource manager, first define an
<structname>RmgrData</structname> structure with implementations for the
resource manager methods. Refer to
<filename>src/backend/access/transam/README</filename> and
<filename>src/include/access/xlog_internal.h</filename> in the
<productname>PostgreSQL</productname> source.
<programlisting>
/*
* Method table for resource managers.
*
* This struct must be kept in sync with the PG_RMGR definition in
* rmgr.c.
*
* rm_identify must return a name for the record based on xl_info (without
* reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
* "VACUUM". rm_desc can then be called to obtain additional detail for the
* record, if available (e.g. the last block).
*
* rm_mask takes as input a page modified by the resource manager and masks
* out bits that shouldn't be flagged by wal_consistency_checking.
*
* RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
* NULL, the corresponding RmgrTable entry is considered invalid.
*/
typedef struct RmgrData
{
const char *rm_name;
void (*rm_redo) (XLogReaderState *record);
void (*rm_desc) (StringInfo buf, XLogReaderState *record);
const char *(*rm_identify) (uint8 info);
void (*rm_startup) (void);
void (*rm_cleanup) (void);
void (*rm_mask) (char *pagedata, BlockNumber blkno);
void (*rm_decode) (struct LogicalDecodingContext *ctx,
struct XLogRecordBuffer *buf);
} RmgrData;
</programlisting>
</para>
<para>
The <filename>src/test/modules/test_custom_rmgrs</filename> module
contains a working example, which demonstrates usage of custom WAL
resource managers.
</para>
<para>
Then, register your new resource
manager.
<programlisting>
/*
* Register a new custom WAL resource manager.
*
* Resource manager IDs must be globally unique across all extensions. Refer
* to https://wiki.postgresql.org/wiki/CustomWALResourceManagers to reserve a
* unique RmgrId for your extension, to avoid conflicts with other extension
* developers. During development, use RM_EXPERIMENTAL_ID to avoid needlessly
* reserving a new ID.
*/
extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
</programlisting>
<function>RegisterCustomRmgr</function> must be called from the
extension module's <link linkend="xfunc-c-dynload">_PG_init</link> function.
While developing a new extension, use <literal>RM_EXPERIMENTAL_ID</literal>
for <parameter>rmid</parameter>. When you are ready to release the extension
to users, reserve a new resource manager ID at the <ulink
url="https://wiki.postgresql.org/wiki/CustomWALResourceManagers">Custom WAL
Resource Manager</ulink> page.
</para>
<para>
Place the extension module implementing the custom resource manager in <xref
linkend="guc-shared-preload-libraries"/> so that it will be loaded early
during <productname>PostgreSQL</productname> startup.
</para>
<note>
<para>
The extension must remain in <varname>shared_preload_libraries</varname>
as long as any custom WAL records may exist in the system. Otherwise
<productname>PostgreSQL</productname> will not be able to apply or decode
the custom WAL records, which may prevent the server from starting.
</para>
</note>
</sect1>