Postgres Pro Backup Enterprise : Документация: 3.4: pg_probackup3 : Компания Postgres Professional

pg_probackup3
Пред.	Наверх	Глава 4. Справка	Начало	След.

pg_probackup3

pg_probackup3 — управление резервным копированием и восстановлением кластеров баз данных Postgres Pro

Синтаксис

pg_probackup3 add-instance -B каталог_копий -D каталог_данных --instance имя_экземпляра --skip-if-exists

pg_probackup3 archive-get -B каталог_копий --instance имя_экземпляра --wal-file-path путь_файлов_wal --wal-file-name имя_файла_wal [параметр...]

pg_probackup3 archive-push -B каталог_копий --instance имя_экземпляра --wal-file-path путь_файлов_wal --wal-file-name имя_файла_wal [параметр...]

pg_probackup3 backup -B каталог_копий --instance имя_экземпляра -b режим_копирования [параметр...]

pg_probackup3 catchup -b режим_синхронизации --destination-pgdata=путь [параметр...]

pg_probackup3 del-instance -B каталог_копий --instance имя_экземпляра

pg_probackup3 delete -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии

pg_probackup3 file-map -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии [параметр...]

pg_probackup3 fuse -B каталог_копий --mnt-path путь_монтирования --instance имя_экземпляра -i ид_резервной_копии --cache-swap-size порог_сброса_кеша --cache-dir каталог_кеша [параметр...]

pg_probackup3 help [команда]

pg_probackup3 init -B каталог_копий --skip-if-exists

pg_probackup3 merge -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии [параметр...]

pg_probackup3 restore -B каталог_копий --instance имя_экземпляра [параметр...]

pg_probackup3 retention -B каталог_копий --instance имя_экземпляра { --delete-wal | --delete-expired | --merge-expired } [параметр...]

pg_probackup3 send-backup -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии -p порт -h сервер [параметр...]

pg_probackup3 server-info [параметр...]

pg_probackup3 set-backup -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии [параметр...]

pg_probackup3 set-config -B каталог_копий --instance имя_экземпляра [параметр...]

pg_probackup3 show -B каталог_копий [параметр...]

pg_probackup3 show-config -B каталог_копий --instance имя_экземпляра [параметр...]

pg_probackup3 validate -B каталог_копий [параметр...]

pg_probackup3 version

Справка по командной строке #

Команды #

В этом подразделе описываются команды pg_probackup3. Необязательные параметры этих команд заключаются в квадратные скобки. В подробностях все параметры описываются в подразделе Параметры.

add-instance #

pg_probackup3 add-instance -B каталог_копий -D каталог_данных --instance=имя_экземпляра
[--skip-if-exists] [--wal-archive-dir=путь_каталога] [--wal-tree] [--help]
[параметры_s3] [параметры_ssh] [параметры_журнала]
[параметры_подключения] [параметры_сжатия] [параметры_сохранения]
[параметры_буферизации]

Инициализирует новый копируемый экземпляр в каталоге каталог_копий и создаёт файл конфигурации pg_probackup3.conf, управляющий параметрами pg_probackup3, относящимися к кластеру в указанном каталоге_данных. Если каталог уже был инициализирован, сообщение об ошибке можно отключить, указав --skip-if-exists.

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Каталог будет создан автоматически, если он не существует.

Параметр --wal-tree организует хранение WAL-файлов в подкаталогах, оптимизируя дисковое пространство. Это предотвращает перегрузку файловых систем, в особенности NFS (Network File System, сетевая файловая система), чья архитектура неэффективно обрабатывает большое количество файлов в едином каталоге.

За подробностями обратитесь к подразделам Общие параметры и Определение копируемого экземпляра.

archive-get #

pg_probackup3 archive-get -B каталог_копий --instance=имя_экземпляра --wal-file-path=путь_файлов_wal --wal-file-name=имя_файла_wal
[--help] [-j | --threads=число_потоков] [--batch-size=размер_пакета] [--prefetch-dir=путь] [--wal-archive-dir=путь_каталога]
[параметры_ssh] [параметры_журнала] [параметры_s3] [параметры_буферизации]

Копирует файлы WAL из соответствующего подкаталога каталога резервных копий в каталог журнала предзаписи кластера. Эта команда автоматически устанавливается программой pg_probackup3 в значении параметра restore_command при восстановлении архивных копий с применением архива WAL. Устанавливать её вручную не нужно, если вы используете для копий локальное хранилище или удалённый режим.

Если вы используете интерфейс S3, для обеспечения доступа сервера Postgres Pro к файлам WAL во время восстановления вы можете указать параметр --config-file, определяющий файл конфигурации S3 с требуемыми параметрами конфигурации, как описано в Подразделе «Общие параметры».

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

Параметр --wal-file-path задаёт путь к WAL-файлу. Этот путь может быть абсолютным или относительным. Абсолютный путь используется как есть. Относительный путь интерпретируется относительно текущего рабочего каталога. Postgres Pro выполняет команду из каталога PGDATA, подставляя %p (путь к целевому файлу, например pg_wal/RECOVERYXLOG) и %f (имя запрашиваемого сегмента). Команда копирует требуемый сегмент из архива по указанному пути:

restore_command = 'pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'

Вы можете извлечь конкретный сегмент из архива для ручного восстановления на момент времени или в целях диагностики, выполнив команду archive-get с параметром --wal-file-path, содержащим абсолютный путь к целевому файлу:

pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=/var/lib/pgsql/data/pg_wal/RECOVERYXLOG --wal-file-name=000000010000000000000001

Вы также можете вручную скопировать WAL-файлы из архива в другое место, например для переноса данных на другой сервер или создания тестового окружения:

pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=/mnt/wal_restore/000000010000000000000001 --wal-file-name=000000010000000000000001

Postgres Pro запрашивает сегменты WAL по одному. Для ускорения восстановления можно воспользоваться параметром --batch-size, определяющим размер пакета из нескольких копируемых сегментов WAL. Вместе с --batch-size также можно указать параметр -j/--threads, чтобы пакеты WAL-сегментов копировались в несколько потоков. Если --batch-size не задан, но задан -j/--threads, то --batch-size по умолчанию принимает значение -j/--threads.

За подробностями обратитесь к подразделам Общие параметры, Параметры архивирования и Параметры сжатия.

archive-push #

pg_probackup3 archive-push -B каталог_копий --instance=имя_экземпляра
--wal-file-name=имя_файла_wal [--wal-file-path=путь_файлов_wal]
[--help] [--no-sync] [--overwrite] [--wal-archive-dir=путь_каталога]
[--archive-timeout=время_ожидания]
[--compress-algorithm=алгоритм_сжатия]
[--compress-level=уровень_сжатия]
[-j | --threads= число_потоков] [--batch-size=размер_пакета]
[параметры_ssh] [параметры_журнала]
[параметры_s3] [параметры_буферизации]

Копирует файлы WAL в соответствующий подкаталог каталога копий, проверяя целевой экземпляр по имени_экземпляра и значению system-identifier. Если параметры экземпляра резервной копии и кластера не совпадают, операция копирования не выполняется, и выдаётся ошибка: Refuse to push WAL segment segment_name into archive. Instance parameters mismatch. (Отказано в помещении сегмента имя_сегмента в архив. Параметры экземпляра не совпадают.)

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

Если файлы, которые требуется копировать, уже имеются в каталоге копий, pg_probackup3 вычисляет и сравнивает их контрольные суммы. В случае совпадения контрольных сумм archive-push пропускает соответствующий файл и выдаёт код успешного завершения. Если же они не совпадают, операция archive-push завершается с ошибкой.

Содержимое каждого файла копируется во временный файл с расширением .part. Если такой временный файл уже существует, pg_probackup3 ждёт, что он исчезнет в течение заданного параметром archive_timeout времени, а если этого не происходит, отбрасывает его. После переноса содержимого выполняется атомарная операция переименования. Тем самым гарантируется, что в случае ошибки команды archive-push непрерывное архивирование не остановится и что при параллельном архивировании WAL из разных источников в один архив повреждение архива исключено.

Postgres Pro запрашивает сегменты WAL по одному. Для ускорения архивирования можно воспользоваться параметром --batch-size, определяющим размер пакета из нескольких копируемых сегментов WAL. Вместе с параметром --batch-size также можно применить указание -j/--threads, чтобы пакеты WAL-сегментов копировались в несколько потоков. Если --batch-size не задан, но задан -j/--threads, то --batch-size по умолчанию принимает значение -j/--threads.

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

Команду archive-push можно использовать в значении параметра archive_command Postgres Pro .

За подробностями обратитесь к подразделам Общие параметры, Параметры архивирования и Параметры сжатия.

backup #

pg_probackup3 backup -B каталог_копий --instance=имя_экземпляра -b режим_копирования -s источник_данных -i ид_резервной_копии
[-x | --exclude-path=префикс_пути] [--wal-archive-dir=путь_каталога] [--with-file-map] [--help] [--progress] [-j | --threads= число_потоков]
[--num-write-threads число_потоков] [--num-validate-threads число_потоков]
[--num-segments] [--create-slot] [--transfer-mode] [--stream]
[--no-validate] [--skip-block-validation] [--no-validate-wal]
[--archive-timeout=время_ожидания] [--external-dirs=путь_внешнего_каталога]
[--no-sync] [--note=заметка_к_копии]
[параметры_подключения] [параметры_сжатия] [параметры_ssh] [параметры_частичного_резервного_копирования]
[параметры_закрепления] [параметры_журнала] [параметры_s3] [параметры_буферизации]

Создаёт копию экземпляра Postgres Pro.

-b режим --backup-mode=режим

Задаёт режим резервного копирования. Возможные значения: full, delta, ptrack.

-s источник_копирования --backup-source=источник_копирования

Указывает источник данных для резервного копирования. Возможные значения: pro, direct, base. Значение по умолчанию — pro.

--wal-archive-dir=путь_каталога

Задаёт каталог для архива WAL.

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

--num-segments=количество_сегментов

Задаёт количество сегментов резервной копии при её создании или объединении. Должен быть положительным целым числом.

Примечание

Если указанное значение превышает системное ограничение на количество одновременно открытых файлов, процесс завершится с ошибкой «too many open files» (слишком много открытых файлов).

--num-write-threads=число_потоков

Указывает количество потоков для копирования файлов. Переопределяет параметр j/--threads для копирования файлов.

--num-validate-threads=число_потоков

Указывает количество потоков для проверки резервной копии. Переопределяет параметр j/--threads для проверки резервной копии.

-C --smooth-checkpoint

Если этот параметр включён, резервное копирование запустится в начале следующей запланированной контрольной точки. В противном случае контрольная точка будет выполнена немедленно и резервное копирование начнётся максимально быстро.

--stream

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

-x префикс_пути --exclude-path=префикс_пути

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

--backup-pg-log

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

-E путь_внешнего_каталога --external-dirs=путь_внешнего_каталога

Включает в создаваемую копию указанный каталог, рекурсивно копируя его содержимое в отдельный подкаталог каталога резервной копии. Этот параметр полезен для архивирования скриптов, SQL-дампов и файлов конфигурации, расположенных вне каталога данных. Если вы хотите архивировать несколько внешних каталогов, их пути нужно разделять двоеточием в Linux или точкой с запятой в Windows.

--archive-timeout=время_ожидания

Задаёт тайм-аут для архивирования сегментов WAL, в секундах. По умолчанию pg_probackup3 ждёт выполнения этих операций 300 секунд.

Примечание

Для режима STREAM этот параметр не применяется. Тайм-аут для потоковой передачи WAL-сегментов фиксирован и всегда на 10% больше значения параметра checkpoint_timeout, сконфигурированного на сервере.

--skip-block-validation

Отключает проверку контрольных сумм на уровне блоков в процессе резервного копирования.

--no-validate

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

Рекомендуется использовать этот флаг при создании резервной копии в хранилище S3. Из-за некоторых особенностей хранилищ S3 автоматическая проверка в этом случае может оказаться некорректной. Пропустите её, а затем выполните проверку с помощью отдельной команды validate.

--no-validate-wal

Отключает проверку WAL-файлов.

Примечание

Параметр --no-validate отключает проверку полностью, включая проверку WAL, тогда как параметр --no-validate-wal отключает только проверку WAL и не влияет на проверку контрольных сумм.

Предупреждение

Используйте --no-validate-wal с осторожностью. Операции могут завершаться успешно, даже если данные повреждены, а восстановленная база данных может оказаться логически несогласованной. Ответственность за последствия полностью лежит на пользователе.

--no-sync

Не сбрасывать копируемые файлы на диск. Этот флаг позволяет несколько ускорить процесс копирования. Использование этого флага может привести к повреждению данных в случае аварии операционной системы или аппаратного сбоя. Если вы используете его, рекомендуется выполнить команду validate сразу после завершения копирования, чтобы убедиться в отсутствии проблем.

--note=заметка_к_копии

Задаёт текстовую заметку для резервной копии. Если заметка_к_копии содержит символы перевода строки, сохранена будет только подстрока до первого перевода строки. Максимальный размер заметки равен 1 КБ. Значение 'none' удаляет текущую заметку.

--with-file-map

Включает создание файлов сопоставления. Необходим для команды fuse.

--transfer-mode=режим_передачи

Указывает способ передачи данных с сервера в приложение.

Примечание

Этот параметр доступен только в режиме источника данных PRO.

Возможные значения:

raw: данные передаются в несжатом виде блоками произвольного размера.
packed: данные передаются в упакованном виде блоками по 128 КБ с общим заголовком.

packed — значение по умолчанию (рекомендуемое).

За подробной информацией о параметрах команды обратитесь к подразделам Общие параметры, Параметры соединения, Параметры закрепления, Параметры SSH, Параметры сжатия и Параметры ведения журнала.

