Утилита резервного копирования pg_probackup

Описание

pg_probackup — это утилита для управления резервным копированием и восстановлением кластеров баз данных. Она предназначена для выполнения периодических резервных копий экземпляра, что позволяет восстановить сервер в случае сбоя.

Утилита pg_probackup поставляется в пакете компонента Pangolin Backup Tools в рамках дистрибутива продукта.

Внимание!

При активном TDE сохранение возможно только при запуске утилиты pg_probackup непосредственно на сервере СУБД. Получение копии через pg_probackup при активном TDE на клиенте (другом хосте) невозможно.

Возможности

pg_probackup предоставляет ряд возможностей, упрощающих построение стратегий резервного копирования и работу с большими объемами данных:

Возможность	Описание
Инкрементное копирование	Резервное копирование на уровне страниц, позволяющее экономить дисковое пространство и ускорять процессы резервирования и восстановления. Поддерживаются три режима, что позволяет подобрать стратегию под характер изменений данных
Инкрементное восстановление	Восстановление на уровне страниц с повторным использованием неизмененных страниц в целевой директории, что значительно ускоряет процесс
Объединение (Merge)	Реализация стратегии «инкрементально обновляемых резервных копий», устраняющей необходимость в периодических полных копиях
Валидация	Автоматическая проверка согласованности данных и проверка резервных копий по запросу без фактического восстановления
Верификация	Проверка целостности экземпляра с помощью команды `checkdb`
Хранение (Retention)	Управление архивами WAL и резервными копиями по политике хранения (по времени восстановления, количеству копий или TTL для конкретной копии). Просроченные копии можно удалять или объединять
Параллельная работа	Выполнение резервного копирования, восстановления, слияния, удаления, верификации и валидации в нескольких потоках
Сжатие	Хранение данных резервной копии в сжатом виде для экономии места
Дедупликация	Пропуск копирования неизмененных служебных файлов (например, `_vm` или `_fsm`)
Удаленные операции	Резервное копирование и восстановление экземпляра, расположенного на удаленном сервере
Резервная копия со standby-сервера	Создание копии с реплики, что позволяет избежать нагрузки на узел мастер
Внешние директории	Резервное копирование файлов и каталогов, находящихся за пределами `PGDATA` (скрипты, конфигурационные файлы, лог-файлы, SQL-выгрузки)
Каталог резервных копий	Список резервных копий и метаданных в формате `plain text` или JSON
Каталог архива	Список всех линий времени WAL и их метаданных в формате `plain text` или JSON
Частичное восстановление	Восстановление только указанных баз или исключение отдельных баз из восстановления
Фоновое резервное копирование	Создание консистентной резервной копии без остановки функционирования основной БД. Пользовательские сессии могут продолжать работу во время выполнения резервного копирования.

Каталог резервных копий

Утилита pg_probackup хранит резервные копии и WAL-файлы, необходимые для восстановления до заданной точки во времени (PITR), хранящиеся в каталоге резервных копий. Для разных экземпляров можно выделять отдельные подкаталоги внутри одного каталога.

Типы резервного копирования

pg_probackup поддерживает 2 вида резервного копирования:

Полное (Full) — содержит все файлы данных, необходимые для восстановления кластера с нуля.
Инкрементное (Incremental) — хранит только измененные с момента предыдущей копии данные, что уменьшает размер резервной копии и ускоряет его создание.

Поддерживаются режимы:
1. PAGE — анализируются все WAL-файлы с момента последней резервной копии, и копируются только страницы, упомянутые в WAL-записях. Требуется полный набор WAL-файлов с момента предыдущей копии.
2. DELTA — читаются все файлы данных в PGDATA, но копируются только измененные страницы. Непрерывное архивирование не требуется, но нагрузка на диск сравнима с резервным копированием полного типа.
3. PTRACK — СУБД Pangolin помечает измененные страницы в специальном битмапе. Требует расширение ptrack. Нагрузка на сервер минимальная, а резервные копии создаются быстрее.

Режим резервного копирования задается с помощью параметра -b <backup-mode>.

Независимо от типа резервного копирования, все копии поддерживают два варианта доставки WAL:

Автономная (stream) — необходимые WAL-файлы передаются через протокол репликации и включаются в резервную копию. Даже при отсутствии непрерывного архивирования восстановление возможно.
Архивная (archive) — используется механизм непрерывного архивирования. Для восстановления требуется полный набор WAL-файлов, сохраненных в архиве.

Параметры

Утилита pg_probackup поддерживает следующие параметры:

Общие параметры

Общие параметры, которые могут использоваться с различными командами утилиты:

--dry-run

Выполняет тестовый запуск команды без внесения изменений (не создаются, не удаляются и не перемещаются файлы). Пропускается потоковая трансляция WAL.

-B <backup-path>

Задает путь к каталогу резервных копий. Можно установить один раз через переменную окружения BACKUP_PATH.

-D <pgdata-path>

Путь к каталогу данных кластера (обязателен только для add-instance). Остальные команды могут использовать переменную PGDATA или конфигурационный файл.

-i <backup-id>

Уникальный идентификатор резервной копии.

--instance=<instance_name>

Имя экземпляра СУБД Pangolin.

--backup-pg-log

Включение в резервную копию каталога log. Этот каталог обычно содержит журналы сообщений сервера. По умолчанию каталог log в копию не включается. Параметр используется только для команды backup.

-j <num-threads>

Количество параллельных потоков для команд backup, restore, merge, validate, checkdb и archive-push.

--progress

Отображение прогресса выполнения.

--help

Подробная справка по параметрам команды.

--format

Формат вывода для команды show (plain, json).

Параметры создания

Используются с командой backup:

-b <backup-mode>

Выбор режима резервного копирования. Поддерживаются следующие режимы: FULL, DELTA, PAGE и PTRACK.

