64.2. Пользовательские менеджеры ресурсов WAL #
В этом разделе описывается интерфейс взаимодействия ядра PostgreSQL с пользовательскими менеджерами ресурсов WAL, используя который расширения могут непосредственно интегрировать свои объекты в WAL.
Расширениям, особенно реализующим табличные методы доступа или индексные методы доступа, может потребоваться использовать WAL для восстановления, репликации и/или логического декодирования.
Чтобы создать новый пользовательский менеджер ресурсов WAL, сначала определите структуру RmgrData с реализациями методов менеджера ресурсов. Подробнее она описывается в src/backend/access/transam/README и в src/include/access/xlog_internal.h в исходном коде PostgreSQL.
/*
* Таблица методов для менеджеров ресурсов.
*
* Эта структура должна синхронизироваться с определением PG_RMGR в
* файле rmgr.c.
*
* Метод rm_identify должен выдать обозначение записи для переданного xl_info
* (без ссылки на rmid). Например, для XLOG_BTREE_VACUUM он мог бы выдать
* "VACUUM". Затем может быть вызван метод rm_desc, который должен выдать
* дополнительные сведения о записи, если они имеются
* (например, последний блок).
*
* Метод rm_mask принимает на вход страницу, изменённую менеджером ресурсов, и
* маскирует биты, на изменение которых не должна реагировать проверка
* wal_consistency_checking.
*
* Индексами в RmgrTable[] являются значения RmgrId (см. rmgrlist.h). Если
* rm_name имеет значение NULL, соответствующая запись RmgrTable считается
* недействительной.
*/
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;Рабочий пример, демонстрирующий использование пользовательских менеджеров ресурсов WAL, можно найти в модуле src/test/modules/test_custom_rmgrs.
Затем зарегистрируйте новый менеджер ресурсов.
/* * Регистрация нового пользовательского менеджера ресурсов WAL. * * Идентификаторы менеджеров ресурсов должны быть глобально уникальными * среди всех расширений. Чтобы избежать конфликтов с расширениями других * разработчиков, зарезервируйте уникальный RmgrId для вашего расширения на * странице https://wiki.postgresql.org/wiki/CustomWALResourceManagers. * В процессе разработки следует использовать RM_EXPERIMENTAL_ID, чтобы * не резервировать лишние идентификаторы. */ extern void RegisterCustomRmgr(RmgrId rmid, const RmgrData *rmgr);
Функция RegisterCustomRmgr должна вызываться из функции _PG_init модуля расширения. В процессе разработки нового расширения в качестве rmid следует использовать RM_EXPERIMENTAL_ID. Когда расширение для пользователей будет готово к выпуску, зарезервируйте новый идентификатор менеджера ресурсов на странице Custom WAL Resource Manager (Пользовательский менеджер ресурсов WAL).
Включите модуль расширения, реализующий пользовательский менеджер ресурсов, в shared_preload_libraries, чтобы он загружался при запуске PostgreSQL.
Примечание
Расширение должно оставаться в shared_preload_libraries до тех пор, пока в системе могут быть какие-либо пользовательские записи WAL. В противном случае сервер PostgreSQL не сможет применять или декодировать пользовательские записи WAL, вследствие чего он может не запуститься.
64.2. Custom WAL Resource Managers #
This section explains the interface between the core PostgreSQL system and custom WAL resource managers, which enable extensions to integrate directly with the WAL.
An extension, especially a Table Access Method or Index Access Method, may need to use WAL for recovery, replication, and/or Logical Decoding.
To create a new custom WAL resource manager, first define an RmgrData structure with implementations for the resource manager methods. Refer to src/backend/access/transam/README and src/include/access/xlog_internal.h in the PostgreSQL source.
/*
* 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;
The src/test/modules/test_custom_rmgrs module contains a working example, which demonstrates usage of custom WAL resource managers.
Then, register your new resource manager.
/* * 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);
RegisterCustomRmgr must be called from the extension module's _PG_init function. While developing a new extension, use RM_EXPERIMENTAL_ID for rmid. When you are ready to release the extension to users, reserve a new resource manager ID at the Custom WAL Resource Manager page.
Place the extension module implementing the custom resource manager in shared_preload_libraries so that it will be loaded early during PostgreSQL startup.
Note
The extension must remain in shared_preload_libraries as long as any custom WAL records may exist in the system. Otherwise PostgreSQL will not be able to apply or decode the custom WAL records, which may prevent the server from starting.