doc/src/sgml/custom-rmgr.sgml

   1 <!-- doc/src/sgml/custom-rmgr.sgml -->
   2
   3 <sect1 id="custom-rmgr">
   4  <title>Custom WAL Resource Managers</title>
   5
   6  <para>
   7   This section explains the interface between the core
   8   <productname>PostgreSQL</productname> system and custom WAL resource
   9   managers, which enable extensions to integrate directly with the <link
  10   linkend="wal"><acronym>WAL</acronym></link>.
  11  </para>
  12  <para>
  13   An extension, especially a <link linkend="tableam">Table Access
  14   Method</link> or <link linkend="indexam">Index Access Method</link>, may
  15   need to use WAL for recovery, replication, and/or <link
  16   linkend="logicaldecoding">Logical Decoding</link>.
  17  </para>
  18  <para>
  19   To create a new custom WAL resource manager, first define an
  20   <structname>RmgrData</structname> structure with implementations for the
  21   resource manager methods. Refer to
  22   <filename>src/backend/access/transam/README</filename> and
  23   <filename>src/include/access/xlog_internal.h</filename> in the
  24   <productname>PostgreSQL</productname> source.
  25 <programlisting>
  26 /*
  27  * Method table for resource managers.
  28  *
  29  * This struct must be kept in sync with the PG_RMGR definition in
  30  * rmgr.c.
  31  *
  32  * rm_identify must return a name for the record based on xl_info (without
  33  * reference to the rmid). For example, XLOG_BTREE_VACUUM would be named
  34  * "VACUUM". rm_desc can then be called to obtain additional detail for the
  35  * record, if available (e.g. the last block).
  36  *
  37  * rm_mask takes as input a page modified by the resource manager and masks
  38  * out bits that shouldn't be flagged by wal_consistency_checking.
  39  *
  40  * RmgrTable[] is indexed by RmgrId values (see rmgrlist.h). If rm_name is
  41  * NULL, the corresponding RmgrTable entry is considered invalid.
  42  */
  43 typedef struct RmgrData
  44 {
  45     const char *rm_name;
  46     void        (*rm_redo) (XLogReaderState *record);
  47     void        (*rm_desc) (StringInfo buf, XLogReaderState *record);
  48     const char *(*rm_identify) (uint8 info);
  49     void        (*rm_startup) (void);
  50     void        (*rm_cleanup) (void);
  51     void        (*rm_mask) (char *pagedata, BlockNumber blkno);
  52     void        (*rm_decode) (struct LogicalDecodingContext *ctx,
  53                               struct XLogRecordBuffer *buf);
  54 } RmgrData;
  55 </programlisting>
  56  </para>
  57
  58   <para>
  59    The <filename>src/test/modules/test_custom_rmgrs</filename> module
  60    contains a working example, which demonstrates usage of custom WAL
  61    resource managers.
  62   </para>
  63
  64  <para>
  65   Then, register your new resource
  66   manager.
  67
  68 <programlisting>
  69 /*
  70  * Register a new custom WAL resource manager.
  71  *
  72  * Resource manager IDs must be globally unique across all extensions. Refer
  73  * to https://wiki.postgresql.org/wiki/CustomWALResourceManagers to reserve a
  74  * unique RmgrId for your extension, to avoid conflicts with other extension
  75  * developers. During development, use RM_EXPERIMENTAL_ID to avoid needlessly
  76  * reserving a new ID.
  77  */
  78 extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
  79 </programlisting>
  80   <function>RegisterCustomRmgr</function> must be called from the
  81   extension module's <link linkend="xfunc-c-dynload">_PG_init</link> function.
  82   While developing a new extension, use <literal>RM_EXPERIMENTAL_ID</literal>
  83   for <parameter>rmid</parameter>. When you are ready to release the extension
  84   to users, reserve a new resource manager ID at the <ulink
  85   url="https://wiki.postgresql.org/wiki/CustomWALResourceManagers">Custom WAL
  86   Resource Manager</ulink> page.
  87  </para>
  88
  89  <para>
  90   Place the extension module implementing the custom resource manager in <xref
  91   linkend="guc-shared-preload-libraries"/> so that it will be loaded early
  92   during <productname>PostgreSQL</productname> startup.
  93  </para>
  94  <note>
  95    <para>
  96     The extension must remain in <varname>shared_preload_libraries</varname>
  97     as long as any custom WAL records may exist in the system. Otherwise
  98     <productname>PostgreSQL</productname> will not be able to apply or decode
  99     the custom WAL records, which may prevent the server from starting.
 100    </para>
 101  </note>
 102 </sect1>