Параметры точки восстановления

Используются с командами restore или validate при непрерывном архивировании WAL:

--recovery-target=<immediate|latest>

Момент завершения восстановления: сразу (immediate) или после применения всех сегментов WAL (latest).

--recovery-target-timeline=<timeline>

Линия времени: immediate, latest или числовое значение.

--recovery-target-lsn=<lsn>

LSN до точки восстановления.

--recovery-target-name=<target-name>

Именованная точка сохранения.

--recovery-target-time=<time>

Точка времени для восстановления.

--recovery-target-xid=<xid>

Идентификатор транзакции для восстановления.

--recovery-target-inclusive=<boolean>

Включить целевую точку (true) или остановиться перед ней (false).

--recovery-target-action=<pause|promote|shutdown>

Действие сервера при достижении цели:

pause — остановка и ожидание решения администратора (используется по умолчанию);
promote — переключение экземпляра в основную роль;
shutdown — завершение работы сервера.

Параметры сохранения

Применяются с командами backup и delete:

--retention-redundancy=<retention-redundancy>

Количество полных копий для хранения (0 — отключено).

--retention-window=<retention-window>

Окно восстановления в днях (0 — отсутствует).

--wal-depth=<wal-depth>

Количество копий WAL для восстановления PITR (0 — отключено).

--delete-wal

Удаление файлов WAL, которые не являются необходимыми для восстановления кластера из имеющихся резервных копий.

--delete-expired

Удаление резервной копии, не удовлетворяющей политике хранения.

--merge-expired

Объединение старых инкрементальных копий в одну, удовлетворяющую требованиям политики хранения, с ее родительскими, срок хранения которых истек.

Параметры закрепления

Используются с командами backup и set-backup:

--ttl=interval

Время закрепления копии (0 — отмена закрепления).

--expire-time=<wal-depth>

Момент окончания хранения (формат ISO-8601).

Параметры ведения журнала

Могут применяться к любой команде:

--no-color

Отключение цветового выделения warning/error.

--log-level-console=<log-level-console>

Уровень сообщений для консоли (verbose, log, info, warning, error, off – по умолчанию).

--log-filename=<log-filename>

Шаблон имени файлов журнала.

--error-log-filename=<error-log-filename>

Отдельный файл для ошибок.

--log-directory=<log-directory>

Каталог для журналов (по умолчанию $BACKUP_PATH/log/).

--log-format-console=<log-format-console>

Формат журнала консоли (text или json).

--log-format-file=<log-format-file>

Формат файлов журнала (plain или json).

--log-rotation-size=<log-rotation-size>

Максимальный размер файла для ротации (0 — отключено).

--log-rotation-age=<log-rotation-age>

Максимальное время жизни файла для ротации (0 — отключено).

Параметры подключения

Используются с командами backup, catchup и checkdb.

-d <dbname> / PGDATABASE

База для подключения.

-h <host> / PGHOST

Узел сервера (по умолчанию localhost).

-p <port> / PGPORT

Порт подключения (по умолчанию 5432).

-U <username> / PGUSER

Имя пользователя.

-w / --no-password

Отсутствие запроса пароля.

-W / --password

Запрос пароля (устаревший параметр).

Параметры сжатия

Применяются с командами backup и archive-push:

--compress-algorithm=<compress-algorithm>

Алгоритм сжатия: zlib, lz4, zstd, pglz, none (по умолчанию none).

--compress-level=<compress-level>

Уровень сжатия, зависит от алгоритма (обычно 1–9, чем выше — тем сильнее сжатие, но медленнее).

--compress

Алгоритм по умолчанию с уровнем 1 (приоритет: zlib, pglz, lz4, zstd).

Параметры архивации

Используются с командами archive-push и archive-get:

--wal-file-path=<wal-file-path>

Путь к файлу WAL.

--wal-file-name=<wal-file-name>

Имя файла WAL.

--overwrite

Перезапись файлов WAL.

--batch-size=<batch_size>

Максимальное количество WAL-файлов, которое может копироваться за один раз при archive-push или archive-get. Ускоряет архивирование и восстановление.

--archive-timeout=<archive-timeout>

Интервал времени, после которого незавершенные .part файлы считаются потерянными. По умолчанию — 300 секунд. Используется только с archive-push.

--no-ready-rename

Параметр, запрещающий переименование файлов состояния в archive_status. Полезен при нескольких командах в archive_command. Только для archive-push.

--no-sync

Параметр, отключающий принудительную запись WAL-файлов на диск, что ускоряет архивирование, но может привести к повреждению архива при сбое системы. Только для archive-push.

--no-validate-wal

Параметр, отключающий проверку предзагруженных WAL-файлов перед использованием, ускоряя восстановление. Используется только с archive-get.

Параметры удаленного режима

Параметры, отвечающие за удаленное выполнение операций pg_probackup по SSH. Применяются с командами add-instance, set-config, backup, catchup, restore, archive-push и archive-get.

--remote-proto=<protocol>

Протокол удаленного выполнения операций. Поддерживается только SSH. Возможные значения:

ssh — включение удаленного режима через SSH (по умолчанию);
none — явное отключение удаленного режима.

Можно не задавать, если указан --remote-host.

--remote-host=<host>

Имя или IP-адрес удаленного сервера.

--remote-port=<port>

Порт на удаленном сервере. По умолчанию: 22.

--remote-user=<username>

Имя пользователя для SSH-соединения на удаленной системе. Если не указано, используется текущий пользователь.

--remote-path=<path>

Каталог установки pg_probackup на удаленной системе.

--ssh-options=ssh-options

Строка дополнительных параметров SSH.

Параметры потоковой передачи WAL

Применяются с командами backup и catchup:

--stream

Создание потоковой резервной копии (STREAM), включая в нее все необходимые файлы WAL, получаемые от сервера по протоколу репликации.