За подробностями обратитесь к подразделу Создание резервной копии.

catchup #

pg_probackup3 catchup -b | --backup-mode=режим_синхронизации --destination-pgdata=путь
[-s | --backup-source=источник_данных] [-x | --exclude-path=префикс_пути]
[--temp-slot] [-P | --perm-slot] [-S | --slot=имя_слота] [-j | --threads=число_потоков]
[--num-write-threads=число_потоков] [--num-validate-threads=число_потоков]
[-T старый_каталог=новый_каталог] [-X | --waldir=каталог_wal]
[параметры_подключения] [параметры_журнала] [параметры_сжатия]

Создаёт копию экземпляра Postgres Pro, не используя каталог резервных копий.

За особенностями и ограничениями использования catchup обратитесь к Подразделу 3.9.1.

-b режим_синхронизации --backup-mode=режим_синхронизации

Задаёт режим синхронизации. Возможные значения: full, delta, ptrack. Значение по умолчанию — full.

--destination-pgdata=путь

Задаёт путь к каталогу данных на целевом сервере.

-s источник_данных --backup-source=источник_данных

Задаёт режим источника данных для синхронизации. Возможные значения: pro, base. Значение по умолчанию — pro.

Примечание

Режим DIRECT в настоящее время не поддерживается.
Если режим PRO недоступен, pg_probackup3 переключается на режим BASE в качестве резервного варианта. За подробностями обратитесь к Подразделу 3.9.1.

-j число_потоков --threads=число_потоков

Задаёт число параллельных потоков для процесса catchup.

--num-write-threads=число_потоков

--num-validate-threads=число_потоков

-x префикс_пути --exclude-path=префикс_пути

Определяет префикс для файлов, которые не будут копироваться при синхронизации экземпляров Postgres Pro. Такой префикс должен содержать путь относительно каталога данных экземпляра. Если в префиксе указан каталог, ни один файл в этом каталоге не будет копирован.

--temp-slot

Создаёт временный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Это гарантирует, что все нужные сегменты WAL будут доступны, если в процессе копирования произойдёт переключение сегментов WAL. Этот параметр нельзя использовать с параметром --perm-slot. По умолчанию имя временного слота — pg_probackup3_wal_streaming_идентификатор_процесса, где идентификатор_процесса — PID Postgres Pro. Чтобы его поменять, воспользуйтесь параметром --slot/-S и явно укажите --temp-slot.

-P --perm-slot

Создаёт постоянный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Этот параметр нельзя использовать с параметром --temp-slot. По умолчанию имя постоянного слота — pg_probackup_perm_slot, но его можно поменять, воспользовавшись параметром --slot/-S.

-S имя_слота --slot=имя_слота

Задаёт слот репликации для подключения при потоковой передаче WAL.

-T старый_каталог=новый_каталог --tablespace-mapping=старый_каталог=новый_каталог

Перемещает табличное пространство из каталога СТАРЫЙ_КАТАЛОГ в НОВЫЙ_КАТАЛОГ во время восстановления. И старый_каталог, и новый_каталог должны задаваться абсолютными путями. Если путь содержит знак равно (=), экранируйте этот знак обратной косой чертой. Данный параметр может указываться неоднократно для перемещения нескольких табличных пространств.

Примечание

Обратите внимание на синтаксис переопределения путей для нескольких табличных пространств: вместо нескольких флагов -T используйте один флаг с парами переопределения, разделёнными двоеточием. Например:

-T старый_каталог1=новый_каталог1:старый_каталог2=новый_каталог2

-X каталог_wal --waldir=каталог_wal

Задаёт каталог, в который будут записаны файлы WAL. По умолчанию файлы WAL будут записываться в подкаталог pg_wal целевого каталога, но с помощью этого параметра их можно поместить в любое место. Путь каталог_wal должен быть абсолютным; этот путь может не существовать, но если он существует, он должен быть пустым, чтобы команда catchup могла выполняться в режиме FULL.

За подробностями использования команды catchup обратитесь к разделу Клонирование и синхронизация экземпляра Postgres Pro.

del-instance #

pg_probackup3 del-instance -B каталог_копий --instance=имя_экземпляра [параметры_s3] [--help]
[параметры_ssh] [параметры_журнала] [параметры_буферизации]

Удаляет все резервные копии и файлы WAL, связанные с указанным экземпляром.

За подробностями о параметрах команды обратитесь к подразделу Общие параметры.

delete #

pg_probackup3 delete -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии
[--help] [--progress] [--status=статус_резервной_копии]
[--dry-run] [параметры_журнала] [параметры_ssh]
[параметры_s3] [параметры_буферизации]

Удаляет резервные копии с указанными ид_резервной_копии.

--dry-run: Выполняет пробный запуск команды delete, который не вносит никаких реальных изменений: файлы на диске не удаляются. Этот флаг также позволяет проверить правильность всех параметров команды и её готовность к запуску.
--status: Позволяет удалять все резервные копии с определённым состоянием.

За подробностями обратитесь к подразделу Удаление резервных копий.

file-map #

pg_probackup3 file-map -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии

Включает создание файлов сопоставления для существующей цепочки резервных копий.

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

fuse #

pg_probackup3 fuse -B каталог_копий --mnt-path=путь_монтирования --instance=имя_экземпляра
-i ид_резервной_копии [--cache-swap-size=порог_сброса_кеша] [--cache-dir=каталог_кеша] [--detach] [--unmount] [--help]
[параметры_ssh] [параметры_журнала] [параметры_s3] [параметры_буферизации] [параметры_точки_восстановления]

Монтирует каталог резервных копий в виде виртуальной файловой системы и позволяет Postgres Pro работать на ней. Более детальное описание процесса представлено в Раздел 3.6.

--cache-swap-size: Задаёт объём данных (в МБ), хранящихся в оперативной памяти. Значение по умолчанию — 128 МБ. При превышении этого размера изменения сбрасываются на ближайший диск. Это позволяет работать со снимком состояния базы данных, не изменяя исходную резервную копию. Кеш очищается после остановки сервера Postgres Pro.
--cache-dir=каталог_кеша: Указывает путь к каталогу кеша FUSE. Если этот параметр опущен, используется системный временный каталог.
--detach: Запускает файловую систему FUSE в фоновом режиме (по умолчанию работает не в фоновом режиме). Это полезно для автоматизации.
--unmount: Демонтирует файловую систему FUSE, которая была ранее смонтирована с помощью команды fuse. Для этого параметра требуется указать только путь монтирования (параметр --mnt-path), который должен совпадать с путём, использовавшимся при монтировании.

help #

pg_probackup3 help [command]

Выдаёт справку по командам pg_probackup3. Если в параметрах задаётся одна из команд pg_probackup3, выводит подробную информацию по параметрам, которые принимает эта команда.

init #

pg_probackup3 init -B каталог_копий [--skip-if-exists] [параметры_s3] [--help]
[параметры_ssh][параметры_журнала] [параметры_буферизации]

Инициализирует каталог_копий, в котором будут храниться резервные копии, архив WAL и метаинформация о скопированных кластерах баз данных. Если заданный каталог_копий уже существует, он должен быть пустым. В противном случае pg_probackup3 выдаст соответствующее сообщение об ошибке. Можно отключить вывод этого сообщения, указав --skip-if-exists. Хотя каталог не будет инициализирован, приложение вернёт 0.

За подробностями обратитесь к подразделу Инициализация каталога резервных копий. Более подробно о параметрах команды рассказывается в подразделе Общие параметры.

merge #

pg_probackup3 merge -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии --merge-from-id=объединить_от --merge-interval=интервал_объединения
[-t | --target-backup-id=ид_резервной_копии] [-j | --threads=число_потоков] [--progress] [--no-validate] [--no-sync] [--no-validate-wal]
[--keep-backups] [--dry-run] [--help][параметры_журнала] [параметры_ssh] [параметры_s3] [параметры_буферизации]

Объединяет копии, относящиеся к одной цепочке инкрементальных копий. Если выбрана полная копия, она будет объединена с первой инкрементальной копией после неё. Если выбрана инкрементальная копия, она будет объединена с родительской полной копией, включая все инкрементальные копии между ними. После выполнения команды полная копия содержит все объединённые данные, а инкрементальные копии удаляются как ненужные. Вы также можете объединять цепочки инкрементальных копий, указав первую и последнюю резервные копии или интервал (в часах) от момента создания первой резервной копии.

--no-validate: Пропускает автоматическую проверку до и после объединения.
--no-validate-wal: Отключает проверку WAL-файлов.
Предупреждение
Используйте --no-validate-wal с осторожностью. Операции могут завершаться успешно, даже если данные повреждены, а восстановленная база данных может оказаться логически несогласованной. Ответственность за последствия полностью лежит на пользователе.
--no-sync: Не сбрасывать объединяемые файлы на диск. Этот флаг позволяет несколько ускорить процесс объединения. Использование этого флага может привести к повреждению данных в случае аварии операционной системы или аппаратного сбоя.
-t --target-backup-id: Задаёт идентификатор объединённой резервной копии.
--keep-backups: Сохраняет исходные резервные копии после объединения.
--merge-from-id: Указывает идентификатор первой резервной копии в цепочке копий для объединения.
--merge-interval: Задаёт время (в часах) перед объединением цепочки инкрементальных резервных копий.
--with-file-map: Включает создание файлов сопоставления. Необходим для команды fuse.

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

restore #

pg_probackup3 restore -B каталог_копий --instance=имя_экземпляра
[--help] [-D каталог_данных] [-i ид_резервной_копии] [--wal-archive-dir=путь_каталога]
[-I | --incremental-mode=инкрементальный_режим] [--progress] [-T старый_каталог=новый_каталог] [-X | --waldir=каталог_wal]
[--external-mapping=старый_каталог=новый_каталог] [--skip-external-dirs]
[-j | --threads=число_потоков] [--num-validate-threads=число_потоков]
[-R | --restore-as-replica] [--no-validate] [--skip-block-validation] [--no-validate-wal]
[--no-sync] [--restore-command=команда]
[--primary-conninfo=строка_подключения]
[ --primary-slot-name=имя_слота]
[параметры_точки_восстановления] [параметры_журнала] [параметры_частичного_восстановления]
[параметры_ssh] [параметры_s3] [параметры_буферизации]

Восстанавливает экземпляр Postgres Pro из резервной копии, расположенной в каталоге каталог_копий.

Примечание

В то время как файлы резервных копий могут передаваться из разных источников (файловая система, S3 или SSH SFTP), восстановление каталога данных PGDATA сервера Postgres Pro производится в локальную файловую систему.

Примечание

Команда restore пока не поддерживает параметр --threads. Число потоков равняется числу сегментов резервной копии.

-R --restore-as-replica

Создаёт минимальный файл конфигурации восстановления для облегчения настройки ведомого сервера. Если для соединения репликации требуется пароль, его нужно дополнительно задать вручную в параметре primary_conninfo. pg_probackup3 сохраняет эти параметры в файле probackup_recovery.conf и при запуске кластера включает их в postgresql.auto.conf.

--primary-conninfo=строка_подключения

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

Пример: --primary-conninfo="host=192.168.1.50 port=5432 user=foo password=foopass"

--primary-slot-name=имя_слота

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

-I инкрементальный_режим --incremental-mode=инкрементальный_режим

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

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

Если этот параметр опущен, выполняется обычное (неинкрементальное) восстановление.

-T старый_каталог=новый_каталог --tablespace-mapping=старый_каталог=новый_каталог

Примечание

-T старый_каталог1=новый_каталог1:старый_каталог2=новый_каталог2

--external-mapping=старый_каталог=новый_каталог

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

--skip-external-dirs

Пропускать внешние каталоги, включённые в резервную копию указанием --external-dirs. Содержимое этих каталогов не будет восстановлено.

--skip-block-validation

Отключает проверку контрольных сумм на уровне блоков для ускорения проверки целостности. При автоматической проверке перед восстановлением будут проверяться только контрольные суммы на уровне файлов.

--no-validate

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

--no-validate-wal

Отключает проверку WAL-файлов.

Предупреждение

--restore-command=команда

Задаёт значение для параметра restore_command. Например: --restore-command='cp /mnt/server/archivedir/%f "%p"'

--wal-archive-dir=путь_каталога

Задаёт каталог для архива WAL.

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

--force

Позволяет игнорировать ошибочное состояние копии. Этот флаг можно использовать, когда требуется восстановить кластер Postgres Pro из повреждённой или некорректной копии. Применяйте его с осторожностью.

Если в целевом каталоге PGDATA идентификатор системы отличается от того, что указан в копии, при инкрементальном восстановлении с этим флагом содержимое каталога будет перезаписано (тогда как без флага возникнет ошибка). Также в случае переопределения расположения табличных пространств с помощью --tablespace-mapping в непустые каталоги содержимое этих каталогов будет удалено.

--no-sync

Не сбрасывать восстанавливаемые файлы на диск. Этот флаг позволяет несколько ускорить процесс восстановления. Использование этого флага может привести к повреждению данных в случае аварии операционной системы или аппаратного сбоя. Если такое событие произойдёт, вам потребуется запустить команду restore ещё раз.

-X каталог_wal --waldir=каталог_wal

Задать каталог, в который будут записаны файлы WAL. По умолчанию файлы WAL будут записываться в подкаталог pg_wal целевого каталога, но с помощью этого параметра их можно поместить в любое место. Путь каталог_wal должен быть абсолютным; этот путь может не существовать, но если он существует, он должен быть пустым.

За подробной информацией о параметрах команды обратитесь к подразделам Общие параметры, Параметры точки восстановления, Параметры SSH, Параметры удалённого архива WAL, Параметры ведения журнала.

За подробностями обратитесь к подразделу Восстановление кластера.

