| 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> |