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

pg_probackup3

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

Синтаксис

pg_probackup3 version

pg_probackup3 help [команда]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Команды #

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

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]
        }

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.

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

add-instance #

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

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

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

del-instance #

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

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

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

set-config #

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

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

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

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

set-backup #

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

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

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

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

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

show-config #

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

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

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

show #

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

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

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

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

backup #

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

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

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

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

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

Указывает источник данных для резервного копирования. Возможные значения: DIRECT, BASE и PRO.

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

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

Примечание

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

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

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

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

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

-C
--smooth-checkpoint

Растягивает выполнение контрольной точки во времени. По умолчанию pg_probackup3 пытается произвести контрольную точку максимально быстро.

--stream

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

--temp-slot[=true|false|on|off]

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

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

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

--backup-pg-log

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

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

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

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

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

--skip-block-validation

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

--no-validate

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

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

--no-sync

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

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

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

--with-file-map

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

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

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

restore #

pg_probackup3 restore -B каталог_копий --instance=имя_экземпляра
[--help] [-D каталог_данных] [-i ид_резервной_копии]
[--progress] [-T СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ]
[--external-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ] [--skip-external-dirs]
[-j число_потоков] [--num-validate-threads число_потоков]
[--no-validate] [--skip-block-validation]
[--no-sync] [--restore-command=команда]
[--primary-conninfo=строка_подключения]
[ --primary-slot-name=имя_слота]
[параметры_точки_восстановления] [параметры_журнала]
[параметры_ssh] [параметры_s3] [параметры_буферизации]

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

Примечание

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

Примечание

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

--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.

-T СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ
--tablespace-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ

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

--external-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ

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

--skip-external-dirs

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

--skip-block-validation

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

--no-validate

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

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

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

--no-sync

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

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

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

validate #

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

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

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

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

merge #

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

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

--no-validate

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

--no-sync

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

-t
--target-backup-id

Задаёт идентификатор объединённой резервной копии.

--keep-backups

Сохраняет исходные резервные копии после объединения.

--merge-from-id

Указывает идентификатор первой резервной копии в цепочке копий для объединения.

--merge-interval

Задаёт время (в часах) перед объединением цепочки инкрементальных резервных копий.

--with-file-map

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

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

delete #

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

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

--dry-run

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

--status

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

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

archive-push #

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

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

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

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

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

Команду archive-push можно использовать в значении параметра archive_command Postgres Pro при настройке непрерывного архивирования WAL.

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

fuse #

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

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

--cache-swap-size

Задаёт объём данных (в МБ), хранящихся в оперативной памяти. Значение по умолчанию — 128 МБ. При превышении этого размера изменения сбрасываются на ближайший диск. Это позволяет работать со снимком состояния базы данных, не изменяя исходную резервную копию. Кеш очищается после остановки сервера Postgres Pro.

--cache-dir=каталог_кеша

Указывает путь к каталогу кеша FUSE. Если этот параметр опущен, используется системный временный каталог.

file-map #

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

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

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

archive-get #

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

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

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

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

retention #

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

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

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

Параметры #

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

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

Если некоторый параметр задаётся несколькими способами, значение в командной строке имеет наивысший приоритет, а значение в 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=число_потоков

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

--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, так что вы можете использовать спецкоды с % для выбора имён файлов, зависящих от времени.

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

Например, если задать шаблон pg_probackup-%u.log, pg_probackup3 будет записывать журнал в отдельные файлы по дням недели, и символы %u в имени будут заменяться соответствующим десятичным номером: pg_probackup-1.log в понедельник, pg_probackup-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. Нулевое значение отключает прокрутку в зависимости от размера. Поддерживаются следующие единицы: kB (по умолчанию), MB, GB, TB.

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

--log-rotation-age=возраст_журнала_для_ротации

Максимальное время жизни отдельного файла журнала. Если это значение достигается, файл журнала прокручивается при выполнении какой-либо команды pg_probackup3, за исключением help и version. Время создания последнего файла журнала сохраняется в $BACKUP_PATH/log/log_rotation. Нулевое значение отключает прокрутку по времени. Поддерживаемые единицы: ms (миллисекунды), s (секунды), min (минуты, по умолчанию), h (часы), d (дни).

По умолчанию: 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 — 12 для lz4

  • 0 — 22 для zstd

При значении 0 устанавливается уровень сжатия по умолчанию для указанного алгоритма:

  • 6 для zlib

  • 9 для lz4

  • 3 для zstd

Примечание

Обычный алгоритм lz4 имеет только один уровень сжатия — 1. Так что, если указан алгоритм сжатия lz4 и значение --compress-level больше 1, фактически используется алгоритм lz4hc, который работает намного медленнее, но обеспечивает лучшее сжатие.

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

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

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

Дополнительно вы можете задать параметры удалённого режима и ведения журнала.

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

Задаёт путь файла WAL в archive_command и restore_command. В качестве значения для данного параметра укажите %p или явно задайте путь к файлу вне каталога данных. Если этот параметр не задан, используется путь, заданный в файле pg_probackup3.conf.

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

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

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

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

--no-sync

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

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

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

--buffer-size=размер

Задаёт размер буфера для операций чтения и записи. Должно быть неотрицательным целым числом. При нулевом значении этот параметр отключается. Значение по умолчанию — 0.

--buffer-read-size=размер

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

--buffer-write-size=размер

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

Для любого параметра буферизации можно явно указать единицы измерения:

  • B — байты

  • KB — килобайты

  • MB — мегабайты

  • GB — гигабайты

  • TB — терабайты

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

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

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

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

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

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

--remote-port=порт

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

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

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

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

--remote-path=путь

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

--ssh-options=параметры_ssh

Задаёт строку параметров командной строки для SSH. Например, следующим образом можно установить свойства keep-alive для SSH-подключений, которые будет открывать pg_probackup3: --ssh-options="-o ServerAliveCountMax=5 -o ServerAliveInterval=60". Полный список всех параметров можно найти в руководстве по ssh_config.

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

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

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

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

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

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

--archive-port=порт

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

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

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

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

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

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

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

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

Выбирает инкрементальный режим. Поддерживаются следующие режимы:

  • CHECKSUM — заменять только страницы с неподходящей контрольной суммой и LSN.

  • LSN — заменять только те страницы, LSN которых больше точки расхождения.

  • NONE — обычное восстановление.

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

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

--db-exclude-oid=dboid

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

--db-include-oid=dboid

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

--db-exclude-name=имя_бд

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

--db-include-name=имя_бд

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

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

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

Параметры S3 #

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

За подробностями обратитесь к подразделу Настройка подключения к хранилищу 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.

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

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

--cfs-nondatafile-mode

Указывает команде backup выполнить резервное копирование CFS в режиме предыдущих версий. Этот параметр позволяет настраивать совместимость с версиями pg_probackup3 ниже 2.6.0 и предназначен в основном для тестирования.

PGPROBACKUP_TESTS_SKIP_HIDDEN

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

--destroy-all-other-dbs

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

Важно

Никогда не используйте этот флаг в производственном кластере.

PGPROBACKUP_TESTS_SKIP_EMPTY_COMMIT

Указывает pg_probackup3 пропускать пустые транзакции после pg_backup_stop.

Авторы #

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

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