--temp-slot=<true|false|on|off>

Создание временного слота физической репликации для передачи WAL с архивируемого экземпляра. По умолчанию --temp-slot включен. Это гарантирует, что все нужные сегменты WAL будут доступны, если в процессе копирования произойдет переключение сегментов WAL. Этот параметр может использоваться только вместе с параметром --stream. По умолчанию имя слота — pg_probackup_slot. Чтобы его поменять, воспользуйтесь параметром --slot/-S и явно укажите --temp-slot или --temp-slot=<true|on>.

-S <slot_name> / --slot=<slot_name>

Указание слота репликации, к которому будет выполнено подключение для передачи WAL. Этот параметр можно указать только вместе с параметром --stream.

Параметры удаленного архива WAL

Параметры для настройки аргументов archive-get при восстановлении PITR или копий типа ARCHIVE в удаленном режиме.

--archive-host=<host>

Имя или IP-адрес сервера для команды archive-get.

--archive-port=<port>

Порт удаленного сервера для archive-get. По умолчанию: 22.

--archive-user=<username>

Имя пользователя для команды archive-get.

Параметры инкрементального восстановления

Параметры, влияющие на инкрементальное восстановление кластера. Используются с командой restore.

-I / --incremental-mode=<none|checksum|lsn>

Режим инкрементального восстановления. Возможные значения:

CHECKSUM — замена только страницы с неподходящей контрольной суммой и LSN;
LSN — замена только страницы с LSN больше точки расхождения;
NONE — обычное восстановление.

-R / --restore-as-replica

Формирование минимального файла конфигурации восстановления, предназначенного для упрощения настройки ведомого сервера. Если для подключения репликации необходим пароль, его следует отдельно указать в параметре primary_conninfo.

--primary-conninfo=<primary_conninfo>

Установка заданного значения для параметра primary_conninfo. Это значение учитывается только при использовании параметра -R.

-S / --primary-slot-name=<slot_name>

Установка заданного значения для параметра primary_slot_name. Это значение учитывается только при использовании параметра -R.

Параметры частичного восстановления

Параметры, определяющие, какие базы данных включать или исключать при восстановлении. Используются с командой restore.

--db-exclude=<dbname>

База данных, исключаемая из восстановления. Можно указать несколько раз.

--db-include=<dbname>

База данных, включаемая в восстановление. Остальные базы не восстанавливаются (кроме template0 и template1). Можно указать несколько раз.

Установка

примечание

При установке СУБД Pangolin с помощью скриптов автоматизации утилита pg_probackup устанавливается автоматически.

Установите пакет pangolin-backup-tools-venv (обязательная зависимость для pangolin-backup-tools):

SberLinux, РЕД ОС, CentOS
Astra Linux
Альт СП

sudo dnf install pangolin-backup-tools-venv-{version_component}-{OS}.x86_64.rpm

sudo apt install pangolin-backup-tools-venv-{version_component}_amd64.deb

sudo apt-get install pangolin-backup-tools-venv-{version_component}-{OS}.x86_64.rpm

Пример заполненной команды:

cd distributive/3rdparty/
tar -xzf 3rdparty.tar.gz -C ./
sudo dnf install -y pangolin-backup-tools-venv-2.1.1-sberlinux9.x86_64.rpm

Установите пакет компонента:

SberLinux, РЕД ОС, CentOS
Astra Linux
Альт СП

sudo dnf install pangolin-backup-tools-{version_component}-{OS}.x86_64.rpm

sudo apt install pangolin-backup-tools-{version_component}_amd64.deb

sudo apt-get install pangolin-backup-tools-{version_component}-{OS}.x86_64.rpm

Пример заполненной команды:

cd distributive
sudo dnf install -y pangolin-backup-tools-2.1.1-sberlinux9.x86_64.rpm

Подсказка

Путь к файлу настроек по умолчанию можно изменить используя переменную окружения BACKUP_TOOLS_CONFIG_PATH_FILE.

Настройка

Инициализация и конфигурация

Хранилище резервных копий уже проинициализировано и располагается в /pgarclogs/{version}/.

Создание нового каталога для хранения резервных копий

Для инициализации каталога резервных копий выполните команду:

pg_probackup init -B <backup-path>

Если указанный каталог резервных копий уже существует, он должен быть пустым, иначе pg_probackup завершит работу с ошибкой. Пользователь, запускающий утилиту, должен иметь полный доступ к каталогу резервных копий.

Определение экземпляра

Для определения копируемого экземпляра, выполните команду:

pg_probackup add-instance -B <backup-path> -D <pgdata-path> --instance=<instance_name>
                [--external-dirs=<external-directories-pathsh>]
                [--remote-proto] [--remote-host]
                [--remote-port] [--remote-path] [--remote-user]
                [--ssh-options]

Ручная настройка конфигурации

Для задания или изменения конфигурационных параметров экземпляра резервного копирования, используйте команду:

pg_probackup set-config -B <backup-path> --instance=<instance_name>
                [-D <pgdata-path>]
                [--external-dirs=<external-directories-pathsh>]
                [--log-level-console=<log-level-console>]
                [--log-level-file=<log-level-file>]
                [--log-format-file=<log-format-file>]
                [--log-filename=<log-filename>]
                [--error-log-filename=<error-log-filename>]
                [--log-directory=<log-directory>]
                [--log-rotation-size=<log-rotation-size>]
                [--log-rotation-age=<log-rotation-age>]
                [--retention-redundancy=<retention-redundancy>]
                [--retention-window=<retention-window>]
                [--wal-depth=<wal-depth>]
                [--compress-algorithm=<compress-algorithm>]
                [--compress-level=<compress-level>]
                [--archive-timeout=timeout]
                [-d <dbname>] [-h <host>] [-p <port>] [-U <username>]
                [--remote-proto] [--remote-host]
                [--remote-port] [--remote-path] [--remote-user]
                [--ssh-options]
                [--restore-command=cmdline] [--archive-host=destination]
                [--archive-port=<port>] [--archive-user=<username>]

