Модули архивирования

QHB предоставляет инфраструктуру для создания пользовательских модулей для непрерывного архивирования (см. раздел Непрерывное архивирование и восстановление на момент времени (PITR)). Хотя архивировать с помощью команды оболочки (т. е. archive_command) гораздо проще, пользовательский модуль архивирования зачастую будет гораздо более производительным и устойчивым к ошибкам.

Если задать в параметре archive_library сконфигурированную библиотеку архивирования пользовательского модуля, QHB будет передавать завершенные файлы WAL этому модулю, а сервер будет избегать повторного использования или удаления этих файлов WAL до тех пор, пока модуль не просигнализирует, что файлы были успешно заархивированы. По большому счету модуль сам решает, что делать с каждым файлом WAL, но многие рекомендации перечислены в подразделе Настройка архивирования WAL.

Модули архивирования должны состоять как минимум из функции инициализации (см. раздел Функции инициализации) и требуемых функций обратного вызова (см. раздел Функции обратного вызова модулей архивирования). Тем не менее модулям архивирования разрешено также делать гораздо большее (например, объявлять GUC (Global User Configuration, серверные конфигурационные параметры) и регистрировать фоновые рабочие процессы).

В модуле basic_archive содержится рабочий пример, демонстрирующий некоторые полезные технические решения.

Функции инициализации

Библиотека архивирования загружается путем динамической загрузки разделяемой библиотеки с базовым именем, указанным в archive_library. Для нахождения библиотеки используется обычный путь поиска библиотек. Чтобы предоставить необходимые функции обратного вызова модуля архивирования и показать, что библиотека в действительности является модулем архивирования, она должна предоставить функцию с именем _PG_archive_module_init. Результатом этой функции должен быть указатель на структуру типа ArchiveModuleCallbacks, содержащую все, что нужно знать коду ядра, чтобы использовать этот модуль архивирования. У возвращаемого значения время существования должно быть такое же, как и у сервера, что обычно достигается путем его определения как переменной static const в глобальном масштабе.

typedef struct ArchiveModuleCallbacks
{
    ArchiveStartupCB startup_cb;
    ArchiveCheckConfiguredCB check_configured_cb;
    ArchiveFileCB archive_file_cb;
    ArchiveShutdownCB shutdown_cb;
} ArchiveModuleCallbacks;
typedef const ArchiveModuleCallbacks *(*ArchiveModuleInit) (void);

Обязательной является только функция обратного вызова archive_file_cb. Остальные функции необязательны.

Функции обратного вызова модулей архивирования

Функции обратного вызова архивирования определяют фактическое поведение модуля при архивировании. Сервер будет вызывать их по мере надобности для обработки каждого отдельного файла WAL.

Функция обратного вызова для запуска

Функция обратного вызова startup_cb вызывается вскоре после загрузки модуля. Эту функцию можно использовать для выполнения любой требуемой дополнительной инициализации. Если имеется какая-либо информация о состоянии модуля архивирования, эта функция может использовать для их хранения state->private_data.

typedef void (*ArchiveStartupCB) (ArchiveModuleState *state);

Функция обратного вызова для проверки

Функция обратного вызова check_configured_cb вызывается, чтобы определить, полностью ли настроен модуль и готов ли он принимать файлы WAL (например, что в его параметрах конфигурации установлены допустимые значения). Если функция check_configured_cb не определена, сервер всегда предполагает, что модуль настроен.

typedef bool (*ArchiveCheckConfiguredCB) (ArchiveModuleState *state);

Если возвращается true, сервер перейдет к архивированию файла путем вызова функции обратного вызова archive_file_cb. Если возвращается false, архивирование не выполнится, а архиватор выдаст в журнал сервера следующее сообщение:

WARNING:  archive_mode enabled, yet archiving is not configured
-- ПРЕДУПРЕЖДЕНИЕ: включен archive_mode, но архивирование не настроено

В последнем случае сервер будет периодически вызывать эту функцию, и архивирование начнется, только когда она вернет true.

Функция обратного вызова для архивирования

Функция обратного вызова archive_file_cb вызывается для архивирования одного файла WAL.

typedef bool (*ArchiveFileCB) (ArchiveModuleState *state, const char *file, const char *path);

Если возвращается true, сервер переходит к следующему этапу, как если бы файл был успешно заархивирован, то есть может переработать или удалить исходный файл WAL. Если возвращается false, сервер сохранит оригинальный файл WAL и повторит попытку архивирования позже. Аргумент file будет содержать только имя архивируемого файла WAL, тогда как аргумент path содержит полный путь к файлу WAL (в том числе имя файла).

Функция обратного вызова для выключения

Функция обратного вызова shutdown_cb вызывается, когда завершается процесс архиватора (например, после ошибки) или изменяется значение archive_library. Если функция shutdown_cb не определена, в таких ситуациях никакие специальные действия не предпринимаются. Если имеется информация о состоянии модуля архивирования, эта функция обратного вызова должна освободить ее во избежание утечек.

typedef void (*ArchiveShutdownCB) (ArchiveModuleState *state);