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 выполните шаги ниже.

  1. Задайте следующие параметры в файле postgresql.conf:

    shared_preload_libraries = 'pgpro_bindump'
    wal_level = 'replica' # or 'logical'
    walsender_plugin_libraries = 'pgpro_bindump'
  2. Перезапустите экземпляр 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_libraries configuration 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.so and libpb3_encoder.so from the libpb3-encoder package 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.

  1. Specify the following parameters in the postgresql.conf file:

    shared_preload_libraries = 'pgpro_bindump'
    wal_level = 'replica' # or 'logical'
    walsender_plugin_libraries = 'pgpro_bindump'
    
  2. 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 the CBOR format.

  • 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 LABEL label, INCR_MODE incr_mode, START_LSN start_lsn, TRANSFER_MODE transfer_mode,
[TRANSFER_BUFFER_SIZE buffer_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 minimal multixact ID 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.

LABEL label

The name of the backup.

INCR_MODE incr_mode

The type of incremental backup. Possible values: PTRACK, DELTA.

START_LSN start_lsn

An XLogRecPtr value representing LSN at the start of the backup.

TRANSFER_MODE transfer_mode

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

packed is the default value.

TRANSFER_BUFFER_SIZE buffer_size

A 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_ALG compress_alg, COMPRESS_LVL compress_lvl, TRANSFER_MODE transfer_mode,
[INCR_MODE incr_mode], [START_LSN start_lsn], [TRANSFER_BUFFER_SIZE buffer_size],
[WORKER_INFO number_of_workers:worker_id]

Forwards blocks of data files and WAL files packaged in the CBOR format.

VERIFY_CHECKSUMS

A boolean value (true or false) indicating whether to verify checksums.

COMPRESS_ALG compress_alg

The compression algorithm to be used. Possible values: zlib, zstd, lz4, none.

COMPRESS_LVL compress_lvl

The compression level. Possible values: 1, 2, 3, 4, 5.

TRANSFER_MODE transfer_mode

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

packed is the default value.

INCR_MODE incr_mode

The type of incremental backup. Possible values: PTRACK, DELTA.

START_LSN start_lsn

An XLogRecPtr value representing LSN at the start of the backup.

TRANSFER_BUFFER_SIZE buffer_size

A numeric value representing the buffer size. The preset (unchanged) value is 131072 (128 KB).

WORKER_INFO number_of_workers:worker_id

The number of workers and the worker ID.

F.49.4.3. stop_backup #

stop_backup STREAM [TRUE | FALSE], COMPRESS_ALG compress_alg, COMPRESS_LVL compress_lvl,
[EXTERNALS externals] [TRANSFER_BUFFER_SIZE buffer_size], [TRANSFER_MODE transfer_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.control file.

  • A set of WAL files (only if WAL streaming is enabled).

STREAM

A boolean value (true or false) indicating whether WAL streaming is enabled.

COMPRESS_ALG compress_alg

The compression algorithm to be used. Possible values: zlib, zstd, lz4, none.

COMPRESS_LVL compress_lvl

The compression level. Possible values: 1, 2, 3, 4, 5.

EXTERNALS externals

A list of external directories.

TRANSFER_BUFFER_SIZE buffer_size

A numeric value representing the buffer size. The preset (unchanged) value is 131072 (128 KB).

TRANSFER_MODE transfer_mode

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

packed is the default value.

F.49.5. Authors #

Postgres Professional, Moscow, Russia.

FAQ