Команда добавляет заданные параметры соединения, сжатия, хранения, ведения журнала и указания внешних каталогов в конфигурационный файл pg_probackup.conf либо изменяет ранее заданные значения.

Редактировать pg_probackup.conf вручную не рекомендуется.

По умолчанию все резервные копии, которые создает pg_probackup, сохраняются в предназначенном для них каталоге.

Настройка СУБД Pangolin для организации резервного копирования

При установке СУБД Pangolin автоматизированным способом инсталлятор автоматически устанавливает и настраивает все необходимые для организации резервного копирования, расширения и утилиты:

Устанавливает утилиту pg_probackup.
Инициализирует локальный каталог резервных копий:
```
pg_probackup init -B $PGBACKUP
```
Определяет копируемый экземпляр (по умолчанию) резервных копий:
```
pg_probackup add-instance -B $PGBACKUP -D $PGDATA --instance=<instance_name>
```

Устанавливает параметры БД:

wal_level = replica
hot_standby = on
full_pages_writes = on
archive_mode = always
archive_command = 'pg_probackup archive-push -B <backup-path> --instance <instance_name> --wal-file-path=%p --wal-file-name=%f --compress --overwrite -j 4'
archive_timeout = 180

Добавляет параметры работы pg_probackup:

pg_probackup set-config -B $PGBACKUP -D $PGDATA --instance <instance_name> -d <dbname> -h <host> -p <port> -U <username>

Просмотр конфигурации pg_probackup

Для просмотра текущей конфигурации резервной копии используйте команду:

pg_probackup show-config -B /pgarclogs/{version}/ --instance=clustername [--format=plain|json]

Пример вывода:

# Backup instance information
pgdata = /pgdata/07/data
system-identifier = 6900845675447083568
xlog-seg-size = 16777216
# Connection parameters
pgdatabase = postgres
pghost = <IP-Address>
pgport = 5433
pguser = backup_user
# Replica parameters
replica-timeout = 5min
# Archive parameters
archive-timeout = 5min
# Logging parameters
log-level-console = INFO
log-level-file = OFF
log-format-console = PLAIN
log-format-file = PLAIN
log-filename = pg_probackup.log
log-rotation-size = 0TB
log-rotation-age = 0d
# Retention parameters
retention-redundancy = 0
retention-window = 0
wal-depth = 0
# Compression parameters
compress-algorithm = none
compress-level = 1
# Remote access parameters
remote-proto = ssh

Управление

Создание резервной копии

Для создания резервной копии выполните следующую команду:

pg_probackup backup -B <backup-path> -b <backup-mode> --instance=<instance_name>
                [-D <pgdata-path>] [-C]
                 [--stream [-S <slot-name>] [--temp-slot]]
                 [--backup-pg-log] [-j <num-threads>] [--progress]
                 [--no-validate] [--skip-block-validation]
                 [--external-dirs=<external-directories-pathsh>]
                 [--no-sync]
                 [--log-level-console=<log-level-console>]
                 [--log-level-file=<log-level-file>]
                 [--log-format-console=<log-format-console>]
                 [--log-format-file=<log-format-file>]
                 [--log-filename=<log-filename>]
                 [--error-log-filename=<error-log-filename>]
                 [--log-directory=<log-directory>]
                 [--log-rotation-size=<log-rotation-size>]
                 [--log-rotation-age=<log-rotation-age>] [--no-color]
                 [--delete-expired] [--delete-wal] [--merge-expired]
                 [--retention-redundancy=<retention-redundancy>]
                 [--retention-window=<retention-window>]
                 [--wal-depth=<wal-depth>]
                 [--compress]
                 [--compress-algorithm=<compress-algorithm>]
                 [--compress-level=<compress-level>]
                 [--archive-timeout=<archive-timeout>]
                 [-d <dbname>] [-h <host>] [-p <port>] [-U <username>]
                 [-w --no-password] [-W --password]
                 [--remote-proto] [--remote-host]
                 [--remote-port] [--remote-path] [--remote-user]
                 [--ssh-options]
                 [--ttl=interval] [--expire-time=<wal-depth>] [--note=text]

Примеры

Создание инкрементальной резервной копии для экземпляра с использованием 4 параллельных потоков, сжатием данных, добавлением потоковых файлов WAL и автоматическим удалением устаревших копий в соответствии с политикой хранения:

pg_probackup backup -B /pgarclogs/{version}/ --instance=<instance_name> -j4 --backup-mode=DELTA --compress --stream --delete-expired

Создание полной резервной копии для указанного экземпляра с использованием 4 параллельных потоков, сжатием данных, добавлением потоковых файлов WAL и автоматическим удалением устаревших копий в соответствии с политикой хранения:

pg_probackup backup -B /pgarclogs/{version}/ --instance=<instance_name> -j4 --backup-mode=FULL --compress --stream --delete-expired

Политика хранения

Для экономии дискового пространства можно задать политику хранения резервных копий, при которой устаревшие или избыточные копии будут автоматически удаляться.

Настройка политики хранения выполняется через файл pg_probackup.conf с помощью команды set-config, где можно указать одну или несколько следующих переменных:

--retention-redundancy=<retention-redundancy>

Определяет минимальное количество полных резервных копий, которые необходимо сохранять в каталоге.

--retention-window=<retention-window>

Задает минимальный временной диапазон, за который должна быть доступна хотя бы одна резервная копия. Значение указывается в днях. Например, при retention-window=7 сохраняется как минимум одна копия старше 7 дней вместе с необходимыми файлами WAL и всеми последующими копиями.

