pg_probackup3
Пред. Глава 5. Справка След.

Название

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 порог_сброса_кеша [параметр...]

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] [-j число_потоков] [--progress]
[--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 ( --backup-threads j/--threads --validate-threads j/--threads -C --smooth-checkpoint pg_probackup3 --stream STREAM), --temp-slot[=true|false|on|off] Postgres Pro. --temp-slot --stream. pg_probackup_slot. --slot/-S --temp-slot --temp-slot=true|on. -S --slot= --stream. --backup-pg-log log. log -E --external-dirs= --archive-timeout= pg_probackup3 --skip-block-validation --no-validate . --no-sync --note= 'none' --wal-file-path .

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

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

restore

pg_probackup3 restore -B каталог_копий --instance=имя_экземпляра
[--help] [-D каталог_данных] [-i ид_резервной_копии]
[--progress] [-T СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ]
[--external-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ] [--skip-external-dirs]
[--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

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

--wal-file-path

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

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

delete

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

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

--no-sync

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

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

archive-push

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

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

--cache-swap-size

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

Чтобы использовать смонтированную резервную копию как PGDATA, укажите путь_монтирования в качестве пути для параметра -D при запуске Postgres Pro командой pg_ctl start.

Примечание

Цепочка резервных копий для монтирования должна включать параметр --with-file-map. Этот параметр используется в операциях резервного копирования and объединения.

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 во время восстановления вы можете указать параметр --s3-config-file, определяющий файл конфигурации S3 с требуемыми параметрами конфигурации, как описано в «Параметры 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, находящегося в каталоге копий.

За подробностями обратитесь к «Настройка pg_probackup3».

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

--progress

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

--help

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

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

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

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

Если настроено непрерывное архивирование 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=уровень_сообщений

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

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

Примечание

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

--log-level-file=уровень_сообщений

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

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

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

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

--compress

Задаёт алгоритм сжатия по умолчанию и устанавливает --compress-level=1. Алгоритм по умолчанию выбирается среди поддерживаемых Postgres Pro в соответствии с приоритетами: zstd (самый высокий) -> lz4 -> zlib. Параметр --compress переопределяет параметры --compression-algorithm и --compress-level и не может быть использован одновременно с ними.

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

Эти параметры могут использоваться с командой 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.

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

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

Подробнее о настройке и использовании удалённого режима рассказывается в «Настройка удалённого режима» и «Использование pg_probackup3 в удалённом режиме».

--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-oid и --db-include-oid использовать вместе нельзя.

Параметры S3

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

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

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

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

  • vk — хранилище VK Cloud. С этим провайдером используются только адрес узла S3 hb.vkcs.cloud, порт 443 и протокол HTTPS. Пользовательские значения узла, порта и протокола игнорируются. Регион по умолчанию — ru-msk.

  • aws — хранилище Amazon S3 от Amazon Web Services (AWS). С этим провайдером используются только адрес узла S3 имя_бакета.s3.регион.amazonaws.com, порт 443 и протокол HTTPS. Пользовательские значения узла, порта и протокола игнорируются. Регион по умолчанию — us-east-1.

  • google —

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

Когда команда pg_probackup3 запускается с ключом --s3, все операции, поддерживающие параллельное выполнение, по умолчанию выполняются параллельно в 10 потоков (за подробностями обратитесь к «Запуск pg_probackup3 в параллельных потоках»). Количество потоков можно изменить с помощью ключа -j/--threads.

--s3-config-file=путь_к_файлу_конфигурации

Задаёт файл конфигурации S3. Параметры, заданные в этом файле, переопределяют переменные окружения. Если этот параметр опускается, pg_probackup3 ищет файл конфигурации S3 сначала в /etc/pg_probackup/s3.config, а затем в ~postgres/.pg_probackup/s3.config. Ниже приведён пример файла конфигурации S3: 

access-key = ...
secret-key = ...
s3-host = localhost
s3-port = 9000
s3-bucket = s3demo
s3-region=us-east-1
s3-buffer-size = 32
s3-secure = on | https | http | off

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

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

--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, Москва, Россия.

Благодарности

Программа pg_probackup3 основана на pg_arman, которая изначально была написана в NTT, а затем её развивал и поддерживал Микаэль Пакье.

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