103 lines
3.9 KiB
Plaintext
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>
|