Если заданы оба параметра (--retention-redundancy и --retention-window), очистка каталога копий учитывает оба условия. Например, комбинация --retention-redundancy=2 и --retention-window=7 означает, что pg_probackup сохранит не менее двух полных копий, а также все копии, необходимые для восстановления за последние семь дней:

pg_probackup set-config -B <backup-path> --instance=<instance_name> --retention-redundancy=2 --retention-window=7

Очистку каталога в соответствии с политикой хранения можно выполнить с помощью команды delete с соответствующими параметрами или командой backup — в последнем случае ненужные копии будут удалены сразу после создания новой.

Чтобы удалить резервные копии, признанные устаревшими в рамках текущей политики хранения, используйте параметр --delete-expired:

pg_probackup delete -B <backup-path> --instance=<instance_name> --delete-expired

Для одновременного удаления файлов WAL, которые больше не требуются ни одной из копий, добавьте параметр --delete-wal:

pg_probackup delete -B <backup-path> --instance=<instance_name> --delete-expired --delete-wal

Кроме того, параметры --retention-redundancy и --retention-window можно указать напрямую при запуске команд delete или backup, чтобы установить или переопределить политику хранения:

pg_probackup delete -B <backup-path> --instance=<instance_name> --delete-expired --retention-window=7 --retention-redundancy=2

Восстановление из резервной копии

Чтобы восстановить кластер баз данных из резервной копии, выполните команду:

pg_probackup restore -B <backup-path> --instance=<instance_name>
                [-D <pgdata-path>] [-i <backup-id>] [-j <num-threads>]
                 [--recovery-target-time=<time>|--recovery-target-xid=<xid>|--recovery-target-lsn=<lsn> [--recovery-target-inclusive=<boolean>]]
                 [--recovery-target-timeline=<timeline>]
                 [--recovery-target=<immediate|latest>]
                 [--recovery-target-name=<target-name>]
                 [--recovery-target-action=<pause|promote|shutdown>]
                 [--restore-command=cmdline]
                 [-R | --restore-as-replica] [--force]
                 [--primary-conninfo=<primary_conninfo>]
                 [-S | --primary-slot-name=<slot_name>]
                 [--no-validate] [--skip-block-validation]
                 [-T OLDDIR=NEWDIR] [--progress]
                 [--external-mapping=OLDDIR=NEWDIR]
                 [--skip-external-dirs] [--no-sync]
                 [-X WALDIR | --waldir=WALDIR]
                 [-I | --incremental-mode=<none|checksum|lsn>]
                 [--db-include | --db-exclude]
                 [--remote-proto] [--remote-host]
                 [--remote-port] [--remote-path] [--remote-user]
                 [--ssh-options]
                 [--archive-host=<host>]
                 [--archive-port=<port>] [--archive-user=<username>]

Внимание!

Восстановить кластер из копии можно только для копий с состоянием OK или DONE.

По умолчанию восстановление идет в оригинальные каталоги. Если восстановление выполняется на том же сервере и табличные пространства уже заняты, возникнет ошибка, так как данные должны быть восстановлены в те же директории. Чтобы перенаправить размещение табличных пространств, следует использовать параметр -T.

Если путь содержит знак =, его необходимо экранировать с помощью обратной косой черты (\=). Параметр может указываться несколько раз для переноса разных табличных пространств.

Для получения непрерывной резервной копии в конфигурации СУБД должно быть включены следующие параметры:

archive_command = 'pg_probackup archive-push -B /pgarclogs/{version} --instance=clustername --wal-file-path=%p --wal-file-name=%f --compress --overwrite -j 4 --batch-size=100'
archive_mode = 'on'
archive_timeout = '180'

Также при восстановлении в некоторых случаях (например, восстановление ведомого сервера) требуется установка дополнительного параметра:

restore_command = 'pg_probackup archive-get -B /pgarclogs/{version} --instance=clustername --wal-file-path=%p --wal-file-name=%f --compress --overwrite -j 4 --batch-size=100'

В случае кластерной конфигурации данные параметры меняются через /etc/pangolin-manager/postgres.yml. Для конфигурации standalone параметры меняются через /pgdata/{version}/data/postgresql.conf.

Параметр archive_mode требует перезапуска СУБД.

Примеры

Восстановление кластера из резервной копии с идентификатором QFEZBK в каталог данных /pgdata/{version}/data для указанного экземпляра, с использованием 4 параллельных потоков, немедленным завершением восстановления при достижении согласованного состояния и выводом информации о ходе выполнения операции:

pg_probackup restore  -B /pgarclogs/{version}/ --instance=<instance_name>  -D  /pgdata/{version}/data -i QFEZBK -j 4 --recovery-target='immediate'   --progress

Восстановление кластера из резервной копии с идентификатором QFEZBK в каталог данных /pgdata/{version}/data для указанного экземпляра, с использованием 4 параллельных потоков, с указанием целевого момента восстановления 2022-12-03 12:00:03-04 и выводом информации о ходе выполнения операции:

pg_probackup restore  -B /pgarclogs/{version}/ --instance=<instance_name>  -D  /pgdata/{version}/data -i QFEZBK -j 4 --recovery-target='2022-12-03 12:00:03-04'   --progress

Проверка резервной копии

Для проверки корректности и пригодности резервной копии для восстановления, выполните команду:

pg_probackup validate -B <backup-path> [--instance=<instance_name>]
                 [-i <backup-id>] [--progress] [-j <num-threads>]
                 [--recovery-target-time=<time>|--recovery-target-xid=<xid>|--recovery-target-lsn=<lsn> [--recovery-target-inclusive=<boolean>]]
                 [--recovery-target-timeline=<timeline>]
                 [--recovery-target-name=<target-name>]
                 [--skip-block-validation]

Например:

