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;

Здесь:

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.

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;