retention #

pg_probackup3 retention -B каталог_копий --instance=имя_экземпляра
[--retention-redundancy] [--retention-window] [--dry-run] [--merge-expired] [--wal-archive-dir=путь_каталога]
[--delete-expired] [--delete-wal] [параметры_закрепления]
[параметры_ssh] [параметры_s3] [параметры_буферизации]

Устанавливает политику хранения резервных копий в экземпляре или каталоге и запускает процесс удаления или объединения резервных копий согласно указанным параметрам.

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

За подробностями о параметрах команды обратитесь к подразделу Параметры сохранения.

send-backup #

pg_probackup3 send-backup -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии -p порт -h хост
[--no-merge] [-I | --incremental-mode=инкрементальный_режим] [параметры_удалённого_архива_wal]

Передаёт данные резервных копий в удалённую систему через указанный порт с использованием многопоточности.

Эта команда выполняется на локальной машине, содержащей каталог резервных копий.

Если резервная копия была создана в режиме ARCHIVE, а её архив WAL находится на отдельном сервере, укажите параметры доступа к нему — --archive-host, --archive-port и --archive-user (параметры удалённого архива WAL). Значения этих параметров передаются на удалённую сторону и используются для формирования restore_command, чтобы целевой экземпляр мог читать WAL из архива.

-p порт --pgport=порт

Указывает порт на удалённом хосте.

-h сервер --pghost=сервер

Указывает имя удалённого хоста.

--no-merge

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

Если этот параметр опущен, перед передачей данных цепочка резервных копий объединяется во временный файл, который удаляется после завершения передачи.

-I инкрементальный_режим --incremental-mode=инкрементальный_режим

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

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

Предупреждение

Используйте параметр -I вместе с флагом --no-merge. В противном случае операция завершится ошибкой.

За подробностями обратитесь к разделу Удалённое восстановление.

server-info #

pg_probackup3 server-info [--format=plain|json] [параметры_подключения]

Отображает доступность параметров резервного копирования для текущего экземпляра Postgres Pro. Включает основную информацию об экземпляре и версию pg_probackup3. Пример вывода:

CAN_USE_API = true
CAN_USE_CLI = true
CAN_USE_S3 = true
CAN_USE_CFS = true
CAN_USE_FUSE = true
CAN_USE_DIRECT = true
CAN_USE_BASE = true
CAN_USE_PRO = true
CAN_USE_MULTITHREAD = true
IS_PRO_MODE_CONFIGURED = true
IS_DELTA_AVAILABLE = true
IS_PTRACK_CONFIGURED = true
IS_PAGE_AVAILABLE = false
IS_WALSUM_AVAILABLE = false
IS_PGDATA_ACCESS = true
SERVER_CHECKSUM_ENABLED = true
PG_VERSION = 170006
PG_VERSION_STRING = "Postgres Pro (enterprise) 17.6.1 on aarch64-apple23.6.0, compiled by Homebrew clang version 21.1.2, 64-bit"
PG_EDITION_STRING = "enterprise"
PGDATA = "/Users/username/projects/postgrespro/tmp_install/data"
TIMELINE = 1
SYSTEM_ID = 75800766633445207
PG_MAX_WAL_SENDERS = 20
PG_BLOCK_SIZE = 8192
PG_BLOCKS_IN_SEGMENT = 131072
PG_WAL_BLOCK_SIZE = 8192
PG_WAL_SEGMENT_SIZE = 16777216
PG_TABLESPACE_MAP = "[]"
APP_VERSION = 3.2.0

По умолчанию вывод отображается в виде простого текста. Укажите параметр --format=json, чтобы получить результат в формате JSON.

Параметры типа CAN_USE_* отражают лицензионные ограничения и показывают, какие функции доступны в текущей версии Postgres Pro.

set-backup #

pg_probackup3 set-backup -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии
{--ttl=время_жизни | --expire-time=время}
[--note=заметка_к_копии] [параметры_ssh]
[параметры_s3] [--help] [параметры_журнала] [параметры_буферизации]

Устанавливает заданные для конкретной резервной копии параметры в конфигурационном файле backup.control или изменяет ранее определённые значения.

--note=заметка_к_копии: Задаёт текстовую заметку для резервной копии. Если заметка_к_копии содержит символы перевода строки, сохранена будет только подстрока до первого перевода строки. Максимальный размер заметки равен 1 КБ. Значение 'none' удаляет текущую заметку.

За подробностями о параметрах команды обратитесь к подразделам Общие параметры и Параметры закрепления.

set-config #

pg_probackup3 set-config -B каталог_копий --instance=имя_экземпляра
[--help] [--pgdata=путь_к_pgdata] [--wal-archive-dir=путь_каталога] [--wal-tree]
[--retention-redundancy=избыточность][--retention-window=окно]
[параметры_сжатия] [параметры_подключения]
[--archive-timeout=время_ожидания] [--external-dirs=путь_внешнего_каталога]
[параметры_журнала] [параметры_ssh] [параметры_буферизации]

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

По умолчанию архив WAL хранится в каталоге каталог_копий/wal/имя_экземпляра. Чтобы указать пользовательский каталог, используйте параметр --wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.

Все поддерживаемые параметры описываются в подразделе Параметры.

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

show #

pg_probackup3 show -B каталог_копий
[--help] [--instance=имя_экземпляра [-i ид_резервной_копии | --archive [--wal-archive-dir=путь_каталога]]]
[--show-log] [--format=plain|json] [--no-color] [--format=plain|json|tree]
[параметры_s3] [параметры_ssh]
[параметры_журнала] [параметры_буферизации]

Показывает содержимое каталога резервных копий. Если заданы имя_экземпляра и ид_резервной_копии, выводится подробная информация об этой копии. С указанием флага --archive эта команда отображает содержимое архива WAL, который по умолчанию находится в каталог_копий/wal/имя_экземпляра. Для указания пользовательского каталога используйте параметр --wal-archive-dir.

По умолчанию содержимое каталога представляется в виде обычного текста. Вы можете передать параметр --format=json, чтобы получить результат в формате JSON. С параметром --no-color выводимые сообщения не выделяются цветом. Можно также использовать параметр --format=tree, чтобы посмотреть список резервных копий в виде дерева.

Более подробно использование этой команды описывается в подразделах Управление каталогом резервных копий и Просмотр оглавления архива WAL.

show-config #

pg_probackup3 show-config -B каталог_копий --instance имя_экземпляра
[--format=plain|json] [параметры_s3] [параметры_ssh]
[параметры_журнала] [параметры_буферизации]

Выводит все текущие параметры конфигурации pg_probackup3, в том числе те, что содержатся в файле pg_probackup3.conf, размещённом в каталоге каталог_копий/backups/имя_экземпляра, и те, что были заданы в командной строке. По умолчанию параметры конфигурации выводятся обычным текстом.

Чтобы изменить содержимое pg_probackup3.conf, используйте команду set-config.

validate #

pg_probackup3 validate -B каталог_копий
[--help] [--instance=имя_экземпляра] [-i ид_резервной_копии]
[-j | --threads=число_потоков] [--progress]
[--skip-block-validation] [--no-validate-wal] [параметры_буферизации]
[параметры_журнала] [параметры_ssh][параметры_s3]

Проверяет наличие и целостность всех файлов, необходимых для восстановления кластера. Если имя_экземпляра не задаётся, pg_probackup3 проверяет все резервные копии, имеющиеся в каталоге копий.

Если указать параметр --progress, в процессе проверки будет выводиться список файлов и каталогов резервной копии.

Параметр --no-validate-wal отключает проверку WAL-файлов.

Предупреждение

version #

pg_probackup3 version

Выводит версию pg_probackup3.

При указании --format=json вывод будет получен в формате JSON. Это может потребоваться для внутренней интеграции с приложениями на основе JSON, например PPEM. Пример вывода JSON:

        pg_probackup3 version --format=json
        {
            "pg_probackup3":
            {
                "version": "3.0.0",
            },
            "compressions": [zlib, lz4, zstd]
        }

Параметры #

В этом подразделе описываются параметры командной строки для команд pg_probackup3. Если какое-либо значение параметра может быть получено из переменной окружения, имя этой переменной указывается в верхнем регистре ниже параметра командной строки. Некоторые значения могут быть получены из файла конфигурации pg_probackup3.conf, находящегося в каталоге копий.

За подробностями обратитесь к Разделу 2.5.

Если некоторый параметр задаётся несколькими способами, значение в командной строке имеет наивысший приоритет, а значение в pg_probackup3.conf — наименьший.

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

Ниже приведён список параметров общего характера.

--dry-run

Выполняет пробный запуск нужной команды, который не вносит никаких реальных изменений: не создаются, не удаляются и не перемещаются файлы на диске. Этот флаг также позволяет проверить правильность всех параметров команды и её готовность к запуску. С --dry-run пропускается потоковая трансляция WAL.

-B каталог --backup-path=каталог BACKUP_PATH

Задаёт абсолютный путь к каталогу копий. Каталог копий — это каталог, в котором хранятся все файлы резервных копий и метаинформация. Поскольку это расположение необходимо задавать почти для всех команд pg_probackup3, имеет смысл указать его один раз в переменной окружения BACKUP_PATH. В этом случае каждый раз указывать этот путь в командной строке не нужно.

-D каталог --pgdata=каталог PGDATA

Задаёт абсолютный путь к каталогу данных кластера. Этот параметр является обязательным только для команды add-instance. Другие команды могут получать этот путь из переменной окружения PGDATA или из файла конфигурации pg_probackup3.conf.

-i ид_резервной_копии --backup-id=ид_резервной_копии

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

--parent-backup-id=ид_родительской_копии

Указывает уникальный идентификатор родительской копии (используется при инкрементальном копировании).

--from-full

Создаёт инкрементальную резервную копию от последней родительской полной копии.

-j число_потоков --threads=число_потоков PG_PROBACKUP_MAX_THREADS

Задаёт число параллельных потоков, запускаемых командами backup, catchup, merge, validate, archive-push и archive-get. По умолчанию равно числу ядер процессора.

Если параметр -j не указан, но задана переменная окружения PG_PROBACKUP_MAX_THREADS, количество потоков определяется автоматически исходя из количества доступных ядер процессора, но не может превышать значение PG_PROBACKUP_MAX_THREADS.

--num-validate-threads число_потоков

Задаёт число параллельных потоков, запускаемых во время проверки резервных копий, например, при выполнении команд backup или restore.

Ключ --no-validate отключает действие параметра --num-validate-threads.

--progress

Включает вывод прогресса выполнения операций.

--help

Выводит подробную информацию по параметрам, которые принимает эта команда.

-v версия --version=версия

Показывает версию pg_probackup3.

--config-file=имя_файла

Задаёт файл конфигурации S3 или SSH. Параметры, заданные в этом файле, переопределяют переменные окружения.

Чтобы создать файл конфигурации, выполните команду set-config с параметром --config-file.

В созданном файле будут указаны все явно заданные параметры S3 или SSH, при этом пароли исключаются и отображаются в виде звёздочек.

Пример файла конфигурации S3:

access-key=admin
s3=on
s3-bucket=test
s3-host=127.0.0.1
s3-port=9000
s3-region=us-west-2
secret-key=***

Если файл конфигурации содержит параметры и S3, и SSH, будут использоваться параметры S3.

Если параметр --config-file опускается, pg_probackup3 ищет файлы конфигурации S3 и SSH сначала в /etc/pg_probackup/s3.config или /etc/pg_probackup/ssh.config, а затем в ~postgres/.pg_probackup/s3.config или ~postgres/.pg_probackup/ssh.config соответственно.

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

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

Предупреждение

Точки восстановления являются взаимоисключающими — одновременно можно указать только один параметр.

--recovery-target-stop=immediate|latest

Определяет, когда остановить восстановление:

Со значением immediate восстановление завершается сразу после достижения согласованного состояния выбранной копии. Такое поведение по умолчанию применяется для копий типа STREAM.
Со значением latest восстановление продолжается до тех пор, пока не будут применены все имеющиеся в архиве сегменты WAL. При указании этого значения для параметра --recovery-target такое же значение задаётся для параметра --recovery-target-timeline.

--recovery-target-timeline=линия_времени

Выбирает линию времени для восстановления:

current — линия времени указанной резервной копии. Это значение по умолчанию.

latest — линия времени последней доступной резервной копии.
Числовое значение.

--recovery-target-lsn=lsn

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

--recovery-target-name=имя_цели_восстановления

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

--recovery-target-time=время|current|latest

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

Например: --recovery-target-time="2027-04-09 18:21:32+00"

--recovery-target-xid=ид_транзакции

Указывает идентификатор транзакции, вплоть до которой будет производиться восстановление.

--recovery-target-inclusive=boolean

Указывает на необходимость остановки сразу после (true) либо до (false) достижения целевой точки. Этот параметр можно использовать только вместе с параметром --recovery-target-time, --recovery-target-lsn или --recovery-target-xid. Значение по умолчанию определяется параметром recovery_target_inclusive.

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

Задаёт действие (recovery_target_action), которое должен выполнить сервер по достижении цели восстановления.

По умолчанию: pause

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

Эти параметры используются с командой retention.

Подробнее о политике хранения рассказывается в подразделе Настройка политики хранения.

--retention-redundancy=избыточность

Указывает, сколько полных резервных копий должно сохраняться в каталоге данных. Должно быть неотрицательным целым числом. Ноль отключает сохранение.

По умолчанию: 0

--retention-window=окно

Указывает количество дней, в течение которого возможно восстановление. Должно быть неотрицательным целым числом. При нулевом значении окно восстановления отсутствует.

По умолчанию: 0

--delete-wal

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

--delete-expired

