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;

Здесь:

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:

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, чтобы получить указатель на эту структуру.

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 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;
	/* 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 checksumse */
	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;