Home • Explore • Blog • CI
☰



postgresql
2nd chunk of `doc/src/sgml/custom-rmgr.sgml`
4551bd2a6b9bc972cc31d672604d53968fe0d8805b2405050000000100000bce

<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>
Title: Registering and Using a Custom WAL Resource Manager
Summary
The text provides the C structure definition of `RmgrData`, which defines the function pointers for a custom resource manager. It then describes the process of registering a custom WAL resource manager using the `RegisterCustomRmgr` function, which must be called during the extension module's `_PG_init` function. It emphasizes the importance of using a unique RmgrId and reserving one when the extension is ready for release. It also notes that the extension must be loaded via shared_preload_libraries to handle custom WAL records during startup.