Удаляет резервные копии, не удовлетворяющие политике сохранения, определённой в файле конфигурации pg_probackup3.conf.

--merge-expired

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

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

Эти параметры могут использоваться с командами backup, set-backup и retention.

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

--ttl=время_жизни

Задаёт время, на которое закрепляется резервная копия. Значение должно быть неотрицательным целым. Нулевое значение отменяет установленное ранее закрепление резервной копии. Поддерживаются следующие единицы измерения: ms (миллисекунды), s (секунды), min (минуты), h (часы), d (дни). По умолчанию подразумеваются секунды.

Например: --ttl=30d

--expire-time=время

Определяет момент времени, до которого будет храниться резервная копия. Время должно задаваться в формате ISO-8601. Если часовой пояс не указывается, подразумевается местное время.

Например: --expire-time="2027-04-09 18:21:32+00"

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

Эти параметры могут использоваться с любой командой.

--no-color

Отключает цветовое выделение сообщений уровней warning и error в консоли.

--log-level-console=уровень_протоколирования

Управляет уровнем сообщений, которые будут выводиться в журнал консоли. Допустимые уровни: trace, debug, info, warning, error и off. Каждый уровень включает все последующие, и с каждым последующим уровнем объём сообщений уменьшается. Вариант off отключает вывод в журнал консоли.

По умолчанию: info

Примечание

Все выводимые в консоль сообщения журнала передаются через stderr, чтобы их можно было отделить от вывода команд show и show-config.

--log-level-file=уровень_протоколирования

Управляет уровнем сообщений, которые будут выводиться в файл журнала. Допустимые уровни: trace, debug, info, warning, error и off. Каждый уровень включает все последующие, и с каждым последующим уровнем объём сообщений уменьшается. Вариант off отключает вывод в файл журнала.

По умолчанию: off

--log-backup=уровень_протоколирования

Управляет уровнем сообщений, которые будут выводиться в файл журнала резервного копирования (создаваемый в каталоге резервных копий) во время выполнения команды backup. Допустимые уровни: trace, debug, info, warning, error и off. Каждый уровень включает все последующие, и с каждым последующим уровнем объём сообщений уменьшается. Вариант off отключает вывод в файл журнала.

По умолчанию: info

--log-filename=файл_журнала

Определяет имена для создаваемых файлов журналов. Имена файлов обрабатываются по шаблону strftime, так что вы можете использовать спецкоды с % для выбора имён файлов, зависящих от времени.

Примечание

Начиная с PostgreSQL 17, в shell-командах, таких как archive_command, применяется более строгая проверка местозаполнителей со знаком процента. В этом контексте вместо одинарного % следует использовать %%. Для получения дополнительной информации обратитесь к соответствующему коммиту PostgreSQL.

По умолчанию: pg_probackup.log

Например, если задать шаблон pg_probackup-%%u.log, pg_probackup3 будет записывать журнал в отдельные файлы по дням недели, и символы %%u в имени будут заменяться соответствующим десятичным номером: pg_probackup-1.log в понедельник, pg_probackup-2.log во вторник и т. д.

Также можно использовать счётчик файлов (%%N) и формат strftime (pg_probackup-%%Y-%%m-%%d_%%H%%M%%S.log). Примеры показаны в таблице ниже.

Таблица 4.1. Примеры шаблонов имён файлов

Шаблон	Развёрнутая версия
file_%%N.log	file_1.log, file_2.log...
file_%%3N.log	file_001.log, file_002.log...
file_%%Y%%m%%d.log	file_20080705.log, file_20080706.log...
file_%%Y-%%m-%%d_%%H-%%M-%%S.%%N.log	file_2008-07-05_13-44-23.1.log, file_2008-07-06_16-00-10.2.log...

Этот параметр действует, если включена запись в журнал (параметром --log-level-file).

--error-log-filename=файл_журнала_событий

Определяет имена только для файлов журналов ошибок. Имена файлов обрабатываются по шаблону strftime, так что вы можете использовать спецкоды с % для выбора имён файлов, зависящих от времени.

Примечание

По умолчанию: none

Например, если задать шаблон error-pg_probackup-%%u.log, pg_probackup3 будет записывать журнал в отдельные файлы по дням недели, и символы %%u в имени будут заменяться соответствующим десятичным номером: error-pg_probackup-1.log в понедельник, error-pg_probackup-2.log во вторник и т. д.

Этот параметр полезен для диагностики и решения возникающих проблем.

--log-directory=каталог_журнала

Определяет каталог, в котором будут создаваться файлы журналов. Вы должны задать в этом параметре абсолютный путь. Этот каталог создаётся только при необходимости, когда в журнал выводится первое сообщение.

Обратите внимание, что каталог для файлов журнала всегда создаётся локально, даже если резервные копии создаются в хранилище S3. Поэтому при необходимости обязательно указывайте локальный путь в каталоге_журнала.

По умолчанию: $BACKUP_PATH/log/

--log-format-console=формат_журнала

Определяет формат журнала консоли. Устанавливается только из командной строки. Обратите внимание, что этот параметр нельзя указать в файле конфигурации pg_probackup3.conf посредством команды set-config и что команда backup также воспринимает указание этого параметра в конфигурационном файле как ошибку. Этот параметр может иметь следующие значения:

Если plain, то журнал выводится на консоль в формате обычного текста.
Если json, то журнал выводится на консоль в формате JSON.

По умолчанию: plain

--log-format-file=формат_журнала

Определяет используемый формат файлов журнала. Этот параметр может иметь следующие значения:

Если plain, то файлы журнала записываются в формате обычного текста.
Если json, то файлы журнала записываются в формате JSON.

По умолчанию: plain

--log-rotation-size=размер_журнала_для_ротации

Определяет максимальный размер отдельного файла журнала. Если это значение достигается, файл журнала прокручивается при выполнении какой-либо команды pg_probackup3, за исключением help и version. Нулевое значение отключает прокрутку в зависимости от размера. Допустимые единицы измерения: B, kB (по умолчанию), MB, GB, TB. Используйте счётчик файлов (%N) в шаблоне имени журнала.

По умолчанию: 0

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

Эти параметры могут использоваться с командой backup.

pg_probackup3 поддерживает все переменные окружения libpq.

-d имя_бд --pgdatabase=имя_бд PGDATABASE

Задаёт имя базы данных для подключения. Это подключение используется только для управления процессом резервного копирования, так что вы можете подключиться к любой существующей базе. Если этот параметр не задаётся в командной строке, переменной окружения PGDATABASE или в конфигурационном файле pg_probackup3.conf, pg_probackup3 принимает в качестве имени базы значение переменной окружения PGUSER или имя текущего пользователя, если переменная PGUSER не задана.

-h сервер --pghost=сервер PGHOST

Указывает имя системы, в которой работает сервер. Если значение начинается с косой черты, оно определяет каталог Unix-сокета.

По умолчанию: localhost

-p порт --pgport=порт PGPORT

Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения.

По умолчанию: 5432

-U имя_пользователя --pguser=имя_пользователя PGUSER

Имя пользователя для подключения.

-w --no-password

Не выдавать запрос на ввод пароля. Если сервер требует аутентификацию по паролю и пароль не доступен с помощью других средств, таких как файл .pgpass или переменная окружения PGPASSWORD, попытка соединения не удастся. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, который вводит пароль.

-W --password

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

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

Эти параметры могут использоваться с командами backup и archive-push.

--compress-algorithm=алгоритм_сжатия

Определяет алгоритм, который будет использоваться для сжатия файлов данных. Возможные значения: zlib, lz4, zstd и none. Любое значение, отличное от none, включает сжатие. При этом сжимаются и файлы данных, и файлы WAL. По умолчанию сжатие отключено.

По умолчанию: none

Предупреждение

Значение lz4 для параметра --compress-algorithm в настоящее время не поддерживается в командах archive-push и archive-get.

--compress-level=уровень_сжатия

Определяет уровень сжатия.

Примечание

Этот параметр необходимо использовать вместе с параметром --compress-algorithm.

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

0–9 для zlib
0–22 для zstd

При значении 0 для всех алгоритмов сжатия устанавливается уровень сжатия по умолчанию, равный 1.

Примечание

Алгоритм lz4 на данный момент не поддерживается.

По умолчанию: 1

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

Эти параметры могут использоваться с командой archive-push в значении параметра archive_command и с командой archive-get в значении restore_command.

Дополнительно можно задать параметры SSH и параметры журнала.

--wal-file-path=путь_файлов_wal

Задаёт путь к WAL-файлу, используемому командой archive-push или archive-get.

Путь может быть абсолютным или относительным. Абсолютный путь используется как есть. Относительный путь интерпретируется относительно текущего рабочего каталога. При вызове через archive_command или restore_command Postgres Pro выбирает текущим рабочим каталогом PGDATA, поэтому относительные пути вида pg_wal/... работают корректно.

Примечание

При использовании в archive_command или restore_command Postgres Pro подставляет переменную %p вместо полного пути и %f вместо имени файла перед вызовом pg_probackup3, независимо от того, является путь абсолютным или относительным.

За дополнительной информацией по использованию этого параметра обратитесь к разделу Настройка непрерывного архивирования WAL и описанию команды archive-get.

--wal-file-name=имя_файла_wal

Задаёт имя файла WAL в archive_command и restore_command. В качестве значения для данного параметра укажите %f для правильной его обработки. Если значением параметра --wal-file-path является путь вне каталога данных, следует явно указывать имя файла.

--overwrite

Разрешает перезапись файлов WAL в архиве. Этот ключ действует при выполнении команды archive-push, когда указанный подкаталог каталога резервных копий уже содержит данный файл WAL, и его нужно заменить новой копией. Без этого ключа archive-push сообщит, что сегмент WAL уже существует, и прервёт операцию. Если заменяемый файл не изменился, archive-push пропускает его, независимо от указания --overwrite.

--batch-size=размер_пакета

Используется для ускорения процесса архивирования при выполнении archive-push или процесса восстановления при выполнении archive-get. Задаёт максимальное количество файлов WAL, которое может быть скопировано в архив одним процессом archive-push или из архива одним процессом archive-get. Если не задан явно, для --batch-size по умолчанию используется значение -j/--threads.

--archive-timeout=время_ожидания

Задаёт интервал, по истечении которого существующие файлы .part будут считаться потерянными. По умолчанию pg_probackup3 ждёт исчезновения этих файлов 300 секунд. Этот параметр можно использовать только с командой archive-push.

--no-sync

Не сбрасывать копируемые файлы WAL на диск. Этот флаг позволяет несколько ускорить процесс архивации. Использование этого флага может привести к повреждению архива WAL в случае аварии операционной системы или аппаратного сбоя. Данный параметр можно указать только с командой archive-push.

--prefetch-dir=путь

Каталог, в котором будут храниться предзагружаемые сегменты WAL при использовании параметра --batch-size. Этот каталог должен находиться в той же файловой системе и ниже той же точки монтирования, что и PGDATA/pg_wal. По умолчанию эти сегменты размещаются в каталоге PGDATA/pg_wal/pbk_prefetch. Данный параметр может применяться только с командой archive-get.

Параметры буферизации #

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

--buffer-size=размер: Задаёт размер буфера для операций чтения и записи. Значение должно быть неотрицательным целым числом. При нулевом значении этот параметр отключается. Значение по умолчанию — 128KB.
--buffer-read-size=размер: Задаёт размер отдельного буфера для операций чтения. Должно быть неотрицательным целым числом. При нулевом значении этот параметр отключается. Значение по умолчанию — 0.
--buffer-write-size=размер: Задаёт размер расширенного буфера для операций записи. Должно быть неотрицательным целым числом. При нулевом значении этот параметр отключается. Значение по умолчанию — 0.

Вы можете явно указать единицы измерения для любого из параметров буфера. Допустимые значения: B, kB, MB, GB, TB. Если единица измерения не указана, по умолчанию используются байты.

Параметры S3 #

В этом разделе описываются параметры, которые необходимо задать для размещения копий в частном облачном хранилище. Эти параметры могут задаваться с любыми командами, которые pg_probackup3 выполняет через интерфейс S3.

За подробностями обратитесь к подразделу Настройка подключения к хранилищу S3.

--s3=провайдер_интерфейса_s3

Задаёт провайдера, поддерживающего интерфейс S3. Возможные значения:

minio — объектное хранилище MinIO, совместимое с облачным хранилищем S3. С этим провайдером могут указываться пользовательские параметры сервера S3. По умолчанию используется протокол HTTP, порт 9000 и регион us-east-1.
off — полностью отключает функциональность S3. Это значение по умолчанию для параметра --s3.

При указании --s3=minio pg_probackup3 будет работать с хранилищем VK Cloud, если правильно заданы адрес узла S3, порт и протокол (адрес узла — hb.vkcs.cloud или указанный в соответствующем разделе профиля VK Cloud, порт 443 и протокол HTTPS). Не указывайте --s3=minio при использовании хранилища Amazon S3.

--s3-host=имя_сервера

Задаёт адрес сервера S3. Можно также указать номер порта через двоеточие. Если номер порта не указан в строке адреса, используется значение --s3-port. Добавляйте двоеточие только при указании номера порта.

--s3-port=номер_порта

Задаёт порт сервера S3.

--s3-region=регион

Задаёт регион сервера S3. Значение по умолчанию — us-east-1.

--s3-bucket=бакет

Задаёт имя бакета на сервере S3.

--access-key=ключ_доступа

Задаёт ключ доступа для хранилища S3.

--secret-key=пароль

Задаёт секретный ключ доступа для хранилища S3.

--s3-secure=протокол

Указывает используемый протокол. Допустимые значения:

ON или HTTPS — используется HTTPS.
HTTP — используется HTTP. Это режим по умолчанию.

--s3-retries=число_повторных_попыток

