begriffs open source - ai-pg/blob - full-docs/txt/custom-rmgr.txt

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