libpgprobackup
libpgprobackup — библиотека с API для резервного копирования данных, восстановления из резервных копий, а также проверки и объединения резервных копий
Описание #
Библиотека libpgprobackup содержит функции для резервного копирования, восстановления из резервных копий, а также проверки и объединения резервных копий. Предоставляемый API позволяет создать собственное приложение для резервного копирования и восстановления данных вместо использования утилиты командной строки pg_probackup.
Библиотека хранит резервные копии в файлах собственного формата.
Библиотека берёт на себя взаимодействие с сервером баз данных, обработку данных, кодирование и декодирование, а также создание и хранение метаданных для резервных копий.
Приложение, использующее библиотеку, должно предоставить ей доступ к хранилищу, такому как файловая система, хранилище S3 или лента. Однако за операции в файловой системе, такие как чтение и хранение резервных копий, а также хранение метаданных, отвечает приложение. Приложение взаимодействует с libpgprobackup следующим образом:
Приложение подготавливает экземпляр базы данных к резервному копированию и вызывает функцию libpgprobackup backup.
libpgprobackup преобразует файлы данных и файлы WAL в формат pg_probackup3 и передаёт их приложению.
Клиентское приложение отправляет данные в файл в целевом хранилище (файловая система, хранилище S3 или лента) и сохраняет метаданные резервной копии. Промежуточное хранилище не используется.
Для восстановления из резервной копии с помощью функции libpgprobackup restore, выполнения проверки целостности резервной копии с помощью функции validate или объединения резервных копий с помощью функции merge, приложение предоставляет библиотеке функции для получения данных и метаданных резервной копии.
libpgprobackup реализована на C++, но может использоваться в приложениях, написанных на различных языках программирования. Интеграция с приложениями на C/C++ должна вызывать наименьшие сложности. Библиотека использует соглашение о вызовах extern "C".
Структуры и функции libprobackup объявлены в файле probackup_lib.h.
Функции #
Библиотека libpgprobackup содержит функции, описанные ниже. При вызове функций библиотеки они принимают структуры с параметрами команд и структуру с указателями на функции, которые работают с файлами и метаданными.
boolbackup(ConnectOptionsLib*conn_opt,BackupOptionsLib*backup_opt,MetadataProviderLib*metadata); #Подключается к локальному или удалённому серверу и выполняет резервное копирование. Возвращает
trueв случае успеха иfalseв случае ошибки.Аргументы:
conn_opt— указатель на структуруConnectOptionsLib, которая содержит параметры подключения к северу Postgres Pro, такие какpgdatabase,pghost,pgport,pguser,password.backup_opt— указатель на структуруBackupOptionsLib, которая содержит параметры резервного копирования, такие как режим резервного копирования или количество потоков.metadata— указатель на структуруMetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.
boolrestore(RestoreOptionsLib*restore_opt,MetadataProviderLib*metadata); #Восстанавливает данные из резервной копии с использованием параметров, переданных в соответствующих структурах, в локальную файловую систему. Возвращает
trueв случае успеха иfalseв случае ошибки.Аргументы:
restore_opt— указатель на структуруRestoreOptionsLib, содержащую параметры для восстановления из резервной копии.metadata— указатель на структуруMetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.
boolvalidate(RestoreOptionsLib*restore_opt,MetadataProviderLib*metadata,boolwithParents); #Проверяет, что все файлы, необходимые для восстановления кластера из резервной копии, присутствуют и не повреждены. Если параметр
withParentsустановлен в значение true, также проверяются все резервные копии в цепочке родительских. Возвращаетtrueв случае успеха иfalseв случае ошибки.Аргументы:
restore_opt— указатель на структуруRestoreOptionsLib, содержащую параметры для проверки целостности резервной копии.metadata— указатель на структуруMetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.withParents— логическое значение, определяющее, необходимо ли также проверять родительские резервные копии.
boolmerge(MergeOptionsLib*merge_opt,MetadataProviderLib*metadata,boolwith_file_map); #Объединяет цепочку инкрементальных резервных копий в одну полную. Во время объединения создаётся новая полная резервная копия, включающая все родительские. Если у родительских копий нет дополнительных зависимостей, они удаляются после успешного объединения. Возвращает
trueв случае успеха иfalseв случае ошибки.Аргументы:
merge_opt— указатель на структуруMergeOptionsLib, содержащую параметры для объединения резервных копий.metadata— указатель на структуруMetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.with_file_map— включает создание файлов сопоставления в метаданных.
voidset_probackup_logger(Loggerinfo,Loggerwarning,Loggererror,Loggerdebug); #Определяет три функции-обработчика записи в журнал, которые libpgprobackup будет использовать для вывода отладочных, информационных сообщений, предупреждений или сообщений об ошибках. Каждая из этих функций должна принимать строковый параметр с сообщением, передаваемым библиотекой.
Аргументы:
info— указатель на функцию, которая будет обрабатывать информационные сообщения.warning— указатель на функцию, которая будет обрабатывать предупреждения.error— указатель на функцию, которая будет обрабатывать сообщения об ошибках.debug— указатель на функцию, которая будет обрабатывать отладочные сообщения.
-
voidget_api_info# Возвращает структуру
ProBackupApiInfo, содержащую информацию о версии API, компиляторе и операционной системе.-
voidset_cancel# Сигнализирует текущей команде начать плавное завершение. Команда завершит текущую операцию, выполнит необходимую очистку, переведёт резервную копию в статус
ERRORи прекратит работу.
Структуры для работы с файлами #
Библиотека получает обратную связь от приложения через структуру типа MetadataProviderLib, которая должна содержать указатели на функции, работающие с файлами и метаданными.
Используются обработчики из библиотеки для функций, переданных приложением. Указатели на функции передаются в библиотеку через структуру MetadataProviderLib. Операции чтения или записи файлов определяются в структурах CSource и CSink, соответственно.
Для обратной связи от приложения структуры библиотеки содержат указатель void *thisPointer, в котором приложение может хранить указатель на свою собственную функцию или экземпляр класса. Этот указатель передаётся в функции-обработчики при их вызове из библиотеки.
MetadataProviderLib #
Указатель на эту структуру передаётся всем основным функциям libpgprobackup, таким как backup, restore, validate, и merge. Эта структура определяет методы для работы с данными резервных копий, для записи и чтения метаданных резервных копий, а также для получения списка резервных копий.
typedef struct
{
CSinkArray *(*get_sinks_for_backup)(const char *backup_id, size_t nsinks, void *thisPointer);
CSourceArray *(*get_sources_for_backup)(const char *backup_id, void *thisPointer);
CSink *(*get_sink_for_backup_map)(const char *backup_id, void *thisPointer);
CSource *(*get_source_for_backup_map)(const char *backup_id,
void *thisPointer);
void (*register_backup)(PgproBackup *backup, void *ptr);
PgproBackup *(*get_backup_by_id)(const char *backup_id, void *thisPointer);
void (*free_backup)(PgproBackup *backup, void *thisPointer);
char **(*list_backup_ids)(void *thisPointer);
bool (*write_backup_status)(const char *backup_id, BackupStatus status,
void *thisPointer);
void *thisPointer;
} MetadataProviderLib;Здесь:
get_sinks_for_backup#Указатель на функцию, которая возвращает
CSinkArray— массив указателей на структуруCSink(см.CSourceиCSinkдля получения более подробной информации). Требуется для записи информации в резервную копию.backup_idсодержит строку с идентификатором резервной копии. ВthisPointerприложение получает указатель, который ранее был передан в библиотеку через структуру.get_sources_for_backup#Указатель на функцию, которая возвращает
CSourceArray— массив указателей на структуруCSource(см.CSourceиCSinkдля получения более подробной информации). Требуется для чтения информации из резервной копии.backup_idсодержит строку с идентификатором резервной копии. ВthisPointerприложение получает указатель, который ранее был передан в библиотеку через структуру.get_sink_for_backup_map#Указатель на функцию, которая возвращает указатель на структуру
CSink(см.CSourceиCSinkдля получения более подробной информации). Требуется для записи информации в резервную копию.backup_idсодержит строку с идентификатором резервной копии. ВthisPointerприложение получает указатель, который ранее был передан в библиотеку через структуру.get_source_for_backup_map#Указатель на функцию, которая возвращает указатель на структуру
CSource(см.CSourceиCSinkдля получения более подробной информации). Требуется для чтения информации о карте резервной копии из её метаданных.backup_idсодержит строку с идентификатором резервной копии. ВthisPointerприложение получает указатель, который ранее был передан в библиотеку через структуру.register_backup#Указатель на функцию, которая сохраняет метаданные резервной копии. Принимает структуру
PgproBackup.get_backup_by_id#Указатель на функцию, которая получает метаданные резервной копии, определяемой параметром
backup_id.free_backup#Освобождает память для структуры
PgproBackup, возвращаемой функциейget_backup_by_id.list_backup_ids#Возвращает список доступных идентификаторов резервных копий. Список содержит указатели на строки, заканчивающиеся на ноль. Последний указатель в списке также должен быть нулевым. Память для списка должна быть выделена с помощью функции языка C, такой как
mallocилиstrdup, поскольку библиотека освобождает память с использованием функцииfree.write_backup_status#Указатель на функцию, которая сохраняет статус резервной копии. Статус резервной копии обновляется отдельно от сохранения остальных метаданных резервной копии.
void *thisPointer#Указатель, который передаётся из библиотеки во все функции-обработчики.
CSource и CSink #
Эти структуры необходимы для чтения и записи блоков данных в файл резервной копии. Массивы указателей на эти структуры должны возвращаться функциями get_sources_for_backup и get_sinks_for_backup, соответственно. Каждая из этих структур фактически представляет собой файл резервной копии, который открыт соответственно для чтения или записи.
/* Support structure */
typedef struct
{
unsigned char *ptr;
size_t len;
} c_buffer_t;
typedef struct
{
c_buffer_t (*read_one)(void *thisPointer);
ssize_t (*read)(char *buf, size_t size, void *thisPointer);
void (*seek)(off_t offset, void *thisPointer);
off_t (*get_offset)(void *thisPointer);
void (*close)(void *thisPointer);
void *thisPointer;
} CSource;
typedef struct
{
/* Write one Pb structure. See @PbStructs. */
size_t (*write_one)(uint8_t *buf, size_t size, void *thisPointer);
ssize_t (*write)(char *buf, size_t size, void *thisPointer);
/* Close this Sink. No more calls will be done. */
void (*close)(void *thisPointer);
void *thisPointer;
} CSink;
typedef struct
{
size_t nsinks;
CSink **array;
} CSinkArray;
typedef struct
{
size_t nsources;
CSource **array;
} CSourceArray;В поле thisPointer приложение может передать в структуру указатель на структуру или класс приложения, который, например, содержит дескриптор открытого файла.
Функции из структуры CSource используются для чтения файла резервной копии, а функции из структуры CSink — для записи. Для этого каждая из этих структур в настоящее время имеет по две функции. Функции read_one и write_one выполняют операции низкого уровня с блоком данных. write_one сохраняет размер блока, в то время как read_one сначала читает размер блока, а затем сам блок данных этого размера.
Функции read и write используются для упрощённой реализации чтения/записи. Их аргументы аналогичны аргументам общих функций для работы с файлами. Обработка размера блока выполняется внутри библиотеки. Эти функции должны возвращать размер прочитанных/записанных данных или 1 в случае ошибки.
Функция seek необязательна и на данный момент работает только вместе с файлами сопоставления. Если реализация этой функции слишком затратна для вашей системы хранения, её можно опустить.
Функция get_offset возвращает текущую позицию чтения в выходном потоке данных (приёмнике).
Функция close закрывает файл.
PgproBackup #
В этой структуре передаются метаданные резервной копии.
typedef struct
{
BackupStatus backup_status;
BackupMode backup_mode; /* Mode - one of BACKUP_MODE_xxx */
char *backup_id; /* Identifier of the backup. */
char *parent_backup_id; /* Identifier of the parent backup. */
BackupTimeLineID tli; /* timeline of start and stop backup lsns */
BackupXLogRecPtr start_lsn; /* backup's starting transaction log location */
BackupXLogRecPtr stop_lsn; /* backup's finishing transaction log location */
BackupTimestampTz start_time; /* UTC time of backup creation */
BackupTransactionId minxid; /* min Xid for the moment of backup start */
BackupMultiXactId
minmulti; /* min multixact for the moment of backup start */
bool stream; /* Was this backup taken in stream mode? I.e. does it include
all needed WAL files? */
bool from_replica; /* Was this backup taken from replica */
char *primary_conninfo; /* Connection parameters of the backup in the format
suitable for recovery.conf */
char *note;
/* For compatibility check */
uint32_t block_size;
uint32_t wal_block_size;
char *program_version;
int server_version;
size_t uncompressed_bytes; ///< Size of data and non-data files before
///< compression is applied
size_t data_bytes; ///< Size of data and non-data files after compression is
///< applied
CompressAlg compress_alg;
int compress_level;
BackupTimestampTz
end_time; /* the moment when backup was finished, or the moment
* when we realized that backup is broken */
BackupTimestampTz
end_validation_time; /* UTC time when validation finished */
BackupSource backup_source;/* direct, base or pro backup method*/
size_t wal_bytes;// not used in pb3
BackupTimestampTz recovery_time;
} PgproBackup;После выполнения функции backup библиотека вызывает функцию-обработчик register_backup, в которую передаётся заполненная структура PgproBackup. Переданную информацию можно сохранять по своему усмотрению.
Для получения информации о существующей резервной копии библиотека использует функцию-обработчик get_backup_by_id. Из этой функции приложение должно вернуть указатель на структуру PgproBackup с метаданными резервной копии, имеющей указанный идентификатор, или нулевой указатель в случае ошибки.
Чтобы освободить память для структуры PgproBackup приложение должно вызвать функцию-обработчик free_backup.
ProBackupApiInfo #
Эта структура содержит следующую информацию о libpgprobackup API:
Версия libpgprobackup:
Компоненты версии (основная, дополнительная, патч)
Версия в виде строки, выводимой пользователю
Поддерживаемые алгоритмы сжатия
Версия компилятора
Версия операционной системы
Тип сборки
typedef struct tag_ProBackupApiInfo {
const int pbk_ver_major;
const int pbk_ver_minor;
const int pbk_ver_patch;
/* User-visible probackup lib version. */
const char *version;
/* Used for dynamic linking */
const int dynamic_api_version;
/* List of supported compressions. */
const char **supported_compressions;
/* Compiler info */
const char *compiler_info;
/* OS info */
const char *os_info;
/* Release/Debug */
const char *build_type;
} ProBackupApiInfo;dynamic_api_version помогает предотвратить использование клиентами несовместимых версий библиотеки. supported_compressions — завершающийся нулём список поддерживаемых алгоритмов сжатия.
Структура выделяется статически — приложения не должны пытаться освободить её память.
Используйте get_api_info, чтобы получить указатель на эту структуру.
Общие параметры #
В этом разделе перечисляются структуры, используемые для передачи параметров командам. Для получения более подробной информации обратитесь к заголовочному файлу библиотеки probackup_lib.h.
connectOptionsLib #
Следующая структура определяет параметры для подключения к серверу Postgres Pro:
typedef struct connectOptionsLib
{
/* The database name. */
const char *pgdatabase;
/* Name of host to connect to. */
const char *pghost;
/* Port number to connect to at the server host, or socket file name
* extension for Unix-domain connections.*/
const char *pgport;
/* PostgreSQL user name to connect as. */
const char *pguser;
/* Password to be used if the server demands password authentication. */
const char *password;
} ConnectOptionsLib;backupOptionsLib #
Ниже представлена структура, которая определяет параметры для создания резервной копии. На данный момент поддерживаются только режимы резервного копирования FULL и DELTA.
typedef struct backupOptionsLib
{
/* Number of threads, if backup mode supports multithreading */
int num_threads;
/* Backup mode PAGE, PTRACK, DELTA, AUTO, FULL*/
BackupMode backup_mode;
/* Backup source DIRECT, BASE or PRO */
BackupSource backup_source;
/* For DIRECT source is required to set up PGDATA. It is not required for
* other sources */
const char *pgdata;
/* Backup Id if you wants to use custom id, otherwise it will be generated a
* unique id using datetime of creation */
const char *backup_id;
/* Id of parent backup. It is not required for FULL backup mode */
const char *parent_backup_id;
/* Name of replication slot, if you use custom slot created by
* pg_create_physical_replication_slot(). Otherwise will be used auto
* generated slot */
const char *replication_slot;
bool create_slot;
const char *backup_note;
/* If true, then WAL will be sent in stream mode, otherwise in archive mode
*/
bool stream_wal;
/* Progress flag. If true progress will be logged */
bool progress;
const char *external_dir_str;
/* Verify check sums. It is available only if checksums enabled on
* PostgresPro server */
bool verify_checksums;
/* Compression algorithm, that is used for sending data between PostgresPro
* server and libpgprobackup */
CompressAlg compress_alg;
/* Compression level, that is used for sending data between PostgresPro
* server and libpgprobackup */
int compress_level;
/* Wait timeout for WAL segment archiving */
uint32_t archive_timeout;
/* Number of backup segment files. */
uint32_t num_segments;
/* Should we send raw 8k pages, or package them into larger groups. */
TransferMode transfer_mode;
/* Number of threads which write into segments. */
uint32_t num_write_threads;
/* Number of threads used for backup validation. */
uint32_t num_validate_threads;
} BackupOptionsLib;restoreOptionsLib #
Следующая структура определяет параметры для восстановления из резервной копии. Эти параметры также используются для проверки резервной копии:
typedef struct restoreOptionsLib
{
/* Number of threads */
uint32_t num_threads;
/* Path to pgdata for restoration */
const char *pgdata;
/* Backup ID for restoration */
char *backup_id;
/* Progress flag. If true progress will be logged */
bool progress;
/* Skip external directories */
bool skip_external_dirs;
const char *external_mapping;
const char *tablespace_mapping;
const char *db_str_oids;
const char *db_str_names;
PartialRestoreType restoreTyp
/* Should we verify postgres page checksums */
bool verify_checksums;
/* Restore command to write in postgresql.auto.conf */
/* https://postgrespro.ru/docs/enterprise/16/runtime-config-wal#GUC-RESTORE-COMMAND */
const char *config_content;
/* Need recovery signal */
bool need_recovery_signal;
/* Need standby signal */
bool need_standby_signal;
/* No synchronization */
bool no_sync;
/* Number of threads to write restored data */
uint32_t num_write_threads;
/* Number of threads used for validation */
uint32_t num_validate_threads;
} RestoreOptionsLib;mergeOptionsLib #
Следующая структура определяет параметры для объединения резервных копий:
typedef struct mergeOptionsLib
{
/* Number of threads */
int num_threads;
/* Path to pgdata to restore to */
const char *pgdata;
/* Incremental backup ID for the merge */
const char *backup_id;
/* Target backup ID for the merge */
const char *target_backup_id;
/* Progress flag. If true progress will be logged */
bool progress;
/* ID of the last increment */
const char *merge_from_id;
/* Time interval within which to merge backups */
int interval;
/* Number of threads to write merged data */
uint32_t num_write_threads;
/* Number of threads used for validation */
uint32_t num_validate_threads;
} MergeOptionsLib;Константы #
BackupMode #
/*
Backup Mode is how backup is taken.
All DIFF modes require parent backup id passed in the BackupOptions.
Parent backup id is ignored in the FULL mode.
DIFF_AUTO returns selected mode in the metadata. Tentatively it prefers
DIFF_PAGE if WAL summarization is available, if not it tries to do
DIFF_PTRACK if ptrack is enabled and finally it falls back to DIFF_DELTA.
In case when even DIFF_DELTA is not possible (no parent full backup exists)
FULL backup is taken.
*/
typedef enum BackupMode
{
BACKUP_MODE_INVALID = 0,
BACKUP_MODE_DIFF_PAGE, /* incremental page backup */
BACKUP_MODE_DIFF_PTRACK, /* incremental page backup with ptrack system */
BACKUP_MODE_DIFF_DELTA, /* incremental page backup with lsn comparison */
BACKUP_MODE_DIFF_AUTO, /* library selects diff backup mode automatically */
BACKUP_MODE_FULL /* full backup */
} BackupMode;CompressAlg #
/*
* Compression mode which is used to transfer data between PG server and the client lib.
* Default is NONE_COMPRESS.
*/
typedef enum CompressAlg
{
NONE_COMPRESS = 0,
ZLIB_COMPRESS,
LZ4_COMPRESS,
ZSTD_COMPRESS,
} CompressAlg;BackupSource #
/**
Backup Source is a method used by the client to access PGDATA.
*/
typedef enum
{
/*
* Direct access. The client reads data files directly.
* Opens normal connection to execute PG_BACKUP_START/STOP.
* Local file access. Multithreaded. No special PostgresPro edition
* required.
*/
BACKUP_SOURCE_DIRECT,
/*
* Uses pg_basebackup protocol.
* Opens replication connection.
* Remote file access. No special PostgresPro edition required.
*/
BACKUP_SOURCE_BASE_BACKUP,
/*
* Uses pg_probackup protocol.
* Opens replication connection.
* Remote file access. Multithreaded. Only works with PostgresPro builds.
* Supported PostgresPro versions start with ent-15.
*/
BACKUP_SOURCE_PRO_BACKUP
} BackupSource;libpgprobackup
libpgprobackup — library with API to back up data, restore from backups, as well as validate and merge backups
Description #
The libpgprobackup library contains functions to back up data, restore from backups, as well as validate and merge backups. The API provided enables you to create your own application to back up and restore data instead of using the command-line utility pg_probackup.
The library stores backups in files of its own format.
The library takes over the interaction with the database server, data processing, coding, and decoding, as well as creation and storing the metadata for backups.
An application that uses the library must provide it with access to the storage, such as a file system, S3 storage, or tape. However, file system operations, such as reading and storing backups, as well as storing the metadata, are the responsibility of the application. The application interacts with libpgprobackup as follows:
The application prepares the database instance for backing up and calls the libpgprobackup backup function.
libpgprobackup transforms the data files and WAL files to the pg_probackup3 format and redirects them to the application.
The client application sends the data to a file on the target storage (file system, S3 storage, or tape) and saves the backup metadata. Note that no intermediate storage is used.
To restore from a backup by calling the libpgprobackup restore function, to perform the backup integrity check by calling the validate function, or to merge backups by calling the merge function, the application provides the library with functions to get the backup data and metadata.
libpgprobackup is implemented in C++, but it can be used in applications written in different programming languages. The integration with C/C++ applications must be least complicated. The library uses the extern "C" calling convention.
libpgprobackup structures and functions are declared in the in the probackup_lib.h file.
Functions #
The libpgprobackup library contains functions described below. When library functions are called, they accept structures with command parameters and a structure with pointers to functions that work with files and metadata.
-
boolbackup(ConnectOptionsLib*conn_opt,BackupOptionsLib*backup_opt,MetadataProviderLib*metadata); # Connects to the local or remote server and performs a backup. Returns
truein the case of success andfalsein case of error.Arguments:
conn_opt— pointer to theConnectOptionsLibstructure that defines the options to connect to the Postgres Pro server, such aspgdatabase,pghost,pgport,pguser,password.backup_opt— pointer to theBackupOptionsLibstructure that contains the backup options, such as the backup mode or number of threads.metadata— pointer to theMetadataProviderLibstructure that provides callback functions for processing of backup metadata and file operations.
-
boolrestore(RestoreOptionsLib*restore_opt,MetadataProviderLib*metadata); # Restores data from a backup using the parameters passed in the appropriate structures to the local file system. Returns
truein the case of success andfalsein case of error.Arguments:
restore_opt— pointer to theRestoreOptionsLibstructure that contains the options to restore from a backup.metadata— pointer to theMetadataProviderLibstructure that provides callback functions for processing of backup metadata and file operations.
-
boolvalidate(RestoreOptionsLib*restore_opt,MetadataProviderLib*metadata,boolwithParents); # Verifies that all the files required to restore the cluster from a backup are present and are not corrupt. If
withParentsis true, all the backups in the chain of parents are also validated. Returnstruein the case of success andfalsein case of error.Arguments:
restore_opt— pointer to theRestoreOptionsLibstructure that contains the options for integrity check of a backup.metadata— pointer to theMetadataProviderLibstructure that provides callback functions for processing of backup metadata and file operations.withParents— a boolean value that defines whether parent backups must also be validated.
-
boolmerge(MergeOptionsLib*merge_opt,MetadataProviderLib*metadata,boolwith_file_map); # Merges a chain of incremental backups into one full backup. During the merge a new full backup created includes all the parent backups. If the parent backups do not have additional dependencies, they are removed after a successful merge. Returns
truein the case of success andfalsein case of error.Arguments:
merge_opt— pointer to theMergeOptionsLibstructure that contains the options for merging backups.metadata— pointer to theMetadataProviderLibstructure that provides callback functions for processing of backup metadata and file operations.with_file_map— enables file map generation in metadata.
-
voidset_probackup_logger(Loggerinfo,Loggerwarning,Loggererror,Loggerdebug); # Defines three callback logger functions that libpgprobackup will use to output debug, information, warning, or error messages. Each of these functions must accept a string parameter with the message to be passed by the library.
Arguments:
info— pointer to the function that will process information messages.warning— pointer to the function that will process warnings.error— pointer to the function that will process error messages.debug— pointer to the function that will process debug messages.
-
voidget_api_info# Returns the
ProBackupApiInfostructure that contains information about the API version, compiler and operation system.-
voidset_cancel# Signals the current command to initiate graceful termination. The command will complete its current operation, perform necessary cleanup procedures, set the backup status to
ERROR, and terminate execution.
Structures to Work with Files #
The library gets feedback from the application through the structure of the MetadataProviderLib type, which must contain pointers to functions that work with files and metadata.
Callbacks from the library to functions passed by the application are used. Pointers to functions are passed to the library through the MetadataProviderLib structure. File read or write operations are defined in the CSource and CSink structures, respectively.
For the feedback from the application, library structures contain the void *thisPointer pointer, where the application can store the pointer to its own function or class instance. This pointer is passed to callback functions when they are called from the library.
MetadataProviderLib #
A pointer to this structure is passed to all the main librobackup functions, such as backup, restore, validate, and merge. This structure defines methods to work with backup data, to write and read backup metadata, and to get the list of backups.
typedef struct
{
CSinkArray *(*get_sinks_for_backup)(const char *backup_id, size_t nsinks, void *thisPointer);
CSourceArray *(*get_sources_for_backup)(const char *backup_id, void *thisPointer);
CSink *(*get_sink_for_backup_map)(const char *backup_id, void *thisPointer);
CSource *(*get_source_for_backup_map)(const char *backup_id,
void *thisPointer);
void (*register_backup)(PgproBackup *backup, void *ptr);
PgproBackup *(*get_backup_by_id)(const char *backup_id, void *thisPointer);
void (*free_backup)(PgproBackup *backup, void *thisPointer);
char **(*list_backup_ids)(void *thisPointer);
bool (*write_backup_status)(const char *backup_id, BackupStatus status,
void *thisPointer);
void *thisPointer;
} MetadataProviderLib;
Where:
get_sinks_for_backup#A pointer to the function that returns
CSinkArray— an array of pointers to theCSinkstructure (seeCSourceandCSinkfor more details). Needed for writing information into the backup.backup_idcontains the string with the backup ID. InthisPointer, the application gets the pointer that was previously passed to the library through the structure.get_sources_for_backup#A pointer to the function that returns
CSourceArray— an array of pointers to theCSourcestructure (seeCSourceandCSinkfor more details). Needed for reading information from the backup.backup_idcontains the string with the backup ID. InthisPointer, the application gets the pointer that was previously passed to the library through the structure.get_sink_for_backup_map#A pointer to the function that returns a pointer to
CSinkstructure (seeCSourceandCSinkfor more details). Needed for writing information into the backup metadata about the backup map.backup_idcontains the string with the backup ID. InthisPointer, the application gets the pointer that was previously passed to the library through the structure.get_source_for_backup_map#A pointer to the function that returns a pointer to the
CSourcestructure (seeCSourceandCSinkfor more details). Needed for reading information about the backup map from the backup metadata.backup_idcontains the string with the backup ID. InthisPointer, the application gets the pointer that was previously passed to the library through the structure.register_backup#A pointer to the function that stores the backup metadata. Accepts the
PgproBackupstructure.get_backup_by_id#A pointer to the function that gets metadata of the backup defined by
backup_id.free_backup#Frees the memory for the
PgproBackupstructure returned byget_backup_by_id.list_backup_ids#Returns the list of available backup IDs. The list contains pointers to strings with the zero character at the end. The last pointer in the list must also be zero. The memory for the list must be allocated by a C function such as
mallocorstrdupbecause the library frees the memory using thefreefunction.write_backup_status#A pointer to the function that saves the backup status. The backup status is updated separately from saving the rest of the backup metadata.
void *thisPointer#A pointer to be passed from the library to all callback functions.
CSource and CSink #
These structures are needed for reading and writing data blocks to a backup file. Arrays of pointers to these structures must be returned by the get_sources_for_backup and get_sinks_for_backup functions, respectively. Each of these structures is actually a backup file that is open for reading or writing, respectively.
/* Support structure */
typedef struct
{
unsigned char *ptr;
size_t len;
} c_buffer_t;
typedef struct
{
c_buffer_t (*read_one)(void *thisPointer);
ssize_t (*read)(char *buf, size_t size, void *thisPointer);
void (*seek)(off_t offset, void *thisPointer);
off_t (*get_offset)(void *thisPointer);
void (*close)(void *thisPointer);
void *thisPointer;
} CSource;
typedef struct
{
/* Write one Pb structure. See @PbStructs. */
size_t (*write_one)(uint8_t *buf, size_t size, void *thisPointer);
ssize_t (*write)(char *buf, size_t size, void *thisPointer);
/* Close this Sink. No more calls will be done. */
void (*close)(void *thisPointer);
void *thisPointer;
} CSink;
typedef struct
{
size_t nsinks;
CSink **array;
} CSinkArray;
typedef struct
{
size_t nsources;
CSource **array;
} CSourceArray;
In the thisPointer field, an application can pass to the structure a pointer to a structure or application class that, for instance, contains a descriptor of an open file.
Functions from the CSource structure are used for reading the backup file, while functions from the CSink structure are used for writing the backup file. Each of these structures currently has two functions for that. The read_one and write_one functions perform lower-level operations with a data block. write_one saves the block size, while read_one first reads the block size and then the data block of this size.
read and write functions are used for simpler implementation of reading/writing. Their arguments are similar to those of common functions to work with files. Processing of the block size is done inside the library. These functions must return the size of the read/written data or 1 in case of error.
The seek function is optional and currently only works together with file maps. If implementing seek would be too costly for your storage system, you can omit it.
The get_offset function returns the current read position in the specified output target (sink).
The close function closes the file.
PgproBackup #
Backup metadata is passed in this structure.
typedef struct
{
BackupStatus backup_status;
BackupMode backup_mode; /* Mode - one of BACKUP_MODE_xxx */
char *backup_id; /* Identifier of the backup. */
char *parent_backup_id; /* Identifier of the parent backup. */
BackupTimeLineID tli; /* timeline of start and stop backup lsns */
BackupXLogRecPtr start_lsn; /* backup's starting transaction log location */
BackupXLogRecPtr stop_lsn; /* backup's finishing transaction log location */
BackupTimestampTz start_time; /* UTC time of backup creation */
BackupTransactionId minxid; /* min Xid for the moment of backup start */
BackupMultiXactId
minmulti; /* min multixact for the moment of backup start */
bool stream; /* Was this backup taken in stream mode? I.e. does it include
all needed WAL files? */
bool from_replica; /* Was this backup taken from replica */
char *primary_conninfo; /* Connection parameters of the backup in the format
suitable for recovery.conf */
char *note;
/* For compatibility check */
uint32_t block_size;
uint32_t wal_block_size;
char *program_version;
int server_version;
size_t uncompressed_bytes; ///< Size of data and non-data files before
///< compression is applied
size_t data_bytes; ///< Size of data and non-data files after compression is
///< applied
CompressAlg compress_alg;
int compress_level;
BackupTimestampTz
end_time; /* the moment when backup was finished, or the moment
* when we realized that backup is broken */
BackupTimestampTz
end_validation_time; /* UTC time when validation finished */
BackupSource backup_source;/* direct, base or pro backup method*/
size_t wal_bytes;// not used in pb3
BackupTimestampTz recovery_time;
} PgproBackup;
After execution of the backup function, the library calls a callback function register_backup, where the filled-in PgproBackup structure is passed. Software engineers can save the passed information at their discretion.
To get information on an existing backup, the library uses a callback function get_backup_by_id. From this function, the application must return a pointer to the PgproBackup structure with the metadata of the backup having the specified ID or a zero pointer in case of error.
To free the memory for the PgproBackup structure, the application must call the callback function free_backup.
ProBackupApiInfo #
This structure contains the following libpgprobackup API information:
libpgprobackup version:
Version components (major, minor, patch)
User-displayable version string
Supported compression algorithms
Compiler version
Operating system version
Build type
typedef struct tag_ProBackupApiInfo {
const int pbk_ver_major;
const int pbk_ver_minor;
const int pbk_ver_patch;
/* User-visible probackup lib version. */
const char *version;
/* Used for dynamic linking */
const int dynamic_api_version;
/* List of supported compressions. */
const char **supported_compressions;
/* Compiler info */
const char *compiler_info;
/* OS info */
const char *os_info;
/* Release/Debug */
const char *build_type;
} ProBackupApiInfo;
dynamic_api_version helps to prevent incompatible versions of the library from being used by clients. supported_compressions is a null-terminated list of supported compression algorithms.
The structure is statically allocated — applications must not attempt to free its memory.
Use get_api_info to get a pointer to this structure.
Command Options #
This section lists structures that are used to pass options to the commands. For more details, see the library header file probackup_lib.h.
connectOptionsLib #
The following structure defines options to connect to the Postgres Pro server:
typedef struct connectOptionsLib
{
/* The database name. */
const char *pgdatabase;
/* Name of host to connect to. */
const char *pghost;
/* Port number to connect to at the server host, or socket file name
* extension for Unix-domain connections.*/
const char *pgport;
/* PostgreSQL user name to connect as. */
const char *pguser;
/* Password to be used if the server demands password authentication. */
const char *password;
} ConnectOptionsLib;
backupOptionsLib #
The structure below defines options to create a backup. Note that the FULL and DELTA backup modes are only supported so far.
typedef struct backupOptionsLib
{
/* Number of threads, if backup mode supports multithreading */
int num_threads;
/* Backup mode PAGE, PTRACK, DELTA, AUTO, FULL*/
BackupMode backup_mode;
/* Backup source DIRECT, BASE or PRO */
BackupSource backup_source;
/* For DIRECT source is required to set up PGDATA. It is not required for
* other sources */
const char *pgdata;
/* Backup Id if you wants to use custom id, otherwise it will be generated a
* unique id using datetime of creation */
const char *backup_id;
/* Id of parent backup. It is not required for FULL backup mode */
const char *parent_backup_id;
/* Name of replication slot, if you use custom slot created by
* pg_create_physical_replication_slot(). Otherwise will be used auto
* generated slot */
const char *replication_slot;
bool create_slot;
const char *backup_note;
/* If true, then WAL will be sent in stream mode, otherwise in archive mode
*/
bool stream_wal;
/* Progress flag. If true progress will be logged */
bool progress;
const char *external_dir_str;
/* Verify check sums. It is available only if checksums are enabled on
* PostgresPro server */
bool verify_checksums;
/* Compression algorithm, that is used for sending data between PostgresPro
* server and libpgprobackup */
CompressAlg compress_alg;
/* Compression level, that is used for sending data between PostgresPro
* server and libpgprobackup */
int compress_level;
/* Wait timeout for WAL segment archiving */
uint32_t archive_timeout;
/* Number of backup segment files. */
uint32_t num_segments;
/* Should we send raw 8k pages, or package them into larger groups. */
TransferMode transfer_mode;
/* Number of threads which write into segments. */
uint32_t num_write_threads;
/* Number of threads used for backup validation. */
uint32_t num_validate_threads;
} BackupOptionsLib;
restoreOptionsLib #
The following structure defines options to restore from a backup. They are also used for backup validation:
typedef struct restoreOptionsLib
{
/* Number of threads */
uint32_t num_threads;
/* Path to pgdata for restoration */
const char *pgdata;
/* Backup ID for restoration */
char *backup_id;
/* Progress flag. If true progress will be logged */
bool progress;
/* Skip external directories */
bool skip_external_dirs;
const char *external_mapping;
const char *tablespace_mapping;
const char *db_str_oids;
const char *db_str_names;
PartialRestoreType restoreTyp
/* Should we verify postgres page checksums */
bool verify_checksums;
/* Restore command to write in postgresql.auto.conf */
/* https://postgrespro.ru/docs/enterprise/16/runtime-config-wal#GUC-RESTORE-COMMAND */
const char *config_content;
/* Need recovery signal */
bool need_recovery_signal;
/* Need standby signal */
bool need_standby_signal;
/* No synchronization */
bool no_sync;
/* Number of threads to write restored data */
uint32_t num_write_threads;
/* Number of threads used for validation */
uint32_t num_validate_threads;
} RestoreOptionsLib;
mergeOptionsLib #
The following structure defines options to merge backups:
typedef struct mergeOptionsLib
{
/* Number of threads */
int num_threads;
/* Path to pgdata to restore to */
const char *pgdata;
/* Incremental backup ID for the merge */
const char *backup_id;
/* Target backup ID for the merge */
const char *target_backup_id;
/* Progress flag. If true progress will be logged */
bool progress;
/* ID of the last increment */
const char *merge_from_id;
/* Time interval within which to merge backups */
int interval;
/* Number of threads to write merged data */
uint32_t num_write_threads;
/* Number of threads used for validation */
uint32_t num_validate_threads;
} MergeOptionsLib;
Constants #
BackupMode #
/*
Backup Mode is how backup is taken.
All DIFF modes require parent backup id passed in the BackupOptions.
Parent backup id is ignored in the FULL mode.
DIFF_AUTO returns selected mode in the metadata. Tentatively it prefers
DIFF_PAGE if WAL summarization is available, if not it tries to do
DIFF_PTRACK if ptrack is enabled and finally it falls back to DIFF_DELTA.
In case when even DIFF_DELTA is not possible (no parent full backup exists)
FULL backup is taken.
*/
typedef enum BackupMode
{
BACKUP_MODE_INVALID = 0,
BACKUP_MODE_DIFF_PAGE, /* incremental page backup */
BACKUP_MODE_DIFF_PTRACK, /* incremental page backup with ptrack system */
BACKUP_MODE_DIFF_DELTA, /* incremental page backup with lsn comparison */
BACKUP_MODE_DIFF_AUTO, /* library selects diff backup mode automatically */
BACKUP_MODE_FULL /* full backup */
} BackupMode;
CompressAlg #
/*
* Compression mode which is used to transfer data between PG server and the client lib.
* Default is NONE_COMPRESS.
*/
typedef enum CompressAlg
{
NONE_COMPRESS = 0,
ZLIB_COMPRESS,
LZ4_COMPRESS,
ZSTD_COMPRESS,
} CompressAlg;
BackupSource #
/**
Backup Source is a method used by the client to access PGDATA.
*/
typedef enum
{
/*
* Direct access. The client reads data files directly.
* Opens normal connection to execute PG_BACKUP_START/STOP.
* Local file access. Multithreaded. No special PostgresPro edition
* required.
*/
BACKUP_SOURCE_DIRECT,
/*
* Uses pg_basebackup protocol.
* Opens replication connection.
* Remote file access. No special PostgresPro edition required.
*/
BACKUP_SOURCE_BASE_BACKUP,
/*
* Uses pg_probackup protocol.
* Opens replication connection.
* Remote file access. Multithreaded. Only works with PostgresPro builds.
* Supported PostgresPro versions start with ent-15.
*/
BACKUP_SOURCE_PRO_BACKUP
} BackupSource;