Задаёт максимальное количество попыток выполнения запроса к S3 при возникновении сбоев. Значение по умолчанию — 3.

--s3-timeout=время_ожидания

Задаёт максимальное время выполнения HTTP-запроса к серверу S3 в секундах. Значение по умолчанию — 300.

--s3-ignore-cert-ver=ON|OFF

Позволяет не проверять сертификат узла и узла-партнёра. По умолчанию — OFF.

--s3-ca-certificate=сертификат_ца

Указывает путь к каталогу файла с сертификатом от доверенного центра сертификации (ЦА).

--s3-ca-path=каталог_ца

Указывает каталог, в котором должны храниться сертификаты доверенного ЦС.

--s3-client-cert=клиентский_сертификат

Устанавливает клиентский сертификат SSL.

--s3-client-key=клиентский_ключ

Задаёт файл закрытого ключа для клиентских сертификатов TLS и SSL.

--s3-versioning=enabled|suspended|off

Включает управление версиями объектов в бакете S3. По умолчанию — off.

--s3-http-compression=true|false

Устанавливает HTTP-заголовок «Accept-Encoding» и выполняет распаковку полученного содержимого. По умолчанию — false (отключено).

Ниже описываются параметры производительности S3.

--s3-buffer-size=размер [единица_измерения]: Задаёт размер буфера чтения/записи для взаимодействия с S3. Вы можете явно указать единицы измерения. Допустимые значения: B, kB, MB, GB, TB. Если единица не указана, по умолчанию используется размер в байтах.
Примечание
Значение параметра --s3-buffer-size не должно быть меньше 5 МБ. При указании меньших значений будет выдано предупреждение, а значение автоматически изменится на 5MB.

Параметры SSH #

В этом подразделе описываются параметры, связанные с работой pg_probackup3 в удалённом режиме через SSH. Эти параметры могут использоваться со всеми командами.

Подробнее о настройке и использовании удалённого режима через SSH рассказывается в Разделе 2.12 и Разделе 3.4.

--remote-host=целевой_адрес

Задаёт имя или IP-адрес целевого удалённого сервера.

--remote-port=порт

Задаёт целевой порт на удалённом сервере.

По умолчанию: 22

--remote-user=имя_пользователя

Задаёт имя пользователя на удалённом сервере для SSH-соединения. В отсутствие этого параметра используется имя текущего пользователя, устанавливающего SSH-соединения.

--remote-path=путь

Задаёт каталог, в котором pg_probackup3 установлен на удалённой системе.

--ssh-password=пароль

Задаёт пароль для подключения по SSH.

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

В этом разделе описаны параметры, используемые для задания аргументов доступа к архиву WAL. Эти параметры могут потребоваться при удалённом восстановлении и передаются в команду send-backup для формирования корректного значения restore_command.

--archive-host=целевой_адрес

Задаёт значение аргумента --remote-host для команды archive-get.

--archive-port=порт

Задаёт значение аргумента --remote-port для команды archive-get.

По умолчанию: 22

--archive-user=имя_пользователя

Задаёт значение аргумента --remote-user для команды archive-get. В отсутствие этого указания используется имя пользователя, запускающего кластер Postgres Pro.

По умолчанию: пользователь Postgres Pro

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

В этом подразделе описываются параметры, связанные с частичным резервным копированием и восстановлением кластера. Эти параметры могут передаваться как с командой backup, так и с restore.

--db-exclude-oid=dboid: Задаёт OID базы данных, которая должна быть исключена из числа восстанавливаемых. Все остальные базы данных в кластере будут восстанавливаться, включая template0 и template1. Этот параметр можно задать несколько раз, таким образом исключив несколько баз данных.
--db-include-oid=dboid: Задаёт OID базы данных, которая должна восстанавливаться. Все остальные базы данных восстанавливаться не будут, за исключением template0 и template1. Этот параметр можно задать несколько раз, таким образом выбрав для восстановления несколько баз данных.

Эти параметры используются с командой restore:

--db-exclude-name=имя_бд: Задаёт имя базы данных, которая должна быть исключена из числа восстанавливаемых. Все остальные базы данных в кластере будут восстанавливаться, включая template0 и template1. Этот параметр можно задать несколько раз, таким образом исключив несколько баз данных.
--db-include-name=имя_бд: Задаёт имя базы данных, которая должна восстанавливаться. Все остальные базы данных восстанавливаться не будут, за исключением template0 и template1. Этот параметр можно задать несколько раз, таким образом выбрав для восстановления несколько баз данных.

Предупреждение

Параметры --db-exclude-oid и --db-include-oid, так же как и параметры --db-exclude-name и --db-include-name, использовать вместе нельзя.

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

В этом подразделе описываются параметры, полезные лишь при тестировании или разработке.

PGPROBACKUP_TESTS_SKIP_HIDDEN: Указывает pg_probackup3 игнорировать копии, помеченные как скрытые. Заметьте, что сама утилита pg_probackup3 никогда не помечает копии как скрытые. Добиться такого состояния копии можно, только вручную отредактировав файл backup.control. Задать этот параметр можно только в переменных окружения.
PGPROBACKUP_TESTS_SKIP_EMPTY_COMMIT: Указывает pg_probackup3 пропускать пустые транзакции после pg_backup_stop.

Авторы #

Postgres Professional, Москва, Россия.

Пред.	Наверх	След.
Глава 4. Справка	Начало	Глава 5. Для разработчиков

pg_probackup3
Prev	Up	Chapter 4. Reference	Home	Next

pg_probackup3

pg_probackup3 — utility to manage backup and recovery of Postgres Pro database clusters

Synopsis

pg_probackup3 add-instance -B backup_dir -D data_dir --instance instance_name --skip-if-exists

pg_probackup3 archive-get -B backup_dir --instance instance_name --wal-file-path wal_file_path --wal-file-name wal_file_name [option...]

pg_probackup3 archive-push -B backup_dir --instance instance_name --wal-file-path wal_file_path --wal-file-name wal_file_name [option...]

pg_probackup3 backup -B backup_dir --instance instance_name -b backup_mode [option...]

pg_probackup3 catchup -b catchup_mode --destination-pgdata=path [option...]

pg_probackup3 del-instance -B backup_dir --instance instance_name

pg_probackup3 delete -B backup_dir --instance instance_name -i backup_id

pg_probackup3 file-map -B backup_dir --instance instance_name -i backup_id [option...]

pg_probackup3 fuse -B backup_dir --mnt-path mnt_path --instance instance_name -i backup_id --cache-swap-size cache_swap_size --cache-dir cache_dir [option...]

pg_probackup3 help [command]

pg_probackup3 init -B backup_dir --skip-if-exists

pg_probackup3 merge -B backup_dir --instance instance_name -i backup_id [option...]

pg_probackup3 restore -B backup_dir --instance instance_name [option...]

pg_probackup3 retention -B backup_dir --instance instance_name { --delete-wal | --delete-expired | --merge-expired } [option...]

pg_probackup3 send-backup -B backup_dir --instance instance_name -i backup_id -p port -h host [option...]

pg_probackup3 server-info [option...]

pg_probackup3 set-backup -B backup_dir --instance instance_name -i backup_id [option...]

pg_probackup3 set-config -B backup_dir --instance instance_name [option...]

pg_probackup3 show -B backup_dir [option...]

pg_probackup3 show-config -B backup_dir --instance instance_name [option...]

pg_probackup3 validate -B backup_dir [option...]

pg_probackup3 version

Command-Line Reference #

Commands #

This section describes pg_probackup3 commands. Optional parameters are enclosed in square brackets. For detailed parameter descriptions, see the section Options.

add-instance #

pg_probackup3 add-instance -B backup_dir -D data_dir --instance=instance_name
[--skip-if-exists] [--wal-archive-dir=directory_path] [--wal-tree] [--help]
[s3_options] [ssh_options] [logging_options]
[connection_options] [compression_options] [retention_options]
[buffer_options]

Initializes a new backup instance inside the backup catalog backup_dir and generates the pg_probackup3.conf configuration file that controls pg_probackup3 settings for the cluster with the specified data_dir data directory. If the catalog was already initialized, you can ignore the error by specifying --skip-if-exists.

By default, the WAL archive is stored in backup_dir/wal/instance_name. Use the --wal-archive-dir option to specify a custom directory. The storage type (local filesystem, SFTP, or S3) must match the instance configuration. The directory will be created automatically if it does not exist.

The --wal-tree option sets WAL files to be stored in subdirectories, optimizing disk space. This prevents file system overload, especially NFS (Network File System), which can struggle with excessive files in a single directory.

For more details of the command settings, see sections Common Options and Adding a New Backup Instance.

archive-get #

pg_probackup3 archive-get -B backup_dir --instance=instance_name --wal-file-path=wal_file_path --wal-file-name=wal_file_name
[--help] [-j | --threads=num_threads] [--batch-size=batch_size] [--prefetch-dir=path] [--wal-archive-dir=directory_path]
[ssh_options] [logging_options] [s3_options] [buffer_options]

Copies WAL files from the corresponding subdirectory of the backup catalog to the cluster's write-ahead log location. This command is automatically set by pg_probackup3 as part of the restore_command parameter when restoring backups using a WAL archive. You do not need to set it manually if you use local storage for backups or remote mode.

If you use S3 interface, to ensure that the Postgres Pro server has access to S3 storage to fetch WAL files during restore, you can specify the --config-file option that defines the S3 configuration file with appropriate configuration settings, as described in the section called “Common Options”.

The --wal-file-path option provides the path to the WAL file. This path can be absolute or relative. An absolute path is used as-is. A relative path is interpreted relative to the current working directory. Postgres Pro runs the command from PGDATA, substituting %p (path to the target file, for example, pg_wal/RECOVERYXLOG) and %f (name of the requested segment). The command copies the required segment from the archive to the specified path:

restore_command = 'pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'

You can extract a specific segment from the archive for manual recovery to a point in time or for diagnostic purposes by running the archive-get command with the --wal-file-path option containing an absolute path to the target file:

pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=/var/lib/pgsql/data/pg_wal/RECOVERYXLOG --wal-file-name=000000010000000000000001

You can also manually copy WAL files from the archive to another location, for example, to transfer data to another server or create a test environment:

pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=/mnt/wal_restore/000000010000000000000001 --wal-file-name=000000010000000000000001

The Postgres Pro server requests WAL segments one at a time. To speed up recovery, you can specify the --batch-size option to copy WAL segments in batches of the specified size. If --batch-size is used, you can also specify the -j/--threads option to copy the batch of WAL segments on multiple threads. If --batch-size is not specified but -j/--threads is, --batch-size will default to the -j/--threads value.

For more details of the command settings, see sections Common Options, Archiving Options, and Compression Options.

archive-push #

pg_probackup3 archive-push -B backup_dir --instance=instance_name
--wal-file-name=wal_file_name [--wal-file-path=wal_file_path]
[--help] [--no-sync] [--overwrite] [--wal-archive-dir=directory_path]
[--archive-timeout=wait_time]
[--compress-algorithm=compression_algorithm]
[--compress-level=compression_level]
[-j | --threads=num_threads] [--batch-size=batch_size]
[ssh_options] [logging_options]
[s3_options] [buffer_options]

Copies WAL files into the corresponding subdirectory of the backup catalog and validates the backup instance by instance_name and system-identifier. If parameters of the backup instance and the cluster do not match, this command fails with the following error message: Refuse to push WAL segment segment_name into archive. Instance parameters mismatch.

If the files to be copied already exist in the backup catalog, pg_probackup3 computes and compares their checksums. If the checksums match, archive-push skips the corresponding file and returns a successful execution code. Otherwise, archive-push fails with an error.

Each file is copied to a temporary file with the .part suffix. If the temporary file already exists, pg_probackup3 will wait archive_timeout seconds before discarding it. After the copy is done, atomic rename is performed. This algorithm ensures that a failed archive-push will not stall continuous archiving and that concurrent archiving from multiple sources into a single WAL archive has no risk of archive corruption.

The Postgres Pro server requests WAL segments one at a time. To speed up archiving, you can specify the --batch-size option to copy WAL segments in batches of the specified size. If --batch-size is used, you can also specify the -j/--threads option to copy the batch of WAL segments on multiple threads. If --batch-size is not specified but -j/--threads is, --batch-size will default to the -j/--threads value.

WAL segments copied to the archive are synced to disk unless the --no-sync flag is used.

You can use archive-push in the archive_command Postgres Pro parameter to set up continuous WAL archiving.

For more details of the command settings, see sections Common Options, Archiving Options, and Compression Options.

backup #

pg_probackup3 backup -B backup_dir --instance=instance_name -b backup_mode -s backup_source -i backup_id
[-x | --exclude-path=path_prefix] [--wal-archive-dir=directory_path] [--with-file-map] [--help] [--progress] [-j | --threads=num_threads]
[--num-write-threads num_threads] [--num-validate-threads num_threads]
[--num-segments] [--create-slot] [--transfer-mode] [--stream]
[--no-validate] [--skip-block-validation] [--no-validate-wal]
[--archive-timeout=wait_time] [--external-dirs=external_directory_path]
[--no-sync] [--note=backup_note]
[connection_options] [compression_options] [ssh_options] [partial_backup_options]
[pinning_options] [logging_options] [s3_options] [buffer_options]

Creates a backup copy of the Postgres Pro instance.

-b mode --backup-mode=mode

Specifies the backup mode to use. Possible values: full, delta, ptrack.

-s backup_source --backup-source=backup_source

Specifies the backup data source. Possible values: pro, direct, base. The default is pro.

--wal-archive-dir=directory_path

Specifies the directory for the WAL archive.

--num-segments=num_segments

Specifies the number of the backup segments during the backup creation or merge. Must be a positive integer.

Note