pg_probackup validate -B /pgarclogs/{version}/ --instance=clustername

Пример вывода:

INFO: Validate backups of the instance 'clustername'
INFO: Validating backup T1AI3F
INFO: Backup T1AI3F data files are valid
INFO: Backup T1AI3F WAL segments are valid
INFO: All backups are valid

Проверка гарантирует, что все необходимые файлы копий находятся в наличии, кластер можно восстановить до указанной точки восстановления (при наличии). Для этого команда запускается с теми же параметрами восстановления, которые будут использоваться при реальном восстановлении.

Если проверка прошла успешно, выводится сообщение об успешной валидации.

В случае ошибки будет выведено сообщение с указанием:

точки времени;
идентификатора транзакции (XID);
значения LSN, до которых возможно восстановление.

Если указан параметр -i backup-id, проверяется только одна резервная копия с указанным идентификатором.

Если -i указан вместе с параметрами --recovery-target-*, проверяется возможность восстановления этой конкретной копии до заданной точки. Если backup-id относится к инкрементальной копии, дополнительно будут проверены все родительские копии, начиная с полной.

Если параметры не заданы, проверяются все резервные копии в каталоге.

Проверка базы данных

Чтобы убедиться в отсутствии повреждений в кластере, выполните следующую команду:

pg_probackup checkdb [-B <backup-path>] [--instance=<instance_name>]
                 [-D <pgdata-path>] [--progress] [-j <num-threads>]
                 [--amcheck] [--skip-block-validation]
                 [--heapallindexed] [--checkunique]

По умолчанию pg_probackup выполняет проверку страниц автоматически в процессе создания резервной копии.

Команда checkdb позволяет запускать проверку страниц в кластере отдельно, без создания резервной копии. Для ее выполнения не требуется предварительная настройка копирования кластера в pg_probackup.

Чтобы провести проверку, приложению pg_probackup необходимо подключиться к целевому кластеру:

Обычно достаточно указать экземпляр кластера, зарегистрированный в pg_probackup.
Если параметры -B и --instance не заданы, то параметры подключения и путь к каталогу данных необходимо указать явно в командной строке или через переменные окружения.

Можно отключить физическую проверку с помощью параметра --skip-block-validation. В этом случае указывать каталог копий и каталог данных не требуется, достаточно задать только параметры подключения.

Для более глубокой диагностики можно использовать расширение amcheck (параметр --amcheck), которое выполняет проверку всех индексов во всех базах данных. Дополнительный параметр --heapallindexed позволяет убедиться, что все кортежи таблиц действительно представлены в индексах.

Просмотр списка резервных копий

Чтобы посмотреть сведения о хранилище резервных копий, выполните:

pg_probackup show -B /pgarclogs/{version}/

Пример вывода:

BACKUP INSTANCE 'clustername'
============================================================================================================================================
 Instance     Version        ID      Recovery time         Mode    WAL Mode  TLI  Time    Data   WAL  Zratio  Start LSN   Stop LSN    Status
============================================================================================================================================
 clustername      06       PYSUE8  2020-12-21 15:51:48+03  FULL    ARCHIVE   1/0   16s  9047kB  16MB    4.31  0/12000028  0/12000160  OK

Для каждой копии выдаются следующие сведения:

Параметр	Описание
Instance	Имя экземпляра СУБД Pangolin
Version	Базовая версия
ID	Идентификатор резервной копии
Recovery time	Самое раннее время, на которое можно восстановить кластер из данной копии
Mode	Режим, в котором была сделана копия. Возможные значения: `FULL` (полная), `PAGE` (страничная), `DELTA` (инкрементальная), `PTRACK` (копирование изменений)
WAL Mode	Режим доставки WAL. Возможные значения: `STREAM` (потоковый) и `ARCHIVE` (архивный)
TLI	Идентификаторы линии времени текущей копии и ее родителя
Time	Время, за которое была выполнена данная копия
Data	Объем файлов данных в этой копии. Значение не включает объем файлов WAL. Для копий в режиме `STREAM` общий размер `= Data + WAL`
WAL	Размер несжатых файлов WAL, которые должны быть применены для достижения согласованного состояния
Zratio	Коэффициент сжатия: отношение «uncompressed-bytes» к «data-bytes»
Start LSN	Последовательный номер в журнале WAL, соответствующий началу копирования. С этой позиции накатываются изменения (REDO)
Stop LSN	Последовательный номер в журнале WAL, соответствующий окончанию копирования. Позиция точки согласованности при восстановлении
Status	Состояние резервной копии. Возможные варианты: `OK` — резервная копия сделана и пригодна к использованию; `DONE` — резервная копия сделана, но не проверена; `RUNNING` — резервное копирование выполняется; `MERGING` — резервная копия объединяется; `MERGED` — файлы резервной копии были успешно обработаны в процессе объединения копий, но ее метаданные еще изменяются. Это состояние могут иметь только полные резервные копии; `DELETING` — файлы резервной копии удаляются; `CORRUPT` — некоторые файлы резервной копии повреждены; `ERROR` — резервное копирование было прервано из-за неожиданной ошибки; `ORPHAN` — резервная копия непригодна к использованию, так как ее родительская копия испорчена или отсутствует

Примеры

Чтобы получить более подробную информацию о копии, укажите в команде show ее идентификатор:

pg_probackup show -B /pgarclogs/{version}/ --instance=<instance_name> -i <backup-id>

Для получения сведение об архиве WAL файлов выполните следующую команду:

pg_probackup show -B /pgarclogs/{version}/ --instance=clustername --archive

Пример вывода:

ARCHIVE INSTANCE 'clustername'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status
================================================================================================================================
 10   0           0/0          0000000A00000017000000E6  0000000A00000017000000F9  20          13MB   25.52   0          OK
 9    0           0/0          0000000900000017000000E3  0000000900000017000000E5  3           216kB  227.44  0          OK

