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 receive-backup -D каталог_данных --port порт [параметр...]
pg_probackup3 restore -B каталог_копий --instance имя_экземпляра [параметр...]
pg_probackup3 retention -B каталог_копий --instance имя_экземпляра { --delete-wal | --delete-expired | --merge-expired } [параметр...]
pg_probackup3 send-backup -B каталог_копий --instance имя_экземпляра -i ид_резервной_копии --port порт --host сервер [параметр...]
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] [--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=каталог_архива_wal] [параметры_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/RECOVERYWAL) и %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/RECOVERYWAL --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=каталог_архива_wal] [--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 завершается с ошибкой.
Каждый WAL-файл копируется напрямую в целевой каталог. Перед копированием сегмента создаётся временный пустой файл с расширением .guard. Пока он существует, считается, что сегмент отсутствует в архиве. Как только сегмент успешно скопирован, файл .guard удаляется. Если операция завершается аварийно, файл .guard остаётся в архиве, а сегмент считается отсутствующим до тех пор, пока файл не будет удалён.
Postgres Pro запрашивает сегменты WAL по одному. Для ускорения архивирования можно воспользоваться параметром --batch-size, определяющим размер пакета из нескольких копируемых сегментов WAL. Вместе с параметром --batch-size также можно применить указание -j/--threads, чтобы пакеты WAL-сегментов копировались в несколько потоков. Если --batch-size не задан, но задан -j/--threads, то --batch-size по умолчанию принимает значение -j/--threads.
Сегменты WAL, копируемые в архив, по умолчанию (без указания флага --no-sync) гарантированно сбрасываются на диск.
Команду archive-push можно использовать в значении параметра Postgres Pro archive_command при настройке непрерывного архивирования WAL.
За подробностями обратитесь к подразделам Общие параметры, Параметры архивирования и Параметры сжатия.
backup #
pg_probackup3 backup -Bкаталог_копий--instance=имя_экземпляра-bрежим_копирования-sисточник_данных-iид_резервной_копии[--parent-backup-id=ид_родительской_копии] [--from-full] [-x | --exclude-path=префикс_пути] [--wal-archive-dir=каталог_архива_wal] [--with-file-map] [--help] [--progress] [-j | --threads=число_потоков] [--num-write-threadsчисло_потоков] [--num-validate-threadsчисло_потоков] [--num-segments] [--temp-slot] [-P | --perm-slot] [-S | --slot=имя_слота] [--transfer-mode] [--create-slot] [--transfer-mode] [--stream] [--no-validate] [--skip-block-validation] [--no-validate-wal] [--archive-timeout=время_ожидания] [-E | --external-dirs=путь_к_внешнему_каталогу] [--no-sync] [--note=заметка_к_копии] [параметры_подключения] [параметры_сжатия] [параметры_ssh] [параметры_частичного_резервного_копирования] [параметры_закрепления] [параметры_журналирования] [параметры_s3] [параметры_буферизации]
Создаёт копию экземпляра Postgres Pro.
-bрежим--backup-mode=режимЗадаёт режим резервного копирования. Возможные значения:
full,delta,ptrack.-sисточник_копирования--backup-source=источник_копированияУказывает режим доступа к серверу. Возможные значения:
pro,direct,base. Значение по умолчанию —pro.--parent-backup-id=ид_родительской_копииУказывает уникальный идентификатор родительской копии (используется при инкрементальном копировании).
--from-fullСоздаёт инкрементальную резервную копию от последней родительской полной копии.
--wal-archive-dir=каталог_архива_walЗадаёт каталог для архива WAL.
По умолчанию архив WAL хранится в каталоге
. Чтобы указать пользовательский каталог, используйте параметркаталог_копий/wal/имя_экземпляра--wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.--num-segments=количество_сегментовЗадаёт количество сегментов резервной копии при её создании или объединении. Должен быть положительным целым числом.
Примечание
Если указанное значение превышает системное ограничение на количество одновременно открытых файлов, процесс завершится с ошибкой «too many open files» (слишком много открытых файлов).
--num-write-threads=число_потоковЗадаёт число потоков записи. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля копирования файлов. Если--num-write-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--num-validate-threads=число_потоковЗадаёт число потоков для проверки резервных копий. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля проверки резервных копий. Если--num-validate-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.-C--smooth-checkpointЕсли этот параметр включён, резервное копирование запустится в начале следующей запланированной контрольной точки. В противном случае контрольная точка будет выполнена немедленно и резервное копирование начнётся максимально быстро.
--streamСоздаёт потоковую резервную копию (STREAM), включая в неё все необходимые файлы WAL, получаемые от сервера по протоколу репликации.
--temp-slotСоздать временный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Это гарантирует, что все нужные сегменты WAL будут доступны, если в процессе копирования произойдёт переключение сегментов WAL. Этот параметр нельзя использовать с параметром
--perm-slot. По умолчанию имя временного слота —pg_probackup3_wal_streaming_, гдеидентификатор_процессаидентификатор_процесса— PID Postgres Pro. Чтобы его поменять, воспользуйтесь параметром-S/--slotи явно укажите--temp-slot.-P--perm-slotСоздать постоянный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Этот параметр нельзя использовать с параметром
--temp-slot. По умолчанию имя постоянного слота —pg_probackup_3_perm_slot, но его можно поменять, воспользовавшись параметром-S/--slot.-Sимя_слота--slot=имя_слотаЗадаёт, к какому слоту репликации подключаться для передачи WAL. Этот параметр можно указать только вместе с параметром
--stream.-xпрефикс_пути--exclude-path=префикс_путиОпределяет префикс для файлов, которые будут исключены из резервного копирования. Такой префикс должен содержать путь относительно каталога данных экземпляра. Если в префиксе указан каталог, ни один файл в этом каталоге не будет скопирован.
-Eпуть_к_внешнему_каталогу--external-dirs=путь_к_внешнему_каталогуВключить в создаваемую копию указанный каталог, рекурсивно копируя его содержимое в отдельный подкаталог каталога резервной копии. Этот параметр полезен для создания резервных копий скриптов, файлов выгрузки SQL и файлов конфигурации, расположенных вне каталога данных. Чтобы создать резервную копию нескольких внешних каталогов, разделите их пути двоеточием в Linux и точкой с запятой в Windows.
--archive-timeout=время_ожиданияЗадаёт тайм-аут для архивирования сегментов WAL, в секундах. По умолчанию pg_probackup3 ждёт выполнения этих операций 300 секунд.
Примечание
Для режима STREAM этот параметр не применяется. Тайм-аут для потоковой передачи WAL-сегментов фиксирован и всегда на 10% больше значения параметра
checkpoint_timeout, сконфигурированного на сервере.Если в архиве WAL существует временный файл
.guard, WAL-сегмент считается отсутствующим в архиве — командаbackupждёт его появления. Если тайм-аут достигается до того, как файл.guardудалён, резервная копия получает статусCORRUPT.--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=префикс_пути] [--sync-replica=режим_синхронизации] [--temp-slot] [-P | --perm-slot] [-S | --slot=имя_слота] [-j | --threads=число_потоков] [--num-write-threads=число_потоков] [--num-validate-threads=число_потоков] [-T | --tablespace-mapping=старый_каталог=новый_каталог] [-X | --waldir=каталог_wal] [параметры_подключения] [параметры_журналирования] [параметры_сжатия]
Создаёт копию экземпляра Postgres Pro, не используя каталог резервных копий.
За особенностями и ограничениями использования catchup обратитесь к Подразделу 6.2.1.
-bрежим_синхронизации--backup-mode=режим_синхронизацииЗадаёт режим синхронизации. Возможные значения:
full,delta,ptrack. Значение по умолчанию —full.--destination-pgdata=путьЗадаёт путь к каталогу данных на целевом сервере.
-sисточник_данных--backup-source=источник_данныхЗадаёт режим доступа к серверу для синхронизации. Возможные значения:
pro,base. Значение по умолчанию —pro.Примечание
Режим DIRECT в настоящее время не поддерживается.
Если режим PRO недоступен, pg_probackup3 переключается на режим BASE в качестве резервного варианта. За подробностями обратитесь к Подразделу 6.2.1.
--sync-replica=режим_синхронизацииСинхронизировать реплику с ведущим сервером, когда истории линий времени расходятся, в том числе после повышения реплики. Если указан этот параметр, команда
catchupопределяет точку расхождения, откатывает реплику до этой точки и догоняет ведущий сервер. По умолчанию параметр отключён.Возможные значения:
check: выполнить пробный запуск. Проводятся диагностические проверки с выводом подробного отчёта; изменения в реплику не вносятся.apply: выполнить синхронизацию без пробного запуска, с внесением изменений в реплику. Если pg_rewind выполнил откат, страницы копируются начиная с позиции в файлеbackup_label, созданном pg_rewind, после чего этот файл удаляется. Если откат не требуется, синхронизация выполняется так же, как в режимеDELTA.
--num-write-threads=число_потоковЗадаёт число потоков записи. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля копирования файлов. Если--num-write-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--num-validate-threads=число_потоковЗадаёт число потоков для проверки резервных копий. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля проверки резервных копий. Если--num-validate-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.-xпрефикс_пути--exclude-path=префикс_путиОпределяет префикс для файлов, которые не будут копироваться при синхронизации экземпляров Postgres Pro. Такой префикс должен содержать путь относительно каталога данных экземпляра. Если в префиксе указан каталог, ни один файл в этом каталоге не будет копирован.
--temp-slotСоздать временный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Это гарантирует, что все нужные сегменты WAL будут доступны, если в процессе копирования произойдёт переключение сегментов WAL. Этот параметр нельзя использовать с параметром
--perm-slot. По умолчанию имя временного слота —pg_probackup3_wal_streaming_, гдеидентификатор_процессаидентификатор_процесса— PID Postgres Pro. Чтобы его поменять, воспользуйтесь параметром-S/--slotи явно укажите--temp-slot.-P--perm-slotСоздать постоянный слот физической репликации для передачи WAL с копируемого экземпляра Postgres Pro. Этот параметр нельзя использовать с параметром
--temp-slot. По умолчанию имя постоянного слота —pg_probackup_3_perm_slot, но его можно поменять, воспользовавшись параметром-S/--slot.-Sимя_слота--slot=имя_слотаЗадаёт слот репликации для подключения при потоковой передаче WAL.
-Tстарый_каталог=новый_каталог--tablespace-mapping=старый_каталог=новый_каталогПереместить табличное пространство из старого каталога в новый во время восстановления. Значение должно иметь вид
, гдестарый_каталог=новый_каталогстарый_каталогиновый_каталог— абсолютные пути. Если путь содержит знак равенства (=), экранируйте его обратной косой чертой.Для перемещения нескольких табличных пространств либо используйте параметр
-Tнесколько раз:pg_probackup3 restore -B
каталог_копий--instanceимя_экземпляра-Dкаталог_данных-j 4 -iид_резервной_копии-Tкаталог_табл_пространства1=новый_каталог_табл_пространства1:каталог_табл_пространства2=новый_каталог_табл_пространства2Либо задайте разделённый двоеточиями список пар сопоставления в одном параметре:
pg_probackup3 restore -B
каталог_копий--instanceимя_экземпляра-Dкаталог_данных-j 4 -iид_резервной_копии-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 работать на ней. Более детальное описание процесса представлено в Раздел 6.3.
--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=число_потоков] [--num-write-threads=число_потоков] [--num-validate-threads=число_потоков] [--progress] [--no-validate] [--no-sync] [--no-validate-wal] [--keep-backups] [--dry-run] [--help][параметры_журналирования] [параметры_ssh] [параметры_s3] [параметры_буферизации]
Объединяет копии, относящиеся к одной цепочке инкрементальных копий. Если выбрана полная копия, она будет объединена с первой инкрементальной копией после неё. Если выбрана инкрементальная копия, она будет объединена с родительской полной копией, включая все инкрементальные копии между ними. После выполнения команды полная копия содержит все объединённые данные, а инкрементальные копии удаляются как ненужные. Вы также можете объединять цепочки инкрементальных копий, указав первую и последнюю резервные копии или интервал (в часах) от момента создания первой резервной копии.
--num-write-threads=число_потоковЗадаёт число потоков записи. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля копирования файлов. Если--num-write-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--num-validate-threads=число_потоковЗадаёт число потоков для проверки резервных копий. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля проверки резервных копий. Если--num-validate-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--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.
За подробностями обратитесь к подразделам Общие параметры и Объединение резервных копий.
receive-backup #
pg_probackup3 receive-backup -Dкаталог_данных--portпорт[параметры_журналирования]
Восстанавливает экземпляр Postgres Pro из резервной копии, отправленной с удалённого хоста с помощью команды send-backup.
-Dкаталог_данных--pgdata=каталог_данныхЗадаёт абсолютный путь к каталогу данных, в который будет восстановлена резервная копия.
--port=портЗадаёт порт для получения данных от send-backup.
За подробной информацией о параметрах команды обратитесь к разделу Общие параметры.
За подробной информацией об удалённом восстановлении обратитесь к Разделу 4.6.
restore #
pg_probackup3 restore -Bкаталог_копий--instance=имя_экземпляра[--help] [-Dкаталог_данных] [-iид_резервной_копии] [--wal-archive-dir=каталог_архива_wal] [-I | --incremental-mode=инкрементальный_режим] [--progress] [-T | --tablespace-mapping=старый_каталог=новый_каталог] [-X | --waldir=каталог_wal] [--external-mapping=старый_каталог=новый_каталог] [--skip-external-dirs] [--num-write-threads=число_потоков] [-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 производится в локальную файловую систему.Для операций PITR необходимо указывать идентификатор резервной копии, то есть параметр
-i/--backup-idявляется обязательным.
-R--restore-as-replicaСоздать минимальный файл конфигурации
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несколько раз:pg_probackup3 restore -B
каталог_копий--instanceимя_экземпляра-Dкаталог_данных-j 4 -iид_резервной_копии-Tкаталог_табл_пространства1=новый_каталог_табл_пространства1:каталог_табл_пространства2=новый_каталог_табл_пространства2Либо задайте разделённый двоеточиями список пар сопоставления в одном параметре:
pg_probackup3 restore -B
каталог_копий--instanceимя_экземпляра-Dкаталог_данных-j 4 -iид_резервной_копии-Tкаталог_табл_пространства1=новый_каталог_табл_пространства1:каталог_табл_пространства2=новый_каталог_табл_пространства2--external-mapping=старый_каталог=новый_каталогПереместить внешний каталог, включённый в резервную копию, из старого каталога в новый во время восстановления. Значение должно иметь вид
, гдестарый_каталог=новый_каталогстарый_каталогиновый_каталог— абсолютные пути. Если путь содержит знак равенства (=), экранируйте его обратной косой чертой.Для перемещения нескольких внешних каталогов задайте разделённый двоеточиями список пар сопоставления. Например:
--external-mapping=
старый_каталог1=новый_каталог1:старый_каталог2=новый_каталог2--skip-external-dirsПропускать внешние каталоги, включённые в резервную копию указанием
-E/--external-dirs. Содержимое этих каталогов не будет восстановлено.--skip-block-validationОтключает проверку контрольных сумм на уровне блоков для ускорения проверки целостности. При автоматической проверке перед восстановлением будут проверяться только контрольные суммы на уровне файлов.
--num-write-threads=число_потоковЗадаёт число потоков записи. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля копирования файлов. Если--num-write-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--num-validate-threads=число_потоковЗадаёт число потоков для проверки резервных копий. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля проверки резервных копий. Если--num-validate-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--no-validateПропускает проверку резервного копирования. Этот ключ может быть полезен, если вы регулярно проверяете копии и хотите сократить время восстановления данных.
--no-validate-walОтключает проверку WAL-файлов.
Предупреждение
Используйте
--no-validate-walс осторожностью. Операции могут завершаться успешно, даже если данные повреждены, а восстановленная база данных может оказаться логически несогласованной. Ответственность за последствия полностью лежит на пользователе.--restore-command=командаЗадаёт для параметра
restore_commandуказанную команду. Например:--restore-command='cp /mnt/server/archivedir/%f "%p"'.По умолчанию для параметра
restore_commandзадаётся команда archive-get, которая извлекает WAL-файлы из каталога резервных копий:restore_command = 'pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'
--wal-archive-dir=каталог_архива_walЗадаёт каталог для архива WAL.
По умолчанию архив WAL хранится в каталоге
. Чтобы указать пользовательский каталог, используйте параметркаталог_копий/wal/имя_экземпляра--wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.--forceПозволяет игнорировать ошибочное состояние копии. Этот флаг можно использовать, когда требуется восстановить кластер Postgres Pro из повреждённой или некорректной копии. Применяйте его с осторожностью.
Если
PGDATAсодержит непустой каталог с системным идентификатором, отличным от того, что указан в восстанавливаемой копии, при инкрементальном восстановлении с этим флагом содержимое каталога будет заменено. Если табличные пространства переопределяются с помощью-T/--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=каталог_архива_wal] [-j | --threads=число_потоков] [--num-write-threads=число_потоков] [--num-validate-threads=число_потоков] [--delete-expired] [--delete-wal] [--wal-depth=глубина_wal] [параметры_закрепления] [параметры_ssh] [параметры_s3] [параметры_буферизации]
Устанавливает политику хранения резервных копий в экземпляре или каталоге и запускает процесс удаления или объединения резервных копий согласно указанным параметрам.
По умолчанию архив WAL хранится в каталоге . Чтобы указать пользовательский каталог, используйте параметр каталог_копий/wal/имя_экземпляра--wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.
Для операций объединения можно явно указать количество потоков для параллельного выполнения.
--num-write-threads=число_потоковЗадаёт число потоков записи. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля копирования файлов. Если--num-write-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.--num-validate-threads=число_потоковЗадаёт число потоков для проверки резервных копий. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр. Значение по умолчанию —
0.Этот параметр переопределяет
j/--threadsдля проверки резервных копий. Если--num-validate-threadsне указан, вместо него используется значениеj/--threads. Еслиj/--threadsтакже не задан, по умолчанию используется число ядер процессора.
За подробностями о параметрах команды обратитесь к разделам Общие параметры и Параметры сохранения.
send-backup #
pg_probackup3 send-backup -Bкаталог_копий--instance=имя_экземпляра-iид_резервной_копии--portпорт--hostхост[--no-merge] [-I | --incremental-mode=инкрементальный_режим] [параметры_удалённого_архива_wal] [параметры_журналирования]
Передаёт данные резервных копий в удалённую систему через указанный порт с использованием многопоточности.
Эта команда выполняется на локальной машине, содержащей каталог резервных копий.
Если резервная копия была создана в режиме ARCHIVE, а её архив WAL находится на отдельном сервере, укажите параметры доступа к нему — --archive-host, --archive-port и --archive-user (параметры удалённого архива WAL). Значения этих параметров передаются на удалённую сторону и используются для формирования restore_command, чтобы целевой экземпляр мог читать WAL из архива.
--port=портУказывает порт на удалённом хосте.
--host=серверУказывает имя удалённого хоста.
--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] [--wal-tree] [--retention-redundancy=избыточность] [--retention-window=окно] [параметры_сжатия] [параметры_подключения] [--archive-timeout=время_ожидания] [-E | --external-dirs=путь_к_внешнему_каталогу] [параметры_журналирования] [параметры_ssh] [параметры_буферизации]
Добавляет заданные параметры соединения, сжатия, политики хранения, ведения журнала и указания внешних каталогов в конфигурационный файл pg_probackup3.conf либо изменяет ранее заданные значения.
По умолчанию архив WAL хранится в каталоге . Чтобы указать пользовательский каталог, используйте параметр каталог_копий/wal/имя_экземпляра--wal-archive-dir. Тип хранилища (локальная файловая система, SFTP или S3) должен соответствовать конфигурации экземпляра. Указывать необходимо уже существующий каталог.
Параметр --wal-tree организует хранение WAL-файлов в подкаталогах, оптимизируя дисковое пространство. Это предотвращает перегрузку файловой системы, в особенности на NFS (Network File System, сетевая файловая система), которая может не справляться с большим количеством файлов в одном каталоге.
Чтобы включить каталоги, расположенные вне каталога данных, передайте список этих каталогов, разделённых двоеточиями, с помощью параметра -E/--external-dirs. В Windows вместо двоеточий используйте точки с запятой.
Чтобы удалить внешние каталоги, передайте пустую строку ('') без знака равенства:
pg_probackup3 set-config -B /путь/к/каталогу_копий --instance=dev -E ''Использование знака равенства без значения (--external-dirs=) приводит к сбою операции.
Все поддерживаемые параметры описываются в подразделе Параметры.
Редактировать pg_probackup3.conf вручную не рекомендуется.
show #
pg_probackup3 show -Bкаталог_копий[--help] [--instance=имя_экземпляра[-iид_резервной_копии| --archive [--wal-archive-dir=каталог_архива_wal]]] [--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=число_потоков] [--num-validate-threads=число_потоков] [--progress] [--skip-block-validation] [--no-validate-wal] [параметры_буферизации] [параметры_журналирования] [параметры_ssh][параметры_s3]
Проверяет наличие и целостность всех файлов, необходимых для восстановления кластера. Если имя_экземпляра не задаётся, pg_probackup3 проверяет все резервные копии, имеющиеся в каталоге копий.
Если указать параметр --progress, в процессе проверки будет выводиться список файлов и каталогов резервной копии.
--num-validate-threads задаёт число потоков для проверки резервных копий. Если --num-validate-threads не указан, вместо него используется значение j/--threads. Если j/--threads также не задан, по умолчанию используется число ядер процессора. Нулевое значение (по умолчанию) отключает этот параметр.
Примечание
Число потоков не может превышать число сегментов резервной копии.
Параметр --no-validate-wal отключает проверку WAL-файлов.
Предупреждение
Используйте --no-validate-wal с осторожностью. Операции могут завершаться успешно, даже если данные повреждены, а восстановленная база данных может оказаться логически несогласованной. Ответственность за последствия полностью лежит на пользователе.
version #
pg_probackup3 version
Выводит версию pg_probackup3.
При указании --format= вывод будет получен в формате JSON. Это может потребоваться для внутренней интеграции с приложениями на основе JSON, например PPEM. Пример вывода JSON: json
pg_probackup3 version --format=json
{
"pg_probackup3":
{
"version": "3.0.0",
},
"compressions": [zlib, lz4, zstd]
}
Параметры #
В этом подразделе описываются параметры командной строки для команд pg_probackup3. Если какое-либо значение параметра может быть получено из переменной окружения, имя этой переменной указывается в верхнем регистре ниже параметра командной строки. Некоторые значения могут быть получены из файла конфигурации pg_probackup3.conf, находящегося в каталоге копий.
За подробностями обратитесь к Разделу 2.6.
Если некоторый параметр задаётся несколькими способами, значение в командной строке имеет наивысший приоритет, а значение в 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=ид_резервной_копииЗадаёт уникальный идентификатор резервной копии.
-jчисло_потоков--threads=число_потоковPG_PROBACKUP_MAX_THREADSЗадаёт число параллельных потоков, запускаемых командами
backup,restore,catchup,merge,validate,archive-pushиarchive-get. Значение по умолчанию равно числу ядер процессора.Если параметр
-jне указан, но задана переменная окруженияPG_PROBACKUP_MAX_THREADS, количество потоков определяется автоматически исходя из количества доступных ядер процессора, но не может превышать значениеPG_PROBACKUP_MAX_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--wal-depth=глубина_walУказывает количество последних рабочих резервных копий на каждой линии времени, которое должно сохраняться для обеспечения возможности PITR. Значение должно быть неотрицательным целым числом. Нулевое значение отключает этот параметр.
По умолчанию:
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). Примеры показаны в таблице ниже.Таблица 7.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, так что вы можете использовать спецкоды с % для выбора имён файлов, зависящих от времени.Примечание
Начиная с PostgreSQL 17, в shell-командах, таких как
archive_command, применяется более строгая проверка местозаполнителей со знаком процента. В этом контексте вместо одинарного%следует использовать%%. Для получения дополнительной информации обратитесь к соответствующему коммиту PostgreSQL.По умолчанию: 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.
Поддерживаются все переменные окружения 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 для
zlib0–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_commandPostgres Pro выбирает текущим рабочим каталогомPGDATA, поэтому относительные пути видаpg_wal/...работают корректно.Примечание
При использовании в
archive_commandилиrestore_commandPostgres 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.--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=pg_probackup3 будет работать с хранилищем VK Cloud, если правильно заданы адрес узла S3, порт и протокол (адрес узла —miniohb.vkcs.cloudили указанный в соответствующем разделе профиля VK Cloud, порт 443 и протокол HTTPS). Не указывайте--s3=при использовании хранилища Amazon S3.minio--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.3.1 и Разделе 2.3.
--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, Москва, Россия.
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 receive-backup -D data_dir --port port [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 --port port --host 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 -Bbackup_dir-Ddata_dir--instance=instance_name[--skip-if-exists] [--wal-archive-dir=wal_archive_dir] [--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 . Use the backup_dir/wal/instance_name--wal-archive-dir option to specify a custom directory. The storage type (local file system, 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 -Bbackup_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=wal_archive_dir] [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”.
By default, the WAL archive is stored in . Use the backup_dir/wal/instance_name--wal-archive-dir option to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.
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/RECOVERYWAL) 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/RECOVERYWAL --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 -Bbackup_dir--instance=instance_name--wal-file-name=wal_file_name[--wal-file-path=wal_file_path] [--help] [--no-sync] [--overwrite] [--wal-archive-dir=wal_archive_dir] [--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.
By default, the WAL archive is stored in . Use the backup_dir/wal/instance_name--wal-archive-dir option to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.
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 WAL file is copied directly to the target directory. A temporary empty file with the .guard extension is created before copying a segment. While it exists, the segment is considered missing in the archive. Once the segment is successfully copied, the .guard file is deleted. If the operation crashes, the .guard file remains in the archive, and the segment is considered missing until the file is deleted.
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 -Bbackup_dir--instance=instance_name-bbackup_mode-sbackup_source-ibackup_id[--parent-backup-id=parent_backup_id] [--from-full] [-x | --exclude-path=path_prefix] [--wal-archive-dir=wal_archive_dir] [--with-file-map] [--help] [--progress] [-j | --threads=num_threads] [--num-write-threadsnum_threads] [--num-validate-threadsnum_threads] [--num-segments] [--temp-slot] [-P | --perm-slot] [-S | --slot=slot_name] [--transfer-mode] [--stream] [--no-validate] [--skip-block-validation] [--no-validate-wal] [--archive-timeout=wait_time] [-E | --external-dirs=external_dir_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.
-bmode--backup-mode=modeSpecifies the backup mode to use. Possible values:
full,delta,ptrack.-sbackup_source--backup-source=backup_sourceSpecifies the server access mode. Possible values:
pro,direct,base. The default ispro.--parent-backup-id=parent_backup_idSpecifies the unique identifier of the parent backup (used for incremental backups).
--from-fullCreates an incremental backup from the latest parent FULL backup.
--wal-archive-dir=wal_archive_dirSpecifies the directory for the WAL archive.
By default, the WAL archive is stored in
. Use thebackup_dir/wal/instance_name--wal-archive-diroption to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.--num-segments=num_segmentsSpecifies 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_threadsSpecifies the number of write threads. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides
j/--threadsfor file copying. If--num-write-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--num-validate-threads=num_threadsSpecifies the number of threads for backup validation. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides the
j/--threadsoption for the backup validation. If--num-validate-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.-C--smooth-checkpointWhen enabled, the backup starts at the next scheduled checkpoint. Otherwise, a checkpoint runs immediately, and the backup begins as soon as possible.
--streamMakes a STREAM backup, which includes all the necessary WAL files by streaming them from the database server via replication protocol.
--temp-slotCreate 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-slotflag. The default slot name ispg_probackup3_wal_streaming_, wherebackend_pidbackend_pidis a PID of the Postgres Pro process. To change it, use the-S/--slotoption and explicitly specify--temp-slot.-P--perm-slotCreate a permanent physical replication slot for streaming WAL from the Postgres Pro instance being copied. This flag cannot be used together with the
--temp-slotflag. The default slot name ispg_probackup_3_perm_slot, which can be changed using the-S/--slotoption.-Sslot_name--slot=slot_nameSpecifies the replication slot to connect to for WAL streaming. This option can only be used together with the
--streamflag.-xpath_prefix--exclude-path=path_prefixSpecifies 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.
-Eexternal_dir_path--external-dirs=external_dir_pathInclude the specified directory in 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. To back up several external directories, separate their paths with a colon on Linux and a semicolon on Windows.
--archive-timeout=wait_timeSets 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_timeoutparameter configured on the server.If a temporary
.guardfile exists in the WAL archive, the WAL segment is considered missing in the archive — thebackupcommand waits for the segment to appear. If the timeout is reached before.guardis deleted, the backup receives theCORRUPTstatus.--skip-block-validationDisables block-level checksum verification to speed up the backup process.
--no-validateSkips 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-walDisables validation of WAL files.
Note
The
--no-validateoption disables validation entirely, including WAL validation, while the--no-validate-waloption disables only WAL validation and does not affect checksum verification.Warning
Use
--no-validate-walwith caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.--no-syncDo 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_noteSets the text note for backup copy. If
backup_notecontains 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-mapEnables file map generation. Required for the fuse command.
--transfer-mode=transfer_modeSpecifies the method of sending data from a server to an application.
Note
This option is only available in PRO server access 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.
packedis 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] [--sync-replica=sync_mode] [--temp-slot] [-P | --perm-slot] [-S | --slot=slot_name] [-j | --threads=num_threads] [--num-write-threads=num_threads] [--num-validate-threads=num_threads] [-T | --tablespace-mapping=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 6.2.1.
-bcatchup_mode--backup-mode=catchup_modeSpecifies the catchup mode to use. Possible values:
full,delta,ptrack. The default isfull.--destination-pgdata=pathSpecifies the path to the data directory on the target server.
-scatchup_source--backup-source=catchup_sourceSpecifies the server access mode for synchronization. Possible values:
pro,base. The default ispro.Note
DIRECT mode is currently unsupported.
If PRO is unavailable, pg_probackup3 falls back to BASE mode. For more details, refer to Section 6.2.1.
--sync-replica=sync_modeSynchronize the replica with the primary when timeline histories diverge, including when the replica has been promoted. When this option is specified, the
catchupcommand determines the divergence point, rolls back the replica to that point, and catches up with the primary. The option is disabled by default.Possible values:
check: Perform a dry run. Diagnostic checks are executed with detailed report output; no changes are applied to the replica.apply: Perform synchronization without a dry run, applying changes to the replica. If pg_rewind performed a rollback, pages are copied starting from the position in thebackup_labelfile created by pg_rewind, after which this file is deleted. If no rollback is required, synchronization is performed in the same way as inDELTAmode.
--num-write-threads=num_threadsSpecifies the number of write threads. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides
j/--threadsfor file copying. If--num-write-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--num-validate-threads=num_threadsSpecifies the number of threads for backup validation. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides the
j/--threadsoption for the backup validation. If--num-validate-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.-xpath_prefix--exclude-path=path_prefixSpecifies 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-slotCreate 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-slotflag. The default slot name ispg_probackup3_wal_streaming_, wherebackend_pidbackend_pidis a PID of the Postgres Pro process. To change it, use the-S/--slotoption and explicitly specify--temp-slot.-P--perm-slotCreate a permanent physical replication slot for streaming WAL from the Postgres Pro instance being copied. This flag cannot be used together with the
--temp-slotflag. The default slot name ispg_probackup_3_perm_slot, which can be changed using the-S/--slotoption.-Sslot_name--slot=slot_nameSpecifies the replication slot to connect to for WAL streaming.
-Told_dir=new_dir--tablespace-mapping=old_dir=new_dirRelocate the tablespace from its old directory to the new one during recovery. The value must have the form
, where bothold_dir=new_dirold_dirandnew_dirare absolute paths. If a path contains an equal sign (=), escape it with a backslash.To relocate several tablespaces, either use the
-Toption repeatedly:pg_probackup3 restore -B
backup_dir--instance=instance_name-Ddata_dir-j 4 -ibackup_id-Ttablespace1_dir=tablespace1_new_dir-Ttablespace2_dir=tablespace2_new_dirOr specify a colon-separated list of mapping pairs within the same option:
pg_probackup3 restore -B
backup_dir--instance=instance_name-Ddata_dir-j 4 -ibackup_id-Ttablespace1_dir=tablespace1_new_dir:tablespace2_dir=tablespace2_new_dir-Xwal_dir--waldir=wal_dirSets the directory to write WAL files to. By default WAL files will be placed in the
pg_walsubdirectory of the target directory, but this option can be used to place them elsewhere.wal_dirmust be an absolute path, which must not already exist, but if it does, it must be empty to performcatchupinFULLmode.
For more details on using catchup, refer to the Cloning and Synchronizing a Postgres Pro Instance section.
del-instance #
pg_probackup3 del-instance -Bbackup_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 -Bbackup_dir--instance=instance_name-ibackup_id[--help] [--progress] [--status=backup_status] [--dry-run] [logging_options] [ssh_options] [s3_options] [buffer_options]
Deletes backups with specified backup_id.
--dry-runInitiates a trial run of the
deletecommand, 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.--statusAllows deleting all backups with a specific status.
For details, see the section Deleting Backups.
file-map #
pg_probackup3 file-map -Bbackup_dir--instance=instance_name-ibackup_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 -Bbackup_dir--mnt-path=mnt_path--instance=instance_name-ibackup_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 6.3 for more details on the process.
--cache-swap-sizeSpecifies 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_dirSpecifies the path to the FUSE cache directory. If omitted, the system temporary directory is used.
--detachSets the FUSE file system to be run in the background (by default, it runs in the foreground). This is useful for automation.
--unmountUnmounts the FUSE file system that was previously mounted with the
fusecommand. This option only requires the mount path (the--mnt-pathoption), 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 -Bbackup_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 -Bbackup_dir--instance=instance_name-ibackup_id--merge-from-id=merge_from--merge-interval=merge_interval[-t | --target-backup-id=backup_id] [-j | --threads=num_threads] [--num-write-threads=num_threads] [--num-validate-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.
--num-write-threads=num_threadsSpecifies the number of write threads. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides
j/--threadsfor file copying. If--num-write-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--num-validate-threads=num_threadsSpecifies the number of threads for backup validation. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides the
j/--threadsoption for the backup validation. If--num-validate-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--no-validateSkips automatic validation before and after merge.
--no-validate-walDisables validation of WAL files.
Warning
Use
--no-validate-walwith caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.--no-syncDo 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-idSpecifies an ID of the merged backups.
--keep-backupsPreserves original backups after merging.
--merge-from-idSpecifies an ID of the first incremental backup from the backup chain for merge.
--merge-intervalSpecifies a time period (in hours) before merging a chain of incremental backups.
--with-file-mapEnables file map generation. File maps are required for FUSE operations.
For more details of the command settings, see sections Common Options and Merging Backups.
receive-backup #
pg_probackup3 receive-backup -Ddata_dir--portport[logging_options]
Restores the Postgres Pro instance from a backup sent from a remote host using the send-backup command.
-Ddata_dir--pgdata=data_dirSpecifies the absolute path to the data directory to restore the backup to.
--port=portSpecifies the port on which to receive data from send-backup.
For more details on the command options, refer to the Common Options section.
For more details about remote restore, refer to Section 4.6.
restore #
pg_probackup3 restore -Bbackup_dir--instance=instance_name[--help] [-Ddata_dir] [-ibackup_id] [--wal-archive-dir=wal_archive_dir] [-I | --incremental-mode=incremental_mode] [--progress] [-T | --tablespace-mapping=old_dir=new_dir] [-X | --waldir=wal_dir] [--external-mapping=old_dir=new_dir] [--skip-external-dirs] [--num-write-threads=num_threads] [-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
PGDATAto a local file system.For PITR operations, a backup ID must be provided, i.e.,
-i/--backup-idis a required option.
-R--restore-as-replicaCreate a minimal
postgresql.auto.confconfiguration file in the target directory to facilitate setting up a standby server. Use this option to perform partial restore of specific databases as a standby, for example, to decouple a single cluster containing multiple databases into separate clusters with minimal downtime. If the replication connection requires a password, specify it manually in the primary_conninfo parameter or use the--primary-conninfooption.--primary-conninfo=primary_conninfoSets the primary_conninfo parameter to the specified value. This option will be ignored unless the
-Rflag is specified.Example:
--primary-conninfo="host=192.168.1.50 port=5432 user=foo password=foopass"--primary-slot-name=slot_nameSets the primary_slot_name parameter to the specified value. This option will be ignored unless the
-Rflag is specified.-Iincremental_mode--incremental-mode=incremental_modeSpecifies 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.
-Told_dir=new_dir--tablespace-mapping=old_dir=new_dirRelocate the tablespace from its old directory to the new one during recovery. The value must have the form
, where bothold_dir=new_dirold_dirandnew_dirare absolute paths. If a path contains an equal sign (=), escape it with a backslash.To relocate several tablespaces, either use the
-Toption repeatedly:pg_probackup3 restore -B
backup_dir--instance=instance_name-Ddata_dir-j 4 -ibackup_id-Ttablespace1_dir=tablespace1_new_dir-Ttablespace2_dir=tablespace2_new_dirOr specify a colon-separated list of mapping pairs within the same option:
pg_probackup3 restore -B
backup_dir--instance=instance_name-Ddata_dir-j 4 -ibackup_id-Ttablespace1_dir=tablespace1_new_dir:tablespace2_dir=tablespace2_new_dir--external-mapping=old_dir=new_dirRelocate the external directory included in the backup from the old path to the new one during recovery. The value must have the form
, where bothold_dir=new_dirold_dirandnew_dirare absolute paths. If a path contains an equal sign (=), escape it with a backslash.To relocate several external directories, specify a colon-separated list of mapping pairs. For example:
--external-mapping=
old_dir1=new_dir1:old_dir2=new_dir2--skip-external-dirsSkip external directories included into the backup with the
-E/--external-dirsoption. The contents of these directories will not be restored.--skip-block-validationDisables block-level checksum verification to speed up validation. During automatic validation before the restore only file-level checksums will be verified.
--num-write-threads=num_threadsSpecifies the number of write threads. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides
j/--threadsfor file copying. If--num-write-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--num-validate-threads=num_threadsSpecifies the number of threads for backup validation. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides the
j/--threadsoption for the backup validation. If--num-validate-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--no-validateSkips backup validation. You can use this flag if you validate backups regularly and would like to save time when running restore operations.
--no-validate-walDisables validation of WAL files.
Warning
Use
--no-validate-walwith caution. Operations may succeed despite data corruption, resulting in a logically inconsistent database. The user assumes full responsibility for any consequences.--restore-command=cmdlineSets the
restore_commandparameter to the specified command. For example:--restore-command='cp /mnt/server/archivedir/%f "%p"'.By default, the
restore_commandparameter is set to the archive-get command, which retrieves WAL files from the backup catalog:restore_command = 'pg_probackup3 archive-get -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'
--wal-archive-dir=wal_archive_dirSpecifies the directory for the WAL archive.
By default, the WAL archive is stored in
. Use thebackup_dir/wal/instance_name--wal-archive-diroption to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.--forceAllows ignoring an invalid status of the backup. You can use this flag if you need to restore the Postgres Pro cluster from a corrupt or invalid backup. Use this flag with caution.
If
PGDATAcontains a non-empty directory with a system identifier different from that of the backup being restored, performing incremental restore with this flag overwrites the directory contents. If tablespaces are remapped using the-T/--tablespace-mappingoption to non-empty directories, the contents of such directories are deleted.--no-syncDo 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.
-Xwal_dir--waldir=wal_dirSets the directory to write WAL files to. By default WAL files will be placed in the
pg_walsubdirectory of the target directory, but this option can be used to place them elsewhere.wal_dirmust be an absolute path, which must not already exist, but if it does, it must be empty.
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 -Bbackup_dir--instance=instance_name[--retention-redundancy] [--retention-window] [--dry-run] [--merge-expired] [--wal-archive-dir=wal_archive_dir] [-j | --threads=num_threads] [--num-write-threads=num_threads] [--num-validate-threads=num_threads] [--delete-expired] [--delete-wal] [--wal-depth=wal_depth] [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.
By default, the WAL archive is stored in . Use the backup_dir/wal/instance_name--wal-archive-dir option to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.
For merge operations, you can explicitly specify the number of threads for parallel execution.
--num-write-threads=num_threadsSpecifies the number of write threads. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides
j/--threadsfor file copying. If--num-write-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.--num-validate-threads=num_threadsSpecifies the number of threads for backup validation. The value must be a non-negative integer. The zero value disables this option. Default:
0.This option overrides the
j/--threadsoption for the backup validation. If--num-validate-threadsis not specified, thej/--threadsvalue is used instead. Ifj/--threadsis not set either, pg_probackup3 defaults to the number of CPU cores.
For more details on the command options, refer to the Common Options and Retention Options sections.
send-backup #
pg_probackup3 send-backup -Bbackup_dir--instance=instance_name-ibackup_id--portport--hosthost[--no-merge] [-I | --incremental-mode=incremental_mode] [remote_wal_archive_options] [logging_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.
--port=portSpecifies the port on the remote host.
--host=hostSpecifies the hostname of the remote host.
--no-mergeDisables 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.
-Iincremental_mode--incremental-mode=incremental_modeSpecifies 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
-Ioption 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 -Bbackup_dir--instance=instance_name-ibackup_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_noteSets the text note for backup copy. If
backup_notecontains 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 -Bbackup_dir--instance=instance_name[--help] [--pgdata=pgdata_path] [--wal-archive-dir=wal_archive_dir] [--wal-tree] [--retention-redundancy=redundancy] [--retention-window=window] [compression_options] [connection_options] [--archive-timeout=wait_time] [-E | --external-dirs=external_dir_path] [logging_options] [ssh_options] [buffer_options]
Adds the specified connection, compression, retention, logging, and external directory settings to the pg_probackup3.conf configuration file, or modifies the previously defined values.
By default, the WAL archive is stored in . Use the backup_dir/wal/instance_name--wal-archive-dir option to specify a custom directory. The storage type (local file system, SFTP, or S3) must match the instance configuration. The directory must already exist.
The --wal-tree option enables storing WAL files in subdirectories, optimizing disk space. This prevents file system overload, especially on NFS (Network File System), which can struggle with too many files in a single directory.
To include directories located outside the data directory, pass a colon-separated list of these directories using the -E/--external-dirs option. On Windows, use semicolons instead of colons.
To remove external directories, pass an empty string ('') without an equal sign:
pg_probackup3 set-config -B /path/to/backup_dir --instance=dev -E ''
Using an equal sign without a value (--external-dirs=) causes the operation to fail.
For all available settings, see the Options section.
It is not recommended to edit pg_probackup3.conf manually.
show #
pg_probackup3 show -Bbackup_dir[--help] [--instance=instance_name[-ibackup_id| --archive [--wal-archive-dir=wal_archive_dir]]] [--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 by default. Use the backup_dir/wal/instance_name--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 -Bbackup_dir--instanceinstance_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 directory and those that were provided on a command line. The configuration settings are shown as plain text. backup_dir/backups/instance_name
To edit pg_probackup3.conf, use the set-config command.
validate #
pg_probackup3 validate -Bbackup_dir[--help] [--instance=instance_name] [-ibackup_id] [-j | --threads=num_threads] [--num-validate-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.
--num-validate-threads specifies the number of threads for backup validation. If --num-validate-threads is not specified, the j/--threads value is used instead. If j/--threads is not set either, pg_probackup3 defaults to the number of CPU cores. The zero value (default) disables this option.
Note
The number of threads cannot exceed the number of backup segments.
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= 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: json
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.6.
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-runInitiates 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.-Bdir_path--backup-path=dir_pathBACKUP_PATHSpecifies 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_PATHenvironment variable. In this case, you do not need to use this option each time on the command line.-Ddata_dir--pgdata=data_dirPGDATASpecifies 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
PGDATAenvironment variable, or from thepg_probackup3.confconfiguration file.-ibackup_id--backup-id=backup_idSpecifies the unique identifier of the backup.
-jnum_threads--threads=num_threadsPG_PROBACKUP_MAX_THREADSSets the number of parallel threads for
backup,restore,catchup,merge,validate,archive-push, andarchive-getprocesses. Defaults to the number of CPU cores.If the
-joption is not specified, but thePG_PROBACKUP_MAX_THREADSenvironment variable is set, the thread count is automatically determined based on available CPU cores but is capped by thePG_PROBACKUP_MAX_THREADSvalue.Note
The number of threads cannot exceed the number of backup segments.
--progressShows the progress of operations.
--helpShows detailed information about the options that can be used with this command.
-vversion--version=versionShows pg_probackup3 version.
--config-file=file_nameSpecifies 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-fileoption.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-fileoption is not specified, pg_probackup3 will first look for S3 and SSH configuration files at/etc/pg_probackup/s3.configor/etc/pg_probackup/ssh.configand then at~postgres/.pg_probackup/s3.configor~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|latestDefines when to stop the recovery:
The
immediatevalue stops the recovery after reaching the consistent state of the specified backup. This is the default behavior for STREAM backups.The
latestvalue continues the recovery until all WAL segments available in the archive are applied. Setting this value of--recovery-targetalso sets--recovery-target-timelinetolatest.
--recovery-target-timeline=timelineSpecifies 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=lsnSpecifies the LSN of the write-ahead log location up to which recovery will proceed.
--recovery-target-name=recovery_target_nameSpecifies a named savepoint up to which to restore the cluster.
--recovery-target-time=time|current|latestSpecifies 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=xidSpecifies the transaction ID up to which recovery will proceed.
--recovery-target-inclusive=booleanSpecifies 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-lsnor--recovery-target-xidoptions. The default depends on the recovery_target_inclusive parameter.--recovery-target-action=pause|promote|shutdownSpecifies 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=redundancySpecifies the number of full backup copies to keep in the data directory. Must be a non-negative integer. The zero value disables this option.
Default:
0--retention-window=windowSpecifies the number of days of recoverability. Must be a non-negative integer. The zero value disables this option.
Default:
0--wal-depth=wal_depthSpecifies the number of latest valid backups on every timeline for which PITR must be available. The value must be a non-negative integer. The zero value disables this option.
Default:
0--delete-walDeletes WAL files that are no longer required to restore the cluster from any of the existing backups.
--delete-expiredDeletes backups that do not conform to the retention policy defined in the
pg_probackup3.confconfiguration file.--merge-expiredMerges 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=ttlSpecifies 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=timeSpecifies 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-colorDisable coloring for console log messages of
warninganderrorlevels.--log-level-console=log_levelControls which message levels are sent to the console log. Valid values are
trace,debug,info,warning,errorandoff. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. Theofflevel disables console logging.Default:
infoNote
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_levelControls which message levels are sent to a log file. Valid values are
trace,debug,info,warning,error, andoff. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. Theofflevel disables file logging.Default:
off--log-backup=log_levelControls which message levels are sent to a backup log file created in the backup directory when running the
backupcommand. Valid values aretrace,debug,info,warning,error, andoff. Each level includes all the levels that follow it. The later the level, the fewer messages are sent. Theofflevel disables file logging.Default:
info--log-filename=log_filenameDefines the filenames of the created log files. The filenames are treated as a
strftimepattern, 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.logFor example, if you specify the
pg_probackup-%%u.logpattern, pg_probackup3 generates a separate log file for each day of the week, with%%ureplaced by the corresponding decimal number:pg_probackup-1.logfor Monday,pg_probackup-2.logfor Tuesday, and so on.You can also use the file counter (
%%N) andstrftimeformat (pg_probackup-%%Y-%%m-%%d_%%H%%M%%S.log). The examples are shown in the table below.Table 7.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-fileoption.--error-log-filename=error_log_filenameDefines the filenames of log files for error messages only. The filenames are treated as a
strftimepattern, 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: none
For example, if you specify the
error-pg_probackup-%%u.logpattern, pg_probackup3 generates a separate log file for each day of the week, with%%ureplaced by the corresponding decimal number:error-pg_probackup-1.logfor Monday,error-pg_probackup-2.logfor Tuesday, and so on.This option is useful for troubleshooting and monitoring.
--log-directory=log_dirDefines 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_dirwhen needed.Default:
$BACKUP_PATH/log/--log-format-console=log_formatDefines the format of the console log. Only set from the command line. Note that you cannot specify this option in the
pg_probackup3.confconfiguration 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_formatDefines 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_sizeDefines the maximum size of an individual log file. If this value is reached, the log file is rotated once any pg_probackup3 command, except
helporversion, 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.
-ddbname--pgdatabase=dbnamePGDATABASESpecifies 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,
PGDATABASEenvironment variable, or thepg_probackup3.confconfiguration file, pg_probackup3 tries to take this value from thePGUSERenvironment variable, or from the current user name ifPGUSERvariable is not set.-hhost--pghost=hostPGHOSTSpecifies 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-pport--pgport=portPGPORTSpecifies the TCP port or the local Unix domain socket file extension on which the server is listening for connections.
Default:
5432-Uusername--pguser=usernamePGUSERUser name to connect as.
-w--no-passwordDisables a password prompt. If the server requires password authentication and a password is not available by other means such as a .pgpass file or
PGPASSWORDenvironment 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--passwordForces a password prompt. (Deprecated)
Compression Options #
You can use these options together with backup and archive-push commands.
--compress-algorithm=compression_algorithmDefines the algorithm to use for compressing data files. Possible values are
zlib,lz4,zstd, andnone. If set to any value butnone, this option enables compression that uses the corresponding algorithm. Both data files and WAL files are compressed. By default, compression is disabled.Default:
noneWarning
Option value
lz4for--compress-algorithmisn't currently supported inarchive-pushandarchive-getcommands.--compress-level=compression_levelDefines the compression level.
Note
This option must be used together with the
--compress-algorithmoption.Possible values depend on the compression algorithm specified:
0–9 for
zlib0–22 for
zstd
The value of
0sets the default compression level, which is1, for all compression algorithms.Note
The
lz4algorithm 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_pathProvides the path to the WAL file used by the
archive-pushorarchive-getcommand.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_commandorrestore_command, Postgres Pro sets the current working directory toPGDATA, so relative paths likepg_wal/...work correctly.Note
When used in
archive_commandorrestore_command, Postgres Pro substitutes the%pvariable for the full path and%ffor 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_nameProvides the name of the WAL file in
archive_commandandrestore_command. Use the%fvariable as the value for this option for correct processing. If the value of--wal-file-pathis a path outside of the data directory, explicitly specify the filename.--overwriteOverwrites 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-pushreports that a WAL segment already exists, and aborts the operation. If the file to replace has not changed,archive-pushskips this file regardless of the--overwriteflag.--batch-size=batch_sizeUsed to speed up archiving in case of
archive-pushor to speed up recovery in case ofarchive-get. Sets the maximum number of WAL files that can be copied into the archive by a singlearchive-pushprocess or from the archive by a singlearchive-getprocess. If not specified,--batch-sizedefaults to the-j/--threadsvalue.--no-syncDo 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=pathDirectory used to store prefetched WAL segments if
--batch-sizeis used. Directory must be located on the same file system and on the same mountpoint thePGDATA/pg_walis located. By default files are stored inPGDATA/pg_wal/pbk_prefetchdirectory. This option can be used only with archive-get command.
Buffer Options #
You can use these options with all commands.
--buffer-size=sizeSpecifies 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=sizeSpecifies 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=sizeSpecifies 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_providerSpecifies 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 regionus-east-1are used by default.off— explicitly disables S3 mode. This is the default value for--s3option.
With
--s3=, pg_probackup3 will work fine for a VK Cloud storage if the S3 host address, port and protocol are properly specified (host address isminiohb.vkcs.cloudor the one specified in the appropriate section of the VK Cloud profile, port 443, and HTTPS protocol). Do not specify--s3=for the Amazon S3 storage.minio--s3-host=hostnameSpecifies 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-portis assumed. Do not add a colon if the port number is not specified.--s3-port=port_numberSpecifies the port of the S3 server.
--s3-region=regionSpecifies the region of the S3 server. The default is
us-east-1.--s3-bucket=bucketSpecifies the name of the bucket on the S3 server.
--access-key=access_keySpecifies the access key from S3 storage.
--secret-key=passwordSpecifies the secret access key from S3 storage.
--s3-secure=protocolSpecifies the protocol to be used. Possible values:
ONorHTTPS— HTTPS is used.HTTP— HTTP is used. This is the default value.
--s3-retries=retry_countSets the maximum number of attempts to execute an S3 request in case of failures. The default is
3.--s3-timeout=timeoutSets 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|OFFAllows to skip the certificate host and peer verification. The default is
OFF.--s3-ca-certificate=ca_certificateSpecifies the path to the file with a trust Certificate Authority (CA) bundle.
--s3-ca-path=ca_pathSpecifies the directory with trust CA certificates.
--s3-client-cert=client_certSets the SSL client certificate.
--s3-client-key=client_keySets the private key file for the TLS and SSL client certificates.
--s3-versioning=enabled|suspended|offSets the S3 bucket support for object versioning. The default is
off.--s3-http-compression=true|falseSets 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-sizevalue must not be less than 5 MB. Smaller values will trigger a warning and will be automatically switched to5MB.
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.3.1 and Section 2.3.
--remote-host=destinationSpecifies the remote host IP address or hostname to connect to.
--remote-port=portSpecifies the remote host port to connect to.
Default:
22--remote-user=usernameSpecifies remote host user for SSH connection. If you omit this option, the current user initiating the SSH connection is used.
--remote-path=pathSpecifies pg_probackup3 installation directory on the remote system.
--ssh-password=passwordSpecifies 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=destinationProvides the argument for the
--remote-hostoption in thearchive-getcommand.--archive-port=portProvides the argument for the
--remote-portoption in thearchive-getcommand.Default:
22--archive-user=usernameProvides the argument for the
--remote-useroption in thearchive-getcommand. 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=dboidSpecifies the OID of the database to exclude from restore. All other databases in the cluster will be restored as usual, including
template0andtemplate1. This option can be specified multiple times for multiple databases.--db-include-oid=dboidSpecifies the OID of the database to restore from a backup. All other databases in the cluster will not be restored, with the exception of
template0andtemplate1. This option can be specified multiple times for multiple databases.
These options can be used with the restore command:
--db-exclude-name=dbnameSpecifies the name of the database to exclude from restore. All other databases in the cluster will be restored as usual, including
template0andtemplate1. This option can be specified multiple times for multiple databases.--db-include-name=dbnameSpecifies the name of the database to restore from a backup. All other databases in the cluster will not be restored, with the exception of
template0andtemplate1. 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_HIDDENInstructs 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.controlfile. This option can only be set with environment variables.PGPROBACKUP_TESTS_SKIP_EMPTY_COMMITInstructs pg_probackup3 to skip empty commits after pg_backup_stop.
Authors #
Postgres Professional, Moscow, Russia.