If the specified value exceeds the system limit for simultaneously open files, the process will fail with the error message “too many open files”.

--num-write-threads=num_threads

Specifies the number of threads for copying files. Overrides the j/--threads option for file copying.

--num-validate-threads=num_threads

Specifies the number of threads for the backup validation. Overrides the j/--threads option for the backup validation.

-C --smooth-checkpoint

When enabled, the backup starts at the next scheduled checkpoint. Otherwise, a checkpoint runs immediately, and the backup begins as soon as possible.

--stream

Makes a STREAM backup, which includes all the necessary WAL files by streaming them from the database server via replication protocol.

-x path_prefix --exclude-path=path_prefix

Specifies a prefix for files to exclude from backup. The prefix must contain a path relative to the data directory of an instance. If the prefix specifies a directory, all files in this directory will not be backed up.

--backup-pg-log

Includes the log directory into the backup. This directory usually contains log messages. By default, log directory is excluded.

-E external_directory_path --external-dirs=external_directory_path

Includes the specified directory into the backup by recursively copying its contents into a separate subdirectory in the backup catalog. This option is useful to back up scripts, SQL dump files, and configuration files located outside of the data directory. If you would like to back up several external directories, separate their paths by a colon on Unix and a semicolon on Windows.

--archive-timeout=wait_time

Sets the timeout for WAL segment archiving (ARCHIVE mode), in seconds. By default, pg_probackup3 waits 300 seconds.

Note

For STREAM mode, this option does not apply. The timeout for WAL segment streaming is fixed and set to 10% more than the checkpoint_timeout parameter configured on the server.

--skip-block-validation

Disables block-level checksum verification to speed up the backup process.

--no-validate

Skips automatic validation after the backup is taken. You can use this flag if you validate backups regularly and would like to save time when running backup operations.

It is recommended to use this flag when creating a backup to an S3 storage. Due to some features of S3 storages, automatic validation may appear incorrect in this case. Skip automatic validation and then perform validation using a separate validate command.

--no-validate-wal

Disables validation of WAL files.

Note

The --no-validate option disables validation entirely, including WAL validation, while the --no-validate-wal option disables only WAL validation and does not affect checksum verification.

Warning

Use --no-validate-wal with caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.

--no-sync

Do not sync backed up files to disk. You can use this flag to speed up the backup process. Using this flag can result in data corruption in case of operating system or hardware crash. If you use this option, it is recommended to run the validate command once the backup is complete to detect possible issues.

--note=backup_note

Sets the text note for backup copy. If backup_note contains newline characters, then only substring before first newline character will be saved. Max size of text note is 1 KB. The 'none' value removes current note.

--with-file-map

Enables file map generation. Required for the fuse command.

--transfer-mode=transfer_mode

Specifies the method of sending data from a server to an application.

Note

This option is only available in PRO backup data source mode.

Possible values:

raw: Unpacked data is sent in random blocks of arbitrary size.
packed: Packed data is sent in blocks of 128 KB with a common header.

packed is the default value (recommended).

For more details of the command settings, see sections Common Options, Connection Options, Pinning Options, SSH Options, Compression Options, and Logging Options.

For details on usage, see the section Creating a Backup.

catchup #

pg_probackup3 catchup -b | --backup-mode=catchup_mode --destination-pgdata=path
[-s | --backup-source=catchup_source] [-x | --exclude-path=path_prefix]
[--temp-slot] [-P | --perm-slot] [-S | --slot=slot_name] [-j | --threads=num_threads]
[--num-write-threads=num_threads] [--num-validate-threads=num_threads]
[-T old_dir=new_dir] [-X | --waldir=wal_dir]
[connection_options] [logging_options] [compression_options]

Creates a copy of a Postgres Pro instance without using the backup catalog.

For specifics and limitations of using catchup, refer to Section 3.9.1.

-b catchup_mode --backup-mode=catchup_mode

Specifies the catchup mode to use. Possible values: full, delta, ptrack. The default is full.

--destination-pgdata=path

Specifies the path to the data directory on the target server.

-s catchup_source --backup-source=catchup_source

Specifies the data source mode for synchronization. Possible values: pro, base. The default is pro.

Note

DIRECT mode is currently unsupported.
If PRO is unavailable, pg_probackup3 falls back to BASE mode. For more details, refer to Section 3.9.1.

-j num_threads --threads=num_threads

Sets the number of parallel threads for catchup process.

--num-write-threads=num_threads

Specifies the number of threads for copying files. Overrides the j/--threads option for file copying.

--num-validate-threads=num_threads

Specifies the number of threads for the backup validation. Overrides the j/--threads option for the backup validation.

-x path_prefix --exclude-path=path_prefix

Specifies a prefix for files to exclude from the synchronization of Postgres Pro instances during copying. The prefix must contain a path relative to the data directory of an instance. If the prefix specifies a directory, all files in this directory will not be synchronized.

--temp-slot

Creates a temporary physical replication slot for streaming WAL from the Postgres Pro instance being copied. It ensures that all the required WAL segments remain available if WAL is rotated while the backup is in progress. This flag cannot be used together with the --perm-slot flag. The default slot name is pg_probackup3_wal_streaming_backend_pid, where backend_pid is a PID of the Postgres Pro process. To change it, use the --slot/-S option and explicitly specify --temp-slot.

-P --perm-slot

Creates a permanent physical replication slot for streaming WAL from the Postgres Pro instance being copied. This flag cannot be used together with the --temp-slot flag. The default slot name is pg_probackup_perm_slot, which can be changed using the --slot/-S option.

-S slot_name --slot=slot_name

Specifies the replication slot to connect to for WAL streaming.

-T old_dir=new_dir --tablespace-mapping=old_dir=new_dir

Relocates the tablespace from the old_dir to the new_dir directory at the time of recovery. Both old_dir and new_dir must be absolute paths. If the path contains the equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple tablespaces.

Note

Note the syntax for multiple tablespace mappings: instead of multiple -T flags, use a single flag with colon-separated mapping pairs. For example:

-T old_dir1=new_dir1:old_dir2=new_dir2

-X wal_dir --waldir=wal_dir

Sets the directory to write WAL files to. By default WAL files will be placed in the pg_wal subdirectory of the target directory, but this option can be used to place them elsewhere. wal_dir must be an absolute path, which must not already exist, but if it does, it must be empty to perform catchup in FULL mode.

For more details on using catchup, refer to the Cloning and Synchronizing a Postgres Pro Instance section.

del-instance #

pg_probackup3 del-instance -B backup_dir --instance=instance_name [s3_options] [--help]
[ssh_options] [logging_options] [buffer_options]

Deletes all backups and WAL files associated with the specified instance.

For more details of the command settings, see the section Common Options.

delete #

pg_probackup3 delete -B backup_dir --instance=instance_name -i backup_id
[--help] [--progress] [--status=backup_status]
[--dry-run] [logging_options] [ssh_options]
[s3_options] [buffer_options]

Deletes backups with specified backup_id.

--dry-run: Initiates a trial run of the delete command, which does not actually make any changes, that is, it does not delete files on disk. This flag allows you to check that all the command options are correct and the command is ready to run.
--status: Allows deleting all backups with a specific status.

For details, see the section Deleting Backups.

file-map #

pg_probackup3 file-map -B backup_dir --instance=instance_name -i backup_id

Enables file map generation for an existing backup chain.

If file maps already exist for the specified backups, file-map overwrites them with newly generated versions.

fuse #

pg_probackup3 fuse -B backup_dir --mnt-path=mnt_path --instance=instance_name
-i backup_id [--cache-swap-size=cache_swap_size] [--cache-dir=cache_dir] [--detach] [--unmount] [--help]
[ssh_options] [logging_options] [s3_options] [buffer_options] [recovery_target_options]

Mounts a backup directory as a virtual file system and allows the Postgres Pro server to run on top of it. Refer to Section 3.6 for more details on the process.

--cache-swap-size: Specifies the amount of data (in MB) stored in memory. The default value is 128 MB. When the cache exceeds this size, changes are flushed to the nearby disk. This allows working with a database snapshot without modifying the actual backup. The cache is cleared when the Postgres Pro server is stopped.
--cache-dir=cache_dir: Specifies the path to the FUSE cache directory. If omitted, the system temporary directory is used.
--detach: Sets the FUSE filesystem to be run in the background (by default, it runs in the foreground). This is useful for automation.
--unmount: Unmounts the FUSE filesystem that was previously mounted with the fuse command. This option only requires the mount path (the --mnt-path option), which must be the same that was used for mounting.

help #

pg_probackup3 help [command]

Displays the synopsis of pg_probackup3 commands. If one of the pg_probackup3 commands is specified, shows detailed information about the options that can be used with this command.

init #

pg_probackup3 init -B backup_dir [--skip-if-exists] [s3_options] [--help]
[ssh_options] [logging_options] [buffer_options]

Initializes the backup catalog in backup_dir that will store backup copies, WAL archive, and meta information for the backed up database clusters. If the specified backup_dir already exists, it must be empty. Otherwise, pg_probackup3 displays a corresponding error message. You can ignore this error by specifying the --skip-if-exists option. Although the backup will not be initialized, the application will return 0 code.

For more details of the process, refer to the section Initializing a Backup Catalog. For more details of the command settings, see the section Common Options.

merge #

pg_probackup3 merge -B backup_dir --instance=instance_name -i backup_id --merge-from-id=merge_from --merge-interval=merge_interval
[-t | --target-backup-id=backup_id] [-j | --threads=num_threads] [--progress] [--no-validate] [--no-sync] [--no-validate-wal]
[--with-file-map] [--keep-backups] [--dry-run] [--help] [logging_options] [ssh_options] [s3_options] [buffer_options]

Merges backups that belong to a common incremental backup chain. If you specify a full backup, it will be merged with its first incremental backup. If you specify an incremental backup, it will be merged to its parent full backup, together with all incremental backups between them. Once the merge is complete, the full backup takes in all the merged data, and the incremental backups are removed as redundant. You can also merge chains of incremental backups by specifying the first and the last incremental backup or the time interval (in hours) after the first backup.

--no-validate: Skips automatic validation before and after merge.
--no-validate-wal: Disables validation of WAL files.
Warning
Use --no-validate-wal with caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.
--no-sync: Do not sync merged files to disk. You can use this flag to speed up the merge process. Using this flag can result in data corruption in case of operating system or hardware crash.
-t --target-backup-id: Specifies an ID of the merged backups.
--keep-backups: Preserves original backups after merging.
--merge-from-id: Specifies an ID of the first incremental backup from the backup chain for merge.
--merge-interval: Specifies a time period (in hours) before merging a chain of incremental backups.
--with-file-map: Enables file map generation. Required for the fuse command.

For more details of the command settings, see sections Common Options and Merging Backups.

restore #

pg_probackup3 restore -B backup_dir --instance=instance_name
[--help] [-D data_dir] [-i backup_id] [--wal-archive-dir=directory_path]
[-I | --incremental-mode=incremental_mode] [--progress] [-T old_dir=new_dir] [-X | --waldir=wal_dir]
[--external-mapping=old_dir=new_dir] [--skip-external-dirs]
[-j | --threads=num_threads] [--num-validate-threads=num_threads]
[-R | --restore-as-replica] [--no-validate] [--skip-block-validation] [--no-validate-wal]
[--no-sync] [--restore-command=cmdline]
[--primary-conninfo=primary_conninfo]
[--primary-slot-name=slot_name]
[recovery_target_options] [logging_options] [partial_restore_options]
[ssh_options] [s3_options] [buffer_options]

Restores the Postgres Pro instance from a backup located in the backup_dir backup catalog.

Note

While backup files for restore can be retrieved from different sources (the file system, S3, or SSH SFTP), pg_probackup3 can only restore the Postgres Pro server PGDATA to a local file system.

Note

The restore command does not support the --threads option yet. The number of threads will match the number of segments in the backup.

-R --restore-as-replica

Creates a minimal recovery configuration file to facilitate setting up a standby server. If the replication connection requires a password, you must specify the password manually in the primary_conninfo parameter as it is not included. pg_probackup3 writes these settings into the probackup_recovery.conf file in the data directory and then includes them into the postgresql.auto.conf when the cluster is started.

--primary-conninfo=primary_conninfo

Sets the primary_conninfo parameter to the specified value. This option will be ignored unless the -R flag is specified.

Example: --primary-conninfo="host=192.168.1.50 port=5432 user=foo password=foopass"

--primary-slot-name=slot_name

Sets the primary_slot_name parameter to the specified value. This option will be ignored unless the -R flag is specified.

-I incremental_mode --incremental-mode=incremental_mode

Specifies the incremental mode for the remote restore. Possible values:

CHECKSUM: Replace only pages with mismatched checksum or LSN.
LSN: Replace only pages with LSN greater than point of divergence.

If this option is omitted, a regular (non-incremental) restore is performed.

-T old_dir=new_dir --tablespace-mapping=old_dir=new_dir

Note

Note the syntax for multiple tablespace mappings: instead of multiple -T flags, use a single flag with colon-separated mapping pairs. For example:

-T old_dir1=new_dir1:old_dir2=new_dir2

--external-mapping=old_dir=new_dir

Relocates an external directory included into the backup from the old_dir to the new_dir directory at the time of recovery. Both old_dir and new_dir must be absolute paths. If the path contains the equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple directories.

--skip-external-dirs

Skip external directories included into the backup with the --external-dirs option. The contents of these directories will not be restored.

--skip-block-validation

Disables block-level checksum verification to speed up validation. During automatic validation before the restore only file-level checksums will be verified.

--no-validate

Skips backup validation. You can use this flag if you validate backups regularly and would like to save time when running restore operations.

--no-validate-wal

Disables validation of WAL files.

Warning

Use --no-validate-wal with caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.