Для каждой линии времени выдаются следующие сведения:

Параметр	Описание
`TLI`	Идентификатор линии времени
`Parent TLI`	Идентификатор линии времени, от которой была ответвлена данная
`Switchpoint`	LSN момента, когда эта линия времени ответвилась от родительской
`Min Segno`	Первый сегмент WAL, относящийся к этой линии времени
`Max Segno`	Последний сегмент WAL, относящийся к этой линии времени
`N segments`	Количество сегментов WAL, относящихся к этой линии времени
`Size`	Объем, который занимают файлы на диске
`Zratio`	Коэффициент сжатия, вычисляемый по формуле: `N segments * wal_segment_size * wal_block_size / Size`
`N backups`	Число копий, относящихся к этой линии времени. Для получения подробных сведений об этих копиях используйте формат JSON
`Status`	Состояние архива WAL для этой линии времени. Возможные значения: `OK` — в архиве присутствуют все сегменты WAL между `Min Segno` и `Max Segno`; `DEGRADED` — некоторые сегменты WAL в интервале отсутствуют. Чтобы понять, какие именно, получите отчет в формате JSON

Редактирование параметров резервной копии

Для изменения времени жизни или добавление заметки, выполните команду:

pg_probackup set-backup -B <backup-path> --instance=<instance_name>
                 -i <backup-id> [--ttl=interval] [--expire-time=<wal-depth>]
                 [--note=text]

Управление резервными копиями

Удаление

Для удаления ненужной резервной копии, выполните команду:

pg_probackup delete -B <backup-path> --instance=<instance_name>
                 [-j <num-threads>] [--progress]
                 [--retention-redundancy=<retention-redundancy>]
                 [--retention-window=<retention-window>]
                 [--wal-depth=<wal-depth>]
                 [-i <backup-id> | --delete-expired | --merge-expired | --status=backup_status]
                 [--delete-wal]
                 [--dry-run] [--no-validate] [--no-sync]

Команда delete позволяет удалять ненужные резервные копии и связанные с ними файлы. Если указать идентификатор копии через параметр -i <backup-id>, будет удалена сама резервная копия и все ее зависимые инкрементальные копии (если такие есть). Это позволяет, удалить несколько последних инкрементальных копий, при этом сохранив предыдущую полную копию и часть следующих за ней копий.

Для очистки устаревших файлов WAL, которые больше не требуются для восстановления оставшихся резервных копий, используйте параметр --delete-wal.

Команда delete позволяет удалять резервные копии, которые считаются ненужными согласно установленной политике хранения. Чтобы удалить копии с истекшим сроком хранения, используйте параметр --delete-expired.

примечание

Копии с истекшим сроком нельзя удалить, если на них базируется хотя бы одна инкрементальная копия, удовлетворяющая политике хранения.

Если нужно сократить число копий, необходимых для восстановления инкрементальных резервных копий, можно использовать параметр --merge-expired.

В этом случае pg_probackup:

Находит самую старую инкрементальную копию, удовлетворяющую политике хранения.
Объединяет ее с базовой полной копией и всеми ее инкрементальными копиями, срок хранения которых истек.
После завершения объединения устаревшие копии удаляются.

Перед удалением или объединением копий можно выполнить команду delete --dry-run. Это позволит получить текущее состояние всех резервных копий по политике хранения без выполнения каких-либо необратимых действий.

Чтобы удалить все копии с конкретным состоянием, используйте параметр --status=<backup_status>. При этом установленная политика хранения не учитывается — будут удалены все копии с указанным статусом.

Объединение

Со временем при регулярном создании инкрементальных копий общий объем каталога резервных копий может значительно увеличиться. Чтобы сократить занимаемое место на диске, можно объединить инкрементальные копии с их родительской полной копией. Для этого используется команда:

pg_probackup merge -B <backup-path> --instance=<instance_name>
                 -i <backup-id> [--progress] [-j <num-threads>]
                 [--no-validate] [--no-sync]

Если выбран идентификатор полной копии, она объединяется с ближайшей последующей инкрементальной копией.

Если выбран идентификатор инкрементальной копии, объединение выполняется с родительской полной копией, а также со всеми промежуточными инкрементальными копиями.

После выполнения операции:

полная копия дополняется данными из всех объединенных копий;
инкрементальные копии удаляются как избыточные.

Таким образом, результат объединения эквивалентен созданию новой полной копии, но операция выполняется значительно быстрее и эффективнее, чем обычное резервное копирование. Она не создает высокой нагрузки на подсистему ввода/вывода и сеть. Это важно при использовании pg_probackup в удаленном режиме.

Перед началом объединения, pg_probackup проверяет целостность всех копий, участвующих в операции.

Состояния операции:

MERGING — операция объединения в процессе;
MERGED — финальный этап объединения, когда изменяются метаданные полной копии.

Если операция объединения прерывается, ее можно безопасно перезапустить.

Архивация WAL

Отправка WAL

Для отправки файлов WAL в архив, выполните команду:

pg_probackup archive-push -B <backup-path> --instance=<instance_name>
                 --wal-file-name=<wal-file-name>
                 [--wal-file-path=<wal-file-path>]
                 [-j <num-threads>] [--batch-size=<batch_size>]
                 [--archive-timeout=timeout]
                 [--no-ready-rename] [--no-sync]
                 [--overwrite] [--compress]
                 [--compress-algorithm=<compress-algorithm>]
                 [--compress-level=<compress-level>]
                 [--remote-proto] [--remote-host]
                 [--remote-port] [--remote-path] [--remote-user]
                 [--ssh-options]

Получение WAL

Для извлечения файлов WAL из архива, выполните команду:

