F.49. pgpro_bindump — модуль протокола репликации для резервного копирования и восстановления #
pgpro_bindump — это модуль, предоставляющий дополнительные команды для протокола репликации Postgres Pro, в частности для использования с утилитой pg_probackup3. pgpro_bindump имеет следующие преимущества:
Упрощённая связь с сервером. Для подключения к серверу баз данных pgpro_bindump не требует протокола SSH и связанных с ним настроек.
Интегрированная передача WAL. Файлы WAL передаются вместе с файлами данных, что снижает риск потери информации при резервном копировании.
Оптимизированное хранение. Файлы копируются не в исходном виде, а архивируются в собственном формате pg_probackup3 —
CBOR(RFC 8949 Concise Binary Object Representation, Сжатое представление двоичных объектов), что повышает эффективность хранения.
F.49.1. Архитектура #
Ключевые особенности работы pgpro_bindump:
Для обработки подключений от внешних приложений создаётся выделенный обслуживающий процесс. Для отправки запросов к этому процессу можно использовать утилиту pg_probackup3 или собственное приложение.
При необходимости можно устанавливать несколько соединений для одного приложения.
Поскольку модуль pgpro_bindump имеет прямой доступ к файлам базы данных, дополнительных разрешений не требуется.
Приложение pgpro_bindump использует библиотеку libpgprobackup вместе со встроенным модулем кодирования для передачи данных в приложение.
Параметр конфигурации
walsender_plugin_librariesупрощает процесс добавления и использования новых команд репликации, включая пользовательские.
F.49.2. Ограничения и требования #
В настоящее время pgpro_bindump имеет следующие ограничения и требования:
Для работы pgpro_bindump требуются
libpgprobackup.soиlibpb3_encoder.soиз пакетаlibpb3-encoder.
F.49.3. Установка и настройка #
Модуль pgpro_bindump входит в состав Postgres Pro как часть пакета postgrespro-ent-18-contrib (подробные инструкции по установке приведены в Главе 17). После установки Postgres Pro выполните шаги ниже.
Задайте следующие параметры в файле
postgresql.conf:shared_preload_libraries = 'pgpro_bindump' wal_level = 'replica' # or 'logical' walsender_plugin_libraries = 'pgpro_bindump'
Перезапустите экземпляр Postgres Pro.
Примечание
Поскольку pgpro_bindump является модулем, а не расширением, команда CREATE EXTENSION не требуется.
F.49.4. Команды репликации #
Модуль pgpro_bindump поддерживает следующие команды репликации:
just-noop— команда-заглушка, не выполняющая никаких действий.start_backup— запускает процесс резервного копирования.copy_files— копирует файлы в форматеCBOR.stop_backup— останавливает процесс резервного копирования.
Резервное копирование выполняется в режиме PRO — расширенном режиме источника данных резервного копирования, включающем все доступные оптимизации и улучшения, в том числе проприетарный протокол репликации и специализированные команды репликации.
Для отправки команд из пользовательского приложения в pgpro_bindump и получения приложением выходных данных из pgpro_bindump используйте libpq.
Примечание
Для работы требуется активное подключение к работающему серверу Postgres Pro.
F.49.4.1. start_backup #
start_backup LABELметка, INCR_MODEинкрементальный_режим, START_LSNначальный_lsn, TRANSFER_MODEрежим_передачи, [TRANSFER_BUFFER_SIZEразмер_буфера]
Запускает процесс резервного копирования. Передаёт приложению следующие данные:
start_lsn— LSN на момент начала резервного копирования.start_tli— идентификатор линии времени на момент начала резервного копирования.min_xid— минимальный идентификатор транзакции на момент начала резервного копирования.min_multixact— минимальный идентификатор мультитранзакции на момент начала резервного копирования.tablespace_list— список табличных пространств, включённых в резервную копию.database_list— список баз данных, включённых в резервную копию.
LABELметкаИмя резервной копии.
INCR_MODEинкрементальный_режимТип инкрементального копирования. Допустимые значения:
PTRACK,DELTA.START_LSNначальный_lsnЗначение типа
XLogRecPtr, представляющее LSN на момент начала резервного копирования.TRANSFER_MODEрежим_передачиСпособ передачи данных с сервера в приложение. Возможные значения:
raw— данные передаются в несжатом виде блоками произвольного размера.packed— данные передаются в упакованном виде блоками по 128 КБ с общим заголовком.
packed— значение по умолчанию.TRANSFER_BUFFER_SIZEразмер_буфераЧисловое значение, определяющее размер буфера. Единственное возможное значение — значение по умолчанию: 131072 (128 КБ).
F.49.4.2. copy_files #
copy_files VERIFY_CHECKSUMS [TRUE | FALSE], COMPRESS_ALGалгоритм_сжатия, COMPRESS_LVLуровень_сжатия, TRANSFER_MODEрежим_передачи, [INCR_MODEинкрементальный_режим], [START_LSNначальный_lsn], [TRANSFER_BUFFER_SIZEразмер_буфера], [WORKER_INFOчисло_процессов:ид_процесса]
Передаёт блоки файлов данных и файлов WAL, упакованные в формате CBOR.
VERIFY_CHECKSUMSЛогическое значение (
trueилиfalse), определяющее необходимость проверки контрольных сумм.COMPRESS_ALGалгоритм_сжатияИспользуемый алгоритм сжатия. Допустимые значения:
zlib,zstd,lz4,none.COMPRESS_LVLуровень_сжатияУровень сжатия. Возможные значения: 1, 2, 3, 4, 5.
TRANSFER_MODEрежим_передачиСпособ передачи данных с сервера в приложение. Возможные значения:
raw— данные передаются в несжатом виде блоками произвольного размера.packed— данные передаются в упакованном виде блоками по 128 КБ с общим заголовком.
packed— значение по умолчанию.INCR_MODEинкрементальный_режимТип инкрементального копирования. Допустимые значения:
PTRACK,DELTA.START_LSNначальный_lsnЗначение типа
XLogRecPtr, представляющее LSN на момент начала резервного копирования.TRANSFER_BUFFER_SIZEразмер_буфераЧисловое значение, определяющее размер буфера. Единственное возможное значение — значение по умолчанию: 131072 (128 КБ).
WORKER_INFOчисло_процессов:ид_процессаКоличество процессов и идентификатор процессора.
F.49.4.3. stop_backup #
stop_backup STREAM [TRUE | FALSE], COMPRESS_ALGалгоритм_сжатия, COMPRESS_LVLуровень_сжатия, [EXTERNALSвнешние_каталоги] [TRANSFER_BUFFER_SIZEразмер_буфера], [TRANSFER_MODEрежим_передачи]
Завершает процесс копирования и закрывает текущее соединение. Отправляет в приложение следующие данные:
stop_lsn— LSN на момент завершения резервного копирования.stop_tli— идентификатор линии времени на момент завершения резервного копирования.Файл
backup.control.Набор файлов WAL (только при включённой передаче WAL).
STREAMЛогическое значение (
trueилиfalse), определяющее, включена ли потоковая передача WAL.COMPRESS_ALGалгоритм_сжатияИспользуемый алгоритм сжатия. Допустимые значения:
zlib,zstd,lz4,none.COMPRESS_LVLуровень_сжатияУровень сжатия. Возможные значения: 1, 2, 3, 4, 5.
EXTERNALSвнешние_каталогиСписок внешних каталогов.
TRANSFER_BUFFER_SIZEразмер_буфераЧисловое значение, определяющее размер буфера. Единственное возможное значение — значение по умолчанию: 131072 (128 КБ).
TRANSFER_MODEрежим_передачиСпособ передачи данных с сервера в приложение. Возможные значения:
raw— данные передаются в несжатом виде блоками произвольного размера.packed— данные передаются в упакованном виде блоками по 128 КБ с общим заголовком.
packed— значение по умолчанию.
F.49.5. Авторы #
Postgres Professional, Москва, Россия.
F.49. pgpro_bindump — a replication protocol module for backup and restore #
pgpro_bindump is a module designed to implement additional commands for the Postgres Pro replication protocol, specifically for use with the pg_probackup3 utility. pgpro_bindump offers the following benefits:
Simplified communication: pgpro_bindump does not require the SSH protocol and associated configurations to connect to a database server.
Integrated WAL transfer: WAL files are transferred together with data files, reducing the risk of data loss during backups.
Optimized storage: Files are not copied as they are, but are archived using the pg_probackup3 own format,
CBOR(RFC 8949 Concise Binary Object Representation), which enhances the storage efficiency.
F.49.1. Architecture #
Here are some key points of how pgpro_bindump works:
A dedicated backend process is created to handle connections from external applications. You can use the pg_probackup3 utility or a custom application to send requests to this backend.
Multiple connections can be established for the same application if needed.
Since the pgpro_bindump module has direct access to the database files, it does not require any additional permissions.
pgpro_bindump uses the libpgprobackup library, along with its built-in encoder module, to send data to the application.
The
walsender_plugin_librariesconfiguration parameter simplifies the process of adding and utilizing new replication commands, including custom ones.
F.49.2. Limitations and Requirements #
pgpro_bindump currently has the following limitations and requirements:
libpgprobackup.soandlibpb3_encoder.sofrom thelibpb3-encoderpackage are required for pgpro_bindump operation.
F.49.3. Installation and Setup #
The pgpro_bindump module is included in Postgres Pro as part of the postgrespro-ent-18-contrib package (for the installation instructions, see Chapter 17). Once you complete Postgres Pro installation, follow the steps below.
Specify the following parameters in the
postgresql.conffile:shared_preload_libraries = 'pgpro_bindump' wal_level = 'replica' # or 'logical' walsender_plugin_libraries = 'pgpro_bindump'
Restart the Postgres Pro instance.
Note
Since pgpro_bindump is a module and not an extension, the CREATE EXTENSION command is not needed.
F.49.4. Replication Commands #
The pgpro_bindump module implements the following replication commands:
just-noop— a do-nothing command.start_backup— starts the backup process.copy_files— copies files in theCBORformat.stop_backup— stops the backup process.
The backup process runs in the PRO mode — an advanced backup data source mode that incorporates all available optimizations and enhancements, including the proprietary replication protocol and specialized replication commands.
To send commands from a user application to pgpro_bindump and to receive the output data from pgpro_bindump by the application, use libpq.
Note
An established connection to a running Postgres Pro server is required.
F.49.4.1. start_backup #
start_backup LABELlabel, INCR_MODEincr_mode, START_LSNstart_lsn, TRANSFER_MODEtransfer_mode, [TRANSFER_BUFFER_SIZEbuffer_size]
Starts the backup process. Sends the following data to the application:
start_lsn— LSN at the start of the backup.start_tli— the timeline ID at the start of the backup.min_xid— the minimal transaction ID at the start of the backup.min_multixact— the minimalmultixactID at the start of the backup.tablespace_list— a list of tablespaces included in the backup.database_list— a list of databases included in the backup.
LABELlabelThe name of the backup.
INCR_MODEincr_modeThe type of incremental backup. Possible values:
PTRACK,DELTA.START_LSNstart_lsnAn
XLogRecPtrvalue representing LSN at the start of the backup.TRANSFER_MODEtransfer_modeThe method to be used for sending data from a server to an application. Possible values:
raw— unpacked data is sent in random blocks of arbitrary size.packed— packed data is sent in blocks of 128 KB with a common header.
packedis the default value.TRANSFER_BUFFER_SIZEbuffer_sizeA numeric value representing the buffer size. The preset (unchanged) value is 131072 (128 KB).
F.49.4.2. copy_files #
copy_files VERIFY_CHECKSUMS [TRUE | FALSE], COMPRESS_ALGcompress_alg, COMPRESS_LVLcompress_lvl, TRANSFER_MODEtransfer_mode, [INCR_MODEincr_mode], [START_LSNstart_lsn], [TRANSFER_BUFFER_SIZEbuffer_size], [WORKER_INFOnumber_of_workers:worker_id]
Forwards blocks of data files and WAL files packaged in the CBOR format.
VERIFY_CHECKSUMSA boolean value (
trueorfalse) indicating whether to verify checksums.COMPRESS_ALGcompress_algThe compression algorithm to be used. Possible values:
zlib,zstd,lz4,none.COMPRESS_LVLcompress_lvlThe compression level. Possible values: 1, 2, 3, 4, 5.
TRANSFER_MODEtransfer_modeThe method to be used for sending data from a server to an application. Possible values:
raw— unpacked data is sent in random blocks of arbitrary size.packed— packed data is sent in blocks of 128 KB with a common header.
packedis the default value.INCR_MODEincr_modeThe type of incremental backup. Possible values:
PTRACK,DELTA.START_LSNstart_lsnAn
XLogRecPtrvalue representing LSN at the start of the backup.TRANSFER_BUFFER_SIZEbuffer_sizeA numeric value representing the buffer size. The preset (unchanged) value is 131072 (128 KB).
WORKER_INFOnumber_of_workers:worker_idThe number of workers and the worker ID.
F.49.4.3. stop_backup #
stop_backup STREAM [TRUE | FALSE], COMPRESS_ALGcompress_alg, COMPRESS_LVLcompress_lvl, [EXTERNALSexternals] [TRANSFER_BUFFER_SIZEbuffer_size], [TRANSFER_MODEtransfer_mode]
Completes the copy process and closes the existing connection. Sends the following data to the application:
stop_lsn— LSN at the end of the backup.stop_tli— the timeline ID at the end of the backup.The
backup.controlfile.A set of WAL files (only if WAL streaming is enabled).
STREAMA boolean value (
trueorfalse) indicating whether WAL streaming is enabled.COMPRESS_ALGcompress_algThe compression algorithm to be used. Possible values:
zlib,zstd,lz4,none.COMPRESS_LVLcompress_lvlThe compression level. Possible values: 1, 2, 3, 4, 5.
EXTERNALSexternalsA list of external directories.
TRANSFER_BUFFER_SIZEbuffer_sizeA numeric value representing the buffer size. The preset (unchanged) value is 131072 (128 KB).
TRANSFER_MODEtransfer_modeThe method to be used for sending data from a server to an application. Possible values:
raw— unpacked data is sent in random blocks of arbitrary size.packed— packed data is sent in blocks of 128 KB with a common header.
packedis the default value.
F.49.5. Authors #
Postgres Professional, Moscow, Russia.