--restore-command=cmdline

Sets the restore_command parameter to the specified command. For example: --restore-command='cp /mnt/server/archivedir/%f "%p"'

--wal-archive-dir=directory_path

Specifies the directory for the WAL archive.

--force

Allows to ignore an invalid status of the backup. You can use this flag if you need to restore the Postgres Pro cluster from a corrupt or an invalid backup. Use with caution.

If PGDATA contains a non-empty directory with system ID different from that of the backup being restored, incremental restore with this flag overwrites the directory contents (while an error occurs without the flag). If tablespaces are remapped through the --tablespace-mapping option into non-empty directories, the contents of such directories will be deleted.

--no-sync

Do not sync restored files to disk. You can use this flag to speed up restore process. Using this flag can result in data corruption in case of operating system or hardware crash. If it happens, you have to run the restore command again.

-X wal_dir --waldir=wal_dir

For more details of the command settings, see sections Common Options, Recovery Target Options, SSH Options, Remote WAL Archive Options, Logging Options.

For details on usage, see the section Restoring a Cluster.

retention #

pg_probackup3 retention -B backup_dir --instance=instance_name
[--retention-redundancy] [--retention-window] [--dry-run] [--merge-expired] [--wal-archive-dir=directory_path]
[--delete-expired] [--delete-wal] [pinning_options]
[ssh_options] [s3_options] [buffer_options]

Sets the backup retention policy for an instance or directory and launches backup merge or purge according to the specified parameters.

For more details of the command settings, see the section Retention Options.

send-backup #

pg_probackup3 send-backup -B backup_dir --instance=instance_name -i backup_id -p port -h host
[--no-merge] [-I | --incremental-mode=incremental_mode] [remote_wal_archive_options]

Sends backup data to a remote system via the specified port using multithreading.

This command runs on the local machine that contains the backup catalog.

If a backup was created in ARCHIVE mode and its WAL archive is located on a separate server, specify its access parameters — --archive-host, --archive-port, and --archive-user (remote WAL archive options). These parameter values are passed to the remote side and used to construct restore_command so that the target instance can read WAL from the archive.

-p port --pgport=port

Specifies the port on the remote host.

-h host --pghost=host

Specifies the hostname of the remote host.

--no-merge

Disables merging the backup chain into a temporary file — the data is transferred as-is.

If this option is omitted, the backup chain is merged into a temporary file before the data transfer, which is deleted after the transfer is complete.

-I incremental_mode --incremental-mode=incremental_mode

Specifies the incremental mode for the remote restore. Possible values:

CHECKSUM: Replace only pages with mismatched checksum or LSN.
LSN: Replace only pages with LSN greater than point of divergence.

Warning

The -I option must be used together with --no-merge. Otherwise, the operation will terminate with an error.

For more details, refer to the section Remote Restore.

server-info #

pg_probackup3 server-info [--format=plain|json] [connection_options]

Displays availability of the backup options for the current Postgres Pro instance. Includes basic information about the instance and pg_probackup3 version. Example output is as follows:

CAN_USE_API = true
CAN_USE_CLI = true
CAN_USE_S3 = true
CAN_USE_CFS = true
CAN_USE_FUSE = true
CAN_USE_DIRECT = true
CAN_USE_BASE = true
CAN_USE_PRO = true
CAN_USE_MULTITHREAD = true
IS_PRO_MODE_CONFIGURED = true
IS_DELTA_AVAILABLE = true
IS_PTRACK_CONFIGURED = true
IS_PAGE_AVAILABLE = false
IS_WALSUM_AVAILABLE = false
IS_PGDATA_ACCESS = true
SERVER_CHECKSUM_ENABLED = true
PG_VERSION = 170006
PG_VERSION_STRING = "Postgres Pro (enterprise) 17.6.1 on aarch64-apple23.6.0, compiled by Homebrew clang version 21.1.2, 64-bit"
PG_EDITION_STRING = "enterprise"
PGDATA = "/Users/username/projects/postgrespro/tmp_install/data"
TIMELINE = 1
SYSTEM_ID = 75800766633445207
PG_MAX_WAL_SENDERS = 20
PG_BLOCK_SIZE = 8192
PG_BLOCKS_IN_SEGMENT = 131072
PG_WAL_BLOCK_SIZE = 8192
PG_WAL_SEGMENT_SIZE = 16777216
PG_TABLESPACE_MAP = "[]"
APP_VERSION = 3.2.0

By default, the output is shown as plain text. Specify the --format=json option to get the result in the JSON format.

The CAN_USE_* parameters reflect licensing limitations and show which features are enabled in the current Postgres Pro version.

set-backup #

pg_probackup3 set-backup -B backup_dir --instance=instance_name -i backup_id
{--ttl=ttl | --expire-time=time}
[--note=backup_note] [ssh_options]
[s3_options] [--help] [logging_options] [buffer_options]

Sets the provided backup-specific settings into the backup.control configuration file, or modifies the previously defined values.

--note=backup_note: Sets the text note for backup copy. If backup_note contains newline characters, then only the substring before the first newline character will be saved. The maximum size of a text note is 1 KB. The 'none' value removes the current note.

For more details of the command settings, see sections Common Options and Pinning Options.

set-config #

pg_probackup3 set-config -B backup_dir --instance=instance_name
[--help] [--pgdata=pgdata-path] [--wal-archive-dir=directory_path] [--wal-tree]
[--retention-redundancy=redundancy][--retention-window=window]
[compression_options] [connection_options]
[--archive-timeout=wait_time] [--external-dirs=external_directory_path]
[logging_options] [ssh_options] [buffer_options]

Adds the specified connection, compression, retention, logging, and external directory settings into the pg_probackup3.conf configuration file, or modifies the previously defined values.

For all available settings, see the Options section.

It is not recommended to edit pg_probackup3.conf manually.

show #

pg_probackup3 show -B backup_dir
[--help] [--instance=instance_name [-i backup_id | --archive [--wal-archive-dir=directory_path]]]
[--show-log] [--format=plain|json] [--no-color] [--format=plain|json|tree]
[s3_options] [ssh_options]
[logging_options] [buffer_options]

Shows the contents of the backup catalog. If instance_name and backup_id are specified, shows detailed information about this backup. If the --archive option is specified, shows the contents of the WAL archive, which is located in backup_dir/wal/instance_name by default. Use the --wal-archive-dir option to specify a custom directory.

By default, the contents of the backup catalog is shown as plain text. You can specify the --format=json option to get the result in the JSON format. If --no-color flag is used, then the output is not colored. You can also use the --format=tree option to see the list of backups as a tree.

For details on usage, see the sections Managing the Backup Catalog and Viewing WAL Archive Information.

show-config #

pg_probackup3 show-config -B backup_dir --instance instance_name
[--format=plain|json] [s3_options] [ssh_options]
[logging_options] [buffer_options]

Displays all the current pg_probackup3 configuration settings, including those that are specified in the pg_probackup3.conf configuration file located in the backup_dir/backups/instance_name directory and those that were provided on a command line. The configuration settings are shown as plain text.

To edit pg_probackup3.conf, use the set-config command.

validate #

pg_probackup3 validate -B backup_dir
[--help] [--instance=instance_name] [-i backup_id]
[-j | --threads=num_threads] [--progress]
[--skip-block-validation] [--no-validate-wal] [buffer_options]
[logging_options] [ssh_options] [s3_options]

Verifies that all the files required to restore the cluster are present and are not corrupt. If you specify the instance_name without any additional options, pg_probackup3 validates all the backups available for this backup instance.

If the --progress option is specified, a list of the backup files and directories will be displayed during the validation process.

The --no-validate-wal option disables validation of WAL files.

Warning

Use --no-validate-wal with caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.

version #

pg_probackup3 version

Prints pg_probackup3 version.

If --format=json is specified, the output is printed in the JSON format. This may be needed for native integration with JSON-based applications, such as PPEM. Example of a JSON output:

        pg_probackup3 version
        {
            "pg_probackup3":
            {
                "version": "3.0.0",
            },
            "compressions": [zlib, lz4, zstd]
        }

Options #

This section describes command-line options for pg_probackup3 commands. If the option value can be derived from an environment variable, this variable is specified below the command-line option, in the uppercase. Some values can be taken from the pg_probackup3.conf configuration file located in the backup catalog.

For details, see Section 2.5.

If an option is specified using more than one method, command-line input has the highest priority, while the pg_probackup3.conf settings have the lowest priority.

Common Options #

The list of general options.

--dry-run

Initiates a trial run of the appropriate command, which does not actually do any changes, that is, it does not create, delete or move files on disk. This flag allows you to check that all the command options are correct and the command is ready to run. WAL streaming is skipped with --dry-run.

-B directory --backup-path=directory BACKUP_PATH

Specifies the absolute path to the backup catalog. Backup catalog is a directory where all backup files and meta information are stored. Since this option is required for most of the pg_probackup3 commands, you are recommended to specify it once in the BACKUP_PATH environment variable. In this case, you do not need to use this option each time on the command line.

-D directory --pgdata=directory PGDATA

Specifies the absolute path to the data directory of the database cluster. This option is mandatory only for the add-instance command. Other commands can take its value from the PGDATA environment variable, or from the pg_probackup3.conf configuration file.

-i backup_id --backup-id=backup_id

Specifies the unique identifier of the backup.

--parent-backup-id=parent_backup_id

Specifies the unique identifier of the parent backup (used for incremental backups).

--from-full

Creates an incremental backup from the latest parent FULL backup.

-j num_threads --threads=num_threads PG_PROBACKUP_MAX_THREADS

Sets the number of parallel threads for backup, catchup, merge, validate, archive-push, and archive-get processes. Defaults to the number of CPU cores.

If the -j option is not specified, but the PG_PROBACKUP_MAX_THREADS environment variable is set, the thread count is automatically determined based on available CPU cores but is capped by the PG_PROBACKUP_MAX_THREADS value.

--num-validate-threads num_threads

Sets the number of parallel threads during the backup validation, for example, when running the backup or restore command.

--no-validate disables --num-validate-threads.

--progress

Shows the progress of operations.

--help

Shows detailed information about the options that can be used with this command.

-v version --version=version

Shows pg_probackup3 version.

--config-file=file_name

Specifies the S3 or SSH configuration file. Settings in the configuration file override the environment variables.

To generate the configuration file, run the set-config command with the --config-file option.

The generated file will include all explicitly specified S3 or SSH parameters, while passwords will be omitted and displayed as asterisks.

An example of the S3 configuration file:

access-key=admin
s3=on
s3-bucket=test
s3-host=127.0.0.1
s3-port=9000
s3-region=us-west-2
secret-key=***

If the configuration file contains both S3 and SSH options, S3 options will be used.

If the --config-file option is not specified, pg_probackup3 will first look for S3 and SSH configuration files at /etc/pg_probackup/s3.config or /etc/pg_probackup/ssh.config and then at ~postgres/.pg_probackup/s3.config or ~postgres/.pg_probackup/ssh.config, respectively.

Recovery Target Options #

If continuous WAL archiving is configured, you can use one of these options with restore command to specify the moment up to which the database cluster must be restored.

Warning

Recovery targets are mutually exclusive — only one option can be specified at a time.

--recovery-target-stop=immediate|latest

Defines when to stop the recovery:

The immediate value stops the recovery after reaching the consistent state of the specified backup. This is the default behavior for STREAM backups.
The latest value continues the recovery until all WAL segments available in the archive are applied. Setting this value of --recovery-target also sets --recovery-target-timeline to latest.

--recovery-target-timeline=timeline

Specifies a particular timeline to be used for recovery:

current — the timeline of the specified backup, default.

latest — the timeline of the latest available backup.
A numeric value.

--recovery-target-lsn=lsn

Specifies the LSN of the write-ahead log location up to which recovery will proceed.

--recovery-target-name=recovery_target_name

Specifies a named savepoint up to which to restore the cluster.

--recovery-target-time=time|current|latest

Specifies the timestamp up to which recovery will proceed. If the time zone offset is not specified, the local time zone is used.

Example: --recovery-target-time="2027-04-09 18:21:32+00"

--recovery-target-xid=xid

Specifies the transaction ID up to which recovery will proceed.

--recovery-target-inclusive=boolean

Specifies whether to stop just after the specified recovery target (true), or just before the recovery target (false). This option can only be used together with --recovery-target-time, --recovery-target-lsn or --recovery-target-xid options. The default depends on the recovery_target_inclusive parameter.

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

Specifies the action (recovery_target_action) the server should take when the recovery target is reached.

Default: pause

Retention Options #

These options are used with the retention command.

For details on configuring retention policy, see the section Configuring Retention Policy.

--retention-redundancy=redundancy

Specifies the number of full backup copies to keep in the data directory. Must be a non-negative integer. The zero value disables this setting.

Default: 0

--retention-window=window

Specifies the number of days of recoverability. Must be a non-negative integer. The zero value disables this setting.

Default: 0

--delete-wal

Deletes WAL files that are no longer required to restore the cluster from any of the existing backups.

--delete-expired

Deletes backups that do not conform to the retention policy defined in the pg_probackup3.conf configuration file.

--merge-expired

Merges the oldest incremental backup that satisfies the requirements of retention policy with its parent backups that have already expired.

Pinning Options #

You can use these options together with backup, set-backup, and retention commands.

For details on backup pinning, see the section Backup Pinning.

--ttl=ttl

Specifies the amount of time the backup should be pinned. Must be a non-negative integer. The zero value unpins the already pinned backup. Supported units: ms, s, min, h, d (s by default).

Example: --ttl=30d

--expire-time=time

Specifies the timestamp up to which the backup will stay pinned. Must be an ISO-8601 complaint timestamp. If the time zone offset is not specified, the local time zone is used.

Example: --expire-time="2027-04-09 18:21:32+00"