pg_probackup archive-get -B <backup-path> --instance=<instance_name>
                 --wal-file-path=<wal-file-path>
                 --wal-file-name=<wal-file-name>
                 [-j <num-threads>] [--batch-size=<batch_size>]
                 [--no-validate-wal]
                 [--remote-proto] [--remote-host]
                 [--remote-port] [--remote-path] [--remote-user]
                 [--ssh-options]

Удаленная синхронизация

В pg_probackup реализована команда catchup, которая позволяет создать копию экземпляра сервера СУБД Pangolin напрямую, не используя каталог резервных копий. Инициализация данных локального узла с удаленного сервера:

pg_probackup catchup -b catchup-mode
                 --source-pgdata=<path_to_pgdata_on_remote_server>
                 --destination-pgdata=<path_to_local_dir>
                 [--stream [-S <slot-name>] [--temp-slot | --perm-slot]]
                 [-j <num-threads>]
                 [-T OLDDIR=NEWDIR]
                 [--exclude-path=<path_prefix>]
                 [-d <dbname>] [-h <host>] [-p <port>] [-U <username>]
                 [-w --no-password] [-W --password]
                 [--remote-proto] [--remote-host]
                 [--remote-port] [--remote-path] [--remote-user]
                 [--ssh-options]
                 [--dry-run]

Операция catchup отличается от остальных команд pg_probackup следующими особенностями:

В отличие от обычных резервных копий, catchup работает напрямую с исходным и целевым экземплярами СУБД Pangolin.
Поддерживается только режим STREAM для передачи WAL-файлов.
Копирование внешних каталогов не поддерживается.
Файлы конфигурации (postgresql.conf, postgresql.auto.conf, pg_hba.conf) копируются с исходного сервера и заменяют соответствующие файлы на целевом сервере. Для того чтобы сохранить конфигурационные файлы на целевом сервере без изменений, используйте параметр --exclude-path.

Перед клонированием/синхронизацией убедитесь, что исходный сервер запущен и принимает подключения. Перед синхронизацией можно выполнить команду с параметром --dry-run. Это позволит оценить объем данных, которые будут переданы, без внесения изменений на диск.

Если на исходной базе есть табличные пространства, которые нужно разместить в других каталогах на целевом сервере, задайте параметр -T.

Для ускорения передачи данных catchup можно запускать в нескольких потоках, используя параметр --threads=<num_threads>.

Общие команды

Вывод справки об утилите или команде:

pg_probackup help [COMMAND]

Версия утилиты:

pg_probackup version

Удаление экземпляра из каталога резервных копий

Чтобы удалить все резервные копии и файлы WAL, связанные с указанным экземпляром, выполните команду:

pg_probackup del-instance -B <backup-path>
               --instance=<instance_name>

Сценарии использования

Снятие резервной копии с реплики

Функция резервного копирования позволяет снять с базы данных архивную копию, которую в дальнейшем можно использовать для восстановления. СУБД Pangolin поддерживает создание резервной копии как с лидера, так и с реплики.

Резервное копирование выполняется командой:

PGPASSWORD={backup_pass} pg_probackup backup -B {PGBACKUP} --instance {cluster_name} -b FULL

Восстановление из резервной копии:

pg_probackup restore -B {PGBACKUP} --instance {cluster_name} --recovery-target='latest'

Процедуры резервного копирования на главном сервере и на копии принципиально идентичны.

Описание​

Возможности​

Каталог резервных копий​

Типы резервного копирования​

Параметры​

Общие параметры​

Параметры создания​

Параметры точки восстановления​

Параметры сохранения​

Параметры закрепления​

Параметры ведения журнала​

Параметры подключения​

Параметры сжатия​

Параметры архивации​

Параметры удаленного режима​

Параметры потоковой передачи WAL​

Параметры удаленного архива WAL​

Параметры инкрементального восстановления​

Параметры частичного восстановления​

Установка​

Настройка​

Инициализация и конфигурация​

Создание нового каталога для хранения резервных копий​

Определение экземпляра​

Ручная настройка конфигурации​

Настройка СУБД Pangolin для организации резервного копирования​

Просмотр конфигурации pg_probackup​

Управление​

Создание резервной копии​

Примеры​

Политика хранения​

Восстановление из резервной копии​

Примеры​

Проверка резервной копии​

Проверка базы данных​

Просмотр списка резервных копий​

Примеры​

Редактирование параметров резервной копии​

Управление резервными копиями​

Удаление​

Объединение​

Архивация WAL​

Отправка WAL​

Получение WAL​

Удаленная синхронизация​

Общие команды​

Удаление экземпляра из каталога резервных копий​

Сценарии использования​

Снятие резервной копии с реплики​

Описание

Возможности

Каталог резервных копий

Типы резервного копирования

Параметры

Общие параметры

Параметры создания

Параметры точки восстановления

Параметры сохранения

Параметры закрепления

Параметры ведения журнала

Параметры подключения

Параметры сжатия

Параметры архивации

Параметры удаленного режима

Параметры потоковой передачи WAL

Параметры удаленного архива WAL

Параметры инкрементального восстановления

Параметры частичного восстановления

Установка

Настройка

Инициализация и конфигурация

Создание нового каталога для хранения резервных копий

Определение экземпляра

Ручная настройка конфигурации

Настройка СУБД Pangolin для организации резервного копирования

Просмотр конфигурации pg_probackup

Управление

Создание резервной копии

Примеры

Политика хранения

Восстановление из резервной копии

Примеры

Проверка резервной копии

Проверка базы данных

Просмотр списка резервных копий

Примеры

Редактирование параметров резервной копии

Управление резервными копиями

Удаление

Объединение

Архивация WAL

Отправка WAL

Получение WAL

Удаленная синхронизация

Общие команды

Удаление экземпляра из каталога резервных копий

Сценарии использования

Снятие резервной копии с реплики