Название
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
.
Функции
Библиотека libprobackup содержит функции, описанные ниже. При вызове функций библиотеки они принимают структуры с параметрами команд и структуру с указателями на функции, которые работают с файлами и метаданными.
- bool
backup
( ConnectOptionsLib *conn_opt
, BackupOptionsLib *backup_opt
, MetadataProviderLib *metadata
); Подключается к локальному или удалённому серверу и выполняет резервное копирование. Возвращает
true
в случае успеха иfalse
в случае ошибки.Аргументы:
conn_opt
— указатель на структуру ConnectOptionsLib, которая задаёт параметры подключения к серверу Postgres Pro, такие какpghost
,pgdatabase
,pgport
,pguser
,password
.backup_opt
— указатель на структуру BackupOptionsLib, которая содержит параметры резервного копирования, такие как режим резервного копирования или количество потоков.metadata
— указатель на структуру MetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.
- bool
restore
( RestoreOptionsLib *restore_opt
, MetadataProviderLib *metadata
); Восстанавливает данные из резервной копии с использованием параметров, переданных в соответствующих структурах, в локальную файловую систему. Возвращает
true
в случае успеха иfalse
в случае ошибки.Аргументы:
restore_opt
— указатель на структуру RestoreOptionsLib, содержащую параметры для восстановления из резервной копии.metadata
— указатель на структуру MetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.
- bool
validate
( RestoreOptionsLib *restore_opt
, MetadataProviderLib *metadata
, boolwithParents
); Проверяет, что все файлы, необходимые для восстановления кластера из резервной копии, присутствуют и не повреждены. Если параметр
withParents
установлен в значение true, также проверяются все резервные копии в цепочке родительских. Возвращаетtrue
в случае успеха иfalse
в случае ошибки.Аргументы:
restore_opt
— указатель на структуру RestoreOptionsLib, содержащую параметры для проверки целостности резервной копии.metadata
— указатель на структуру MetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.withParents
— логическое значение, определяющее, необходимо ли также проверять родительские резервные копии.
- bool
merge
( MergeOptionsLib *merge_opt
, MetadataProviderLib *metadata
); Объединяет цепочку инкрементных резервных копий в одну полную. Во время объединения создаётся новая полная резервная копия, включающая все родительские. Если у родительских копий нет дополнительных зависимостей, они удаляются после успешного объединения. Возвращает
true
в случае успеха иfalse
в случае ошибки.Аргументы:
merge_opt
— указатель на структуру MergeOptionsLib, содержащую параметры для объединения резервных копий.metadata
— указатель на структуру MetadataProviderLib, которая предоставляет функции-обработчики для метаданных резервных копий и файловых операций.
- uint64_t
identify_system
( ConnectOptionsLib *conn_opt
); Возвращает уникальный идентификатор сервера Postgres Pro. Он используется для управления резервными копиями и их восстановления на системном уровне.
Аргументы:
conn_opt
— указатель на структуру ConnectOptionsLib, которая задаёт параметры подключения к серверу Postgres Pro.
- void
set_probackup_logger
( Loggerinfo
, Loggerwarning
, Loggererror
); Определяет три функции-обработчика записи в журнал, которые libpgprobackup будет использовать для вывода информационных сообщений, предупреждений или сообщений об ошибках. Каждая из этих функций должна принимать строковый параметр с сообщением, передаваемым библиотекой.
Аргументы:
info
— указатель на функцию, которая будет обрабатывать информационные сообщения.warning
— указатель на функцию, которая будет обрабатывать предупреждения.error
— указатель на функцию, которая будет обрабатывать сообщения об ошибках.
Структуры для работы с файлами
Библиотека получает обратную связь от приложения через структуру типа MetadataProviderLib, которая должна содержать указатели на функции, работающие с файлами и метаданными.
Используются обработчики из библиотеки к функциям, переданным приложением. Указатели на функции передаются в библиотеку через структуру MetadataProviderLib. Операции чтения или записи файлов определяются в структурах CSource и Csink, соответственно.
Для обратной связи от приложения структуры библиотеки содержат указатель void *thisPointer
, в котором приложение может хранить указатель на свою собственную функцию или экземпляр класса. Этот указатель передаётся в функции-обработчики при их вызове из библиотеки.
MetadataProviderLib
Указатель на эту структуру передаётся всем основным функциям libprobackup, таким как backup, restore, validate, и merge. Эта структура определяет методы для работы с данными резервных копий, для записи и чтения метаданных резервных копий, а также для получения списка резервных копий.
typedef struct { CSink *(*get_sink_for_backup)(const char *backup_id, void *thisPointer); CSource *(*get_source_for_backup)(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_sink_for_backup
Указатель на функцию, которая возвращает указатель на структуру CSync (см. CSource и Csink для получения более подробной информации). Требуется для записи информации в резервную копию.
backup_id
содержит строку с идентификатором резервной копии. ВthisPointer
приложение получает указатель, который ранее был передан в библиотеку через структуру.get_source_for_backup
Указатель на функцию, которая возвращает указатель на структуру 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_source_for_backup и get_sink_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 (*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;
В поле thisPointer
приложение может передать в структуру указатель на структуру или класс приложения, который, например, содержит дескриптор открытого файла.
Функции из структуры CSource используются для чтения файла резервной копии, а функции из структуры CSink — для записи. Для этого каждая из этих структур в настоящее время имеет по две функции. Функции read_one
и write_one
выполняют операции низкого уровня с блоком данных. write_one
сохраняет размер блока, в то время как read_one
сначала читает размер блока, а затем сам блок данных этого размера.
Функции read
и write
используются для упрощённой реализации чтения/записи. Их аргументы аналогичны аргументам общих функций для работы с файлами. Обработка размера блока выполняется внутри библиотеки. Эти функции должны возвращать размер прочитанных/записанных данных или 1 в случае ошибки.
Функции 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 } PgproBackup;
После выполнения функции backup библиотека вызывает функцию-обработчик register_backup, в которую передаётся заполненная структура PgproBackup. Переданную информацию можно сохранять по своему усмотрению.
Для получения информации о существующей резервной копии библиотека использует функцию-обработчик get_backup_by_id. Из этой функции приложение должно вернуть указатель на структуру PgproBackup с метаданными резервной копии, имеющей указанный идентификатор, или нулевой указатель в случае ошибки.
Чтобы освободить память для структуры PgproBackup приложение должно вызвать функцию-обработчик free_backup.
Общие параметры
В этом разделе перечисляются структуры, используемые для передачи параметров командам. Для получения более подробной информации обратитесь к заголовочному файлу библиотеки 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; /* Postgres Pro 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 turn on 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; } BackupOptionsLib;
restoreOptionsLib
Следующая структура определяет параметры для восстановления из резервной копии. Эти параметры также используются для проверки резервной копии:
typedef struct restoreOptionsLib { /* Number of threads */ int 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; /* Checksum page verification */ 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; } 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; } 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;