Logging Options #

You can use these options with any command.

--no-color

Disable coloring for console log messages of warning and error levels.

--log-level-console=log_level

Controls which message levels are sent to the console log. Valid values are trace, debug, info, warning, error and off. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The off level disables console logging.

Default: info

Note

All console log messages are going to stderr, so the output of show and show-config commands does not mingle with log messages.

--log-level-file=log_level

Controls which message levels are sent to a log file. Valid values are trace, debug, info, warning, error, and off. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The off level disables file logging.

Default: off

--log-backup=log_level

Controls which message levels are sent to a backup log file created in the backup directory when running the backup command. Valid values are trace, debug, info, warning, error, and off. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. The off level disables file logging.

Default: info

--log-filename=log_filename

Defines the filenames of the created log files. The filenames are treated as a strftime pattern, so you can use %-escapes to specify time-varying filenames.

Note

Starting from PostgreSQL 17, stricter validation of percent-sign placeholders takes place in shell commands such as archive_command. In this context, %% should be used instead of single %. For more details, refer to the corresponding PostgreSQL commit.

Default: pg_probackup.log

For example, if you specify the pg_probackup-%%u.log pattern, pg_probackup3 generates a separate log file for each day of the week, with %%u replaced by the corresponding decimal number: pg_probackup-1.log for Monday, pg_probackup-2.log for Tuesday, and so on.

You can also use the file counter (%%N) and strftime format (pg_probackup-%%Y-%%m-%%d_%%H%%M%%S.log). The examples are shown in the table below.

Table 4.1. Filename Template Examples

Template	Expands to
file_%%N.log	file_1.log, file_2.log...
file_%%3N.log	file_001.log, file_002.log...
file_%%Y%%m%%d.log	file_20080705.log, file_20080706.log...
file_%%Y-%%m-%%d_%%H-%%M-%%S.%%N.log	file_2008-07-05_13-44-23.1.log, file_2008-07-06_16-00-10.2.log...

This option takes effect if file logging is enabled by the --log-level-file option.

--error-log-filename=error_log_filename

Defines the filenames of log files for error messages only. The filenames are treated as a strftime pattern, so you can use %-escapes to specify time-varying filenames.

Note

Default: none

For example, if you specify the error-pg_probackup-%%u.log pattern, pg_probackup3 generates a separate log file for each day of the week, with %%u replaced by the corresponding decimal number: error-pg_probackup-1.log for Monday, error-pg_probackup-2.log for Tuesday, and so on.

This option is useful for troubleshooting and monitoring.

--log-directory=log_directory

Defines the directory in which log files will be created. You must specify the absolute path. This directory is created lazily, when the first log message is written.

Note that the directory for log files is always created locally even if backups are created in the S3 storage. So be sure to pass a local path in log_directory when needed.

Default: $BACKUP_PATH/log/

--log-format-console=log_format

Defines the format of the console log. Only set from the command line. Note that you cannot specify this option in the pg_probackup3.conf configuration file through the set-config command and that the backup command also treats this option specified in the configuration file as an error. Possible values are:

plain — sets the plain-text format of the console log.
json — sets the JSON format of the console log.

Default: plain

--log-format-file=log_format

Defines the format of log files used. Possible values are:

plain — sets the plain-text format of log files.
json — sets the JSON format of log files.

Default: plain

--log-rotation-size=log_rotation_size

Defines the maximum size of an individual log file. If this value is reached, the log file is rotated once any pg_probackup3 command, except help or version, is launched. The zero value disables size-based rotation. Available unit values: B, kB, MB, GB, TB. If no unit is specified, the value defaults to bytes. Use file counter (%N) in the log filename pattern.

Default: 0

Connection Options #

You can use these options together with the backup command.

All libpq environment variables are supported.

-d dbname --pgdatabase=dbname PGDATABASE

Specifies the name of the database to connect to. The connection is used only for managing backup process, so you can connect to any existing database. If this option is not provided on the command line, PGDATABASE environment variable, or the pg_probackup3.conf configuration file, pg_probackup3 tries to take this value from the PGUSER environment variable, or from the current user name if PGUSER variable is not set.

-h host --pghost=host PGHOST

Specifies the host name of the system on which the server is running. If the value begins with a slash, it is used as a directory for the Unix domain socket.

Default: localhost

-p port --pgport=port PGPORT

Specifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections.

Default: 5432

-U username --pguser=username PGUSER

User name to connect as.

-w --no-password

Disables a password prompt. If the server requires password authentication and a password is not available by other means such as a .pgpass file or PGPASSWORD environment variable, the connection attempt will fail. This flag can be useful in batch jobs and scripts where no user is present to enter a password.

-W --password

Forces a password prompt. (Deprecated)

Compression Options #

You can use these options together with backup and archive-push commands.

--compress-algorithm=compression_algorithm

Defines the algorithm to use for compressing data files. Possible values are zlib, lz4, zstd, and none. If set to any value but none, this option enables compression that uses the corresponding algorithm. Both data files and WAL files are compressed. By default, compression is disabled.

Default: none

Warning

Option value lz4 for --compress-algorithm isn't currently supported in archive-push and archive-get commands.

--compress-level=compression_level

Defines the compression level.

Note

This option must be used together with the --compress-algorithm option.

Possible values depend on the compression algorithm specified:

0–9 for zlib
0–22 for zstd

The value of 0 sets the default compression level, which is 1, for all compression algorithms.

Note

The lz4 algorithm is not currently supported.

Default: 1

Archiving Options #

These options can be used with the archive-push command in the archive_command setting and the archive-get command in the restore_command setting.

Additionally, SSH options and logging options can be used.

--wal-file-path=wal_file_path

Provides the path to the WAL file used by the archive-push or archive-get command.

The path can be absolute or relative. An absolute path is used as-is. A relative path is interpreted relative to the current working directory. When invoked via archive_command or restore_command, Postgres Pro sets the current working directory to PGDATA, so relative paths like pg_wal/... work correctly.

Note

When used in archive_command or restore_command, Postgres Pro substitutes the %p variable for the full path and %f for the file name before calling pg_probackup3, regardless of whether the path is absolute or relative.

For more information on using this option, refer to the Setting up Continuous WAL Archiving section and the archive-get command description.

--wal-file-name=wal_file_name

Provides the name of the WAL file in archive_command and restore_command. Use the %f variable as the value for this option for correct processing. If the value of --wal-file-path is a path outside of the data directory, explicitly specify the filename.

--overwrite

Overwrites archived WAL file. Use this flag together with the archive-push command if the specified subdirectory of the backup catalog already contains this WAL file and it needs to be replaced with its newer copy. Otherwise, archive-push reports that a WAL segment already exists, and aborts the operation. If the file to replace has not changed, archive-push skips this file regardless of the --overwrite flag.

--batch-size=batch_size

Used to speed up archiving in case of archive-push or to speed up recovery in case of archive-get. Sets the maximum number of WAL files that can be copied into the archive by a single archive-push process or from the archive by a single archive-get process. If not specified, --batch-size defaults to the -j/--threads value.

--archive-timeout=wait_time

Sets the timeout for considering existing .part files to be stale. By default, pg_probackup3 waits 300 seconds. This option can be used only with the archive-push command.

--no-sync

Do not sync copied WAL files to disk. You can use this flag to speed up archiving process. Using this flag can result in WAL archive corruption in case of operating system or hardware crash. This option can be used only with archive-push command.

--prefetch-dir=path

Directory used to store prefetched WAL segments if --batch-size is used. Directory must be located on the same filesystem and on the same mountpoint the PGDATA/pg_wal is located. By default files are stored in PGDATA/pg_wal/pbk_prefetch directory. This option can be used only with archive-get command.

Buffer Options #

You can use these options with all commands.

--buffer-size=size: Specifies the buffer size for read and write operations. Must be a non-negative integer. The zero value disables this setting. The default is 128KB.
--buffer-read-size=size: Specifies a separate buffer size for read operations. Must be a non-negative integer. The zero value disables this setting. The default value is 0.
--buffer-write-size=size: Specifies a separate extended buffer size for write operations. Must be a non-negative integer. The zero value disables this setting. The default value is 0.

You can explicitly specify units for any of the buffer options. Possible values: B, kB, MB, GB, TB. If no unit is specified, the value defaults to bytes.

S3 Options #

This section describes the options needed to store backups in private clouds. These options can be used with any command that pg_probackup3 runs using S3 interface.

For more details, refer to the section Configuring S3 Connection section.

--s3=s3_interface_provider

Specifies the S3 interface provider. Possible values are:

minio — MinIO object storage, compatible with S3 cloud storage service. With this provider, custom S3 server settings can be specified. The HTTP protocol, port 9000, and region us-east-1 are used by default.
off — explicitly disables S3 mode. This is the default value for --s3 option.

With --s3=minio, pg_probackup3 will work fine for a VK Cloud storage if the S3 host address, port and protocol are properly specified (host address is hb.vkcs.cloud or the one specified in the appropriate section of the VK Cloud profile, port 443, and HTTPS protocol). Do not specify --s3=minio for the Amazon S3 storage.

--s3-host=hostname

Specifies the address of the S3 server. Can include the port number, separated by a colon. If the port number is not specified in a host string, the value of --s3-port is assumed. Do not add a colon if the port number is not specified.

--s3-port=port_number

Specifies the port of the S3 server.

--s3-region=region

Specifies the region of the S3 server. The default is us-east-1.

--s3-bucket=bucket

Specifies the name of the bucket on the S3 server.

--access-key=access_key

Specifies the access key from S3 storage.

--secret-key=password

Specifies the secret access key from S3 storage.

--s3-secure=protocol

Specifies the protocol to be used. Possible values:

ON or HTTPS — HTTPS is used.
HTTP — HTTP is used. This is the default value.

--s3-retries=retry_count

Sets the maximum number of attempts to execute an S3 request in case of failures. The default is 3.

--s3-timeout=timeout

Sets the maximum amount of time to execute an HTTP request to the S3 server, in seconds. The default is 300.

--s3-ignore-cert-ver=ON|OFF

Allows to skip the certificate host and peer verification. The default is OFF.

--s3-ca-certificate=ca_certificate

Specifies the path to the file with a trust Certificate Authority (CA) bundle.

--s3-ca-path=ca_path

Specifies the directory with trust CA certificates.

--s3-client-cert=client_cert

Sets the SSL client certificate.

--s3-client-key=client_key

Sets the private key file for the TLS and SSL client certificates.

--s3-versioning=enabled|suspended|off

Sets the S3 bucket support for object versioning. The default is off.

--s3-http-compression=true|false

Sets the "Accept-Encoding" HTTP header and decompresses received contents. The default is false.

The S3 performance options are described below.

--s3-buffer-size=size [unit]: Specifies the size of the read/write buffer for communicating with S3. You can explicitly specify units. Possible values: B, kB, MB, GB, TB. If no unit is specified, the value defaults to bytes.
Note
The --s3-buffer-size value must not be less than 5 MB. Smaller values will trigger a warning and will be automatically switched to 5MB.

SSH Options #

This section describes the options related to running pg_probackup3 operations remotely via SSH. These options can be used with all commands.

For details on configuring and using the remote mode via SSH, see Section 2.12 and Section 3.4.

--remote-host=destination

Specifies the remote host IP address or hostname to connect to.

--remote-port=port

Specifies the remote host port to connect to.

Default: 22

--remote-user=username

Specifies remote host user for SSH connection. If you omit this option, the current user initiating the SSH connection is used.

--remote-path=path

Specifies pg_probackup3 installation directory on the remote system.

--ssh-password=password

Specifies the password for SSH connection.

Remote WAL Archive Options #

This section describes the options used to provide the arguments for accessing the WAL archive. These options may be required for remote restore and are passed to the send-backup command to construct a proper restore_command.

--archive-host=destination

Provides the argument for the --remote-host option in the archive-get command.

--archive-port=port

Provides the argument for the --remote-port option in the archive-get command.

Default: 22

--archive-user=username

Provides the argument for the --remote-user option in the archive-get command. If you omit this option, the user that has started the Postgres Pro cluster is used.

Default: Postgres Pro user

Partial Backup and Restore Options #

This section describes the options for partial cluster backup and restore. These options can be used with both the backup and restore commands:

--db-exclude-oid=dboid: Specifies the OID of the database to exclude from restore. All other databases in the cluster will be restored as usual, including template0 and template1. This option can be specified multiple times for multiple databases.
--db-include-oid=dboid: Specifies the OID of the database to restore from a backup. All other databases in the cluster will not be restored, with the exception of template0 and template1. This option can be specified multiple times for multiple databases.

These options can be used with the restore command:

--db-exclude-name=dbname: Specifies the name of the database to exclude from restore. All other databases in the cluster will be restored as usual, including template0 and template1. This option can be specified multiple times for multiple databases.
--db-include-name=dbname: Specifies the name of the database to restore from a backup. All other databases in the cluster will not be restored, with the exception of template0 and template1. This option can be specified multiple times for multiple databases.

Warning

Options --db-exclude-oid and --db-include-oid cannot be used together, as well as --db-exclude-name and --db-include-name.

Testing and Debugging Options #

This section describes options useful only in a test or development environment.

PGPROBACKUP_TESTS_SKIP_HIDDEN: Instructs pg_probackup3 to ignore backups marked as hidden. Note that pg_probackup3 can never mark a backup as hidden. It can only be done by directly editing the backup.control file. This option can only be set with environment variables.
PGPROBACKUP_TESTS_SKIP_EMPTY_COMMIT: Instructs pg_probackup3 to skip empty commits after pg_backup_stop.

Authors #

Postgres Professional, Moscow, Russia.

Prev	Up	Next
Chapter 4. Reference	Home	Chapter 5. For Developers