pg_probackup

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

Синтаксис

pg_probackup version

pg_probackup help [команда]

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

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

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

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

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

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

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

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

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

pg_probackup checkdb -B каталог_копий --instance имя_экземпляра -D каталог_данных [параметр...]

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

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

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

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

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

pg_probackup catchup -b режим_синхронизации --source-pgdata=путь_к_копируемому_каталогу_данных --destination-pgdata=путь_к_целевому_каталогу_данных [параметр...]

pg_probackup maintain -B каталог_копий --instance имя_экземпляра [--backup-id ид_резервной_копии] --status-sync [параметр...]

Описание #

pg_probackup — это утилита для управления резервным копированием и восстановлением кластеров баз данных Postgres Pro. Она предназначена для регулярного создания резервных копий экземпляра Postgres Pro, позволяющих восстанавливать сервер в случае необходимости. pg_probackup поддерживает PostgreSQL версии 11 и новее.

Обзор #

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

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

  • Инкрементальное восстановление: ускорение восстановления из копии благодаря повторному использованию неизменённых страниц, имеющихся в PGDATA.

  • Проверка: автоматический контроль целостности данных и проверка резервных копий без восстановления данных кластера.

  • Контроль целостности: выполняемая по запросу проверка экземпляра Postgres Pro с помощью команды checkdb.

  • Политика хранения: управление архивами WAL и резервными копиями в соответствии с установленными правилами их хранения. Вы можете ограничить хранение резервных копий по времени или их количеству, а также переопределить время жизни (TTL) для избранных копий. Потерявшие актуальность резервные копии могут объединяться или удаляться.

  • Параллельное выполнение: выполнение внутренних процессов команд backup, restore, merge, delete, validate и checkdb в несколько параллельных потоков.

  • Сжатие: хранение копируемых данных в сжатом состоянии для экономии дискового пространства.

  • Исключение дублирования: экономия дискового пространства за счёт фильтрации при инкрементальном копировании файлов, не содержащих непосредственно данные (например, файлов _vm или _fsm), если эти файлы не изменялись с момента создания предыдущей копии в цепочке инкрементальных копий.

  • Удалённый режим работы: выполнение резервного копирования экземпляра Postgres Pro, находящегося в удалённой системе, и удалённое восстановление.

  • Получение резервной копии с ведомого: исключение дополнительной нагрузки на ведущий сервер.

  • Архивирование внешних каталогов: резервное копирование файлов и каталогов, расположенных вне каталога данных Postgres Pro (PGDATA), например скриптов, файлов конфигурации, журналов или SQL-дампов.

  • Каталогизация резервных копий: получение списка резервных копий и соответствующей метаинформации в виде простого текста или JSON.

  • Каталогизация архивов WAL: получение списка всех линий времени в WAL и соответствующей метаинформации в виде простого текста или JSON.

  • Частичное восстановление: восстановление только избранных баз данных.

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

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

Используя pg_probackup, вы можете выполнять полное или инкрементальное резервное копирование:

  • Полные резервные копии содержат все файлы данных, необходимые для восстановления кластера баз данных с нуля.

  • Инкрементальные копии создаются на уровне страниц и включают только те данные, которые изменились со времени последнего копирования. Это позволяет сэкономить место на диске и создавать копии быстрее, чем при полном копировании. Восстановление инкрементальных копий также осуществляется быстрее, чем воспроизведение файлов WAL. pg_probackup поддерживает следующие режимы инкрементального копирования:

    • Разностное копирование. В режиме DELTA pg_probackup считывает все файлы данных в каталоге данных и копирует только те страницы, которые изменились со времени предыдущего копирования. Для использования данного режима не требуется производить непрерывное архивирование. В этом режиме объём ввода-вывода может равняться объёму при полном резервном копировании.

    • Страничное копирование. В режиме PAGE pg_probackup сканирует все файлы WAL в архиве с момента создания предыдущей полной или инкрементальной копии. Новая резервная копия будет содержать только страницы, фигурирующие в записях WAL. При этом необходимо, чтобы в архиве WAL сохранялись все файлы WAL, записанные после предыдущей копии. Если размер этих файлов сравним с общим размером файлов базы данных, ускорение будет менее значительным, но размер копии будет всё же меньше.

    • Копирование изменений. В режиме PTRACK Postgres Pro отслеживает изменения страниц на лету. Чтобы он работал, не требуется производить непрерывное архивирование WAL. При каждом изменении страницы отношения она помечается в специальной карте PTRACK. Это отслеживание привносит небольшие издержки в работу сервера, но значительно ускоряет инкрементальное резервное копирование.

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

После повышения ведомого сервера до ведущего и переключения линий времени создайте первую резервную копию в режиме FULL или DELTA — другие режимы могут повредить данные.

pg_probackup может производить копирование только работающего экземпляра, а для обеспечения целостности таких копий требуется копировать WAL. Поэтому вне зависимости от выбранного режима копирования (FULL, PAGE или DELTA), чтобы pg_probackup мог получить полноценную копию, нужно выбрать один из следующих режимов доставки WAL:

  • ARCHIVE. В таком режиме целостность копий обеспечивается посредством непрерывного архивирования. Это режим доставки WAL по умолчанию.

  • STREAM. Такие резервные копии включают все файлы, необходимые для восстановления целостного состояния кластера на момент создания копии. Вне зависимости от того, осуществляется ли непрерывное архивирование, необходимые для восстановления сегменты WAL считываются по протоколу потоковой репликации во время резервного копирования и включаются в состав резервной копии. Поэтому такие резервные копии называются автономными или самодостаточными.

Ограничения #

В настоящее время pg_probackup имеет следующие ограничения:

  • Режим удалённого сервера на платформе Windows не поддерживается.

  • В Unix-системах копию базы Postgres Pro можно сделать только от имени того пользователя, который запускает сервер Postgres Pro. Например, если сервер Postgres Pro запускает пользователь postgres, команду backup также должен выполнять пользователь postgres. Для удовлетворения этого требования в случае использования удалённого режима и SSH в параметре --remote-user необходимо передать postgres.

  • На сервере Postgres Pro, где была сделана копия, и на сервере, где она будет восстанавливаться, должны быть одинаковые значения параметров block_size и wal_block_size и одинаковая основная версия. В зависимости от конфигурации кластера, Postgres Pro может накладывать дополнительные ограничения, например, по архитектуре процессора и версии libc/icu.

Быстрый запуск #

Чтобы быстро начать работу с pg_probackup, выполните следующие действия. Это позволит настроить резервное копирование удалённо в режимах FULL и DELTA и увидеть некоторые базовые операции pg_probackup. Далее используются следующие обозначения:

  • backup — роль в Postgres Pro, используемая для подключения к кластеру Postgres Pro.

  • backupdb — база данных, через которую выполняется подключение к кластеру Postgres Pro.

  • backup_host — система, где находится каталог резервных копий.

  • backup_user — пользователь в системе backup_host, от имени которого выполняются все операции pg_probackup.

  • /mnt/backups — путь к каталогу резервных копий в системе backup_host.

  • postgres_host — система, в которой работает Postgres Pro.

  • postgres — пользователь в системе postgres_host, от имени которого запускаются процессы кластера Postgres Pro.

  • /var/lib/pgpro/std-16/data — путь к каталогу данных Postgres Pro в системе postgres_host.

Выполните следующие шаги: #

  1. Установите pg_probackup в обеих системах: backup_host (сервер резервного копирования) и postgres_host (сервер баз данных).

  2. Настройте подключение через SSH с backup_host к postgres_host:

  3. Настройте кластер баз данных для резервного копирования в режиме STREAM.

  4. Проинициализируйте каталог резервных копий:

    backup_user@backup_host:~$ pg_probackup init -B /mnt/backups
    INFO: Backup catalog '/mnt/backups' successfully initialized
  5. Добавьте экземпляр с именем mydb в каталог резервных копий:

    backup_user@backup_host:~$ pg_probackup add-instance \
        -B /mnt/backups \
        -D /var/lib/pgpro/std-16/data \
        --instance=node \
        --remote-host=postgres_host \
        --remote-user=postgres
    INFO: Instance 'node' successfully initialized
  6. Сделайте полную резервную копию:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b FULL \
        --instance=node \
        --stream \
        --compress-algorithm=zstd \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6J, backup mode: FULL, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/8000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 2s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/9000000 currentpos 0/9000000
    INFO: backup->stop_lsn 0/8004E40
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 1s
    INFO: Validating backup SBOL6J
    INFO: Backup SBOL6J data files are valid
    INFO: Backup SBOL6J resident size: 53MB
    INFO: Backup SBOL6J completed
  7. Выведите список резервных копий экземпляра:

    backup_user@backup_host:~$ pg_probackup show \
            -B /mnt/backups \
            --instance=node
    =============================================================================================================================================
     Instance  Version  ID      Recovery Time                  Mode  WAL Mode  TLI  Time  Data   WAL  Zalg  Zratio  Start LSN  Stop LSN   Status 
    =============================================================================================================================================
     node      17       SBOL6J  2024-04-09 18:18:21.970314+03  FULL  STREAM    1/0    4s  37MB  16MB  zstd    2.57  0/8000028  0/8004E40  OK     
  8. Сделайте инкрементальную резервную копию в режиме DELTA:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b DELTA \
        --instance=node \
        --stream \
        --compress-algorithm=zstd \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6N, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: Parent backup: SBOL6J
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/9000028, TLI: 1
    INFO: Parent Start LSN: 0/8000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 1s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/A000000 currentpos 0/A000000
    INFO: backup->stop_lsn 0/9000190
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 0
    INFO: Validating backup SBOL6N
    INFO: Backup SBOL6N data files are valid
    INFO: Backup SBOL6N resident size: 17MB
    INFO: Backup SBOL6N completed
  9. Добавьте или измените несколько параметров в файле конфигурации pg_probackup, чтобы их не надо было каждый раз указывать в командной строке:

    backup_user@backup_host:~$ pg_probackup set-config \
        -B /mnt/backups \
        --instance=node \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
  10. Проверьте конфигурацию экземпляра:

    backup_user@backup_host:~$ pg_probackup show-config \
        -B /mnt/backups \
        --instance=node
    # Backup instance information
    pgdata = /var/lib/pgpro/std-16/data
    system-identifier = 7355886958826772732
    xlog-seg-size = 16777216
    # Connection parameters
    pgdatabase = backupdb
    pghost = postgres_host
    pguser = backup
    # Archive parameters
    archive-timeout = 5min
    # Logging parameters
    log-level-console = INFO
    log-level-file = OFF
    log-format-console = PLAIN
    log-format-file = PLAIN
    log-filename = pg_probackup.log
    log-rotation-size = 0TB
    log-rotation-age = 0d
    # Retention parameters
    retention-redundancy = 0
    retention-window = 0
    wal-depth = 0
    # Compression parameters
    compress-algorithm = none
    compress-level = 1
    # Remote access parameters
    remote-proto = ssh
    remote-host = postgres_host
    remote-user = postgres

    Обратите внимание, что параметры, не изменённые командой set-config, сохраняют значения по умолчанию.

  11. Сделайте ещё одну инкрементальную копию в режиме DELTA, опустив параметры, ранее сохранённые в файле конфигурации:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b DELTA \
        --instance=node \
        --stream \
        --compress-algorithm=zstd
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6P, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: Parent backup: SBOL6N
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/A000028, TLI: 1
    INFO: Parent Start LSN: 0/9000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 1s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/B000000 currentpos 0/B000000
    INFO: backup->stop_lsn 0/A000190
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 0
    INFO: Validating backup SBOL6P
    INFO: Backup SBOL6P data files are valid
    INFO: Backup SBOL6P resident size: 17MB
    INFO: Backup SBOL6P completed
  12. Вновь выведите список резервных копий экземпляра:

    backup_user@backup_host:~$ pg_probackup show \
        -B /mnt/backups \
        --instance=node
    ================================================================================================================================================
     Instance  Version  ID      Recovery Time                  Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN  Stop LSN   Status 
    ================================================================================================================================================
     node      17       SBOL6P  2024-04-09 18:18:26.630175+03  DELTA  STREAM    1/1    1s  1147kB  16MB  zstd    1.00  0/A000028  0/A000190  OK     
     node      17       SBOL6N  2024-04-09 18:18:25.015713+03  DELTA  STREAM    1/1    2s  1160kB  16MB  zstd    1.04  0/9000028  0/9000190  OK     
     node      17       SBOL6J  2024-04-09 18:18:21.970314+03  FULL   STREAM    1/0    4s    37MB  16MB  zstd    2.57  0/8000028  0/8004E40  OK     
  13. Восстановите данные из последней доступной копии в произвольный каталог:

    backup_user@backup_host:~$ pg_probackup restore \
        -B /mnt/backups \
        -D /var/lib/pgpro/std-16/staging-data \
        --instance=node
    INFO: Validating parents for backup SBOL6P
    INFO: Validating backup SBOL6J
    INFO: Backup SBOL6J data files are valid
    INFO: Validating backup SBOL6N
    INFO: Backup SBOL6N data files are valid
    INFO: Validating backup SBOL6P
    INFO: Backup SBOL6P data files are valid
    INFO: Backup SBOL6P WAL segments are valid
    INFO: Backup SBOL6P is valid.
    INFO: Restoring the database from the backup starting at 2024-04-09 18:18:25+03 on localhost
    INFO: Start restoring backup files. PGDATA size: 112MB
    INFO: Backup files are restored. Transferred bytes: 112MB, time elapsed: 2s
    INFO: Restore incremental ratio (less is better): 100% (112MB/112MB)
    INFO: Syncing restored files to disk
    INFO: Restored backup files are synced, time elapsed: 1s
    INFO: Restore of backup SBOL6P completed.

Установка и подготовка #

Установив pg_probackup, выполните следующие действия:

  • Инициализируйте каталог резервных копий.

  • Добавьте копируемый экземпляр в каталог копий.

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

  • Настройте SSH для выполнения операций pg_probackup в удалённом режиме, если вы планируете его использовать.

Инициализация каталога резервных копий #

pg_probackup сохраняет все файлы копируемых данных и WAL в соответствущих подкаталогах каталога резервных копий.

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

pg_probackup init -B каталог_копий

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

Пользователь, запускающий pg_probackup, должен иметь полный доступ к каталогу_копий.

pg_probackup создаёт каталог_копий со следующими подкаталогами:

  • wal/ — каталог для файлов WAL.

  • backups/ — каталог для файлов резервных копий.

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

Определение копируемого экземпляра #

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

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

pg_probackup add-instance -B каталог_копий -D каталог_данных --instance=имя_экземпляра [параметры_удалённого_режима]

Здесь:

  • каталог_данных — каталог, содержащий данные кластера, копию которого вы хотите сделать. Для подготовки и использования pg_probackup необходимо иметь право записи в этот каталог.

  • имя_экземпляра — это имя подкаталогов, в которых будут храниться файлы копируемых данных и WAL для этого кластера.

  • параметры_удалённого_режима должны задаваться дополнительно, если каталог_данных располагается удалённо.

pg_probackup создаёт подкаталоги имя_экземпляра в каталогах backups/ и wal/ внутри каталога резервных копий. Каталог backups/имя_экземпляра содержит файл конфигурации pg_probackup.conf с параметрами pg_probackup, относящимися к данному экземпляру копии. Если этой команде передать параметры_удалённого_режима, они будут добавлены в pg_probackup.conf.

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

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

Примечание

Для Postgres Pro версии 11 и новее рекомендуется использовать возможность -g, чтобы выполнить копирование мог любой пользователь ОС, включённый в группу владельца кластера. В этом случае пользователь должен иметь права на чтение каталога кластера.

Настройка кластера баз данных #

Хотя pg_probackup можно использовать от имени суперпользователя, рекомендуется создать отдельную роль с минимальными правами, необходимыми для выбранной стратегии копирования. В этих инструкциях по настройке такой ролью служит роль backup.

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

postgres=# CREATE DATABASE backupdb;
postgres=# \c backupdb

Для выполнения резервного копирования роль backup должна иметь следующие разрешения на сервере Postgres Pro (только в базе данных, к которой производится подключение).

Для версий Postgres Pro 11 — 14:

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;

Для Postgres Pro версии 15 или новее:

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;

В файле pg_hba.conf разрешите подключение к кластеру баз данных пользователю с ролью backup.

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

В зависимости от того, будете ли вы делать самодостаточные или архивные копии, конфигурация кластера Postgres Pro будет разной (об особенностях рассказывается ниже). Чтобы получить копию кластера баз данных с ведомого сервера, запустить pg_probackup в удалённом режиме или создать резервную копию PTRACK, требуется дополнительная настройка.

Подробнее об этом рассказывается в подразделах Настройка потокового резервного копирования, Настройка непрерывного архивирования WAL, Настройка копирования с резервного сервера, Настройка удалённого режима, Настройка частичного восстановления и Настройка копирования PTRACK.

Настройка потокового резервного копирования #

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

  • Если роль backup не существует, создайте её с правом REPLICATION при Настройке кластера базы данных:

    CREATE ROLE backup WITH LOGIN REPLICATION;
  • Если роль backup уже существует, дайте ей право REPLICATION:

    ALTER ROLE backup WITH REPLICATION;
  • В файле pg_hba.conf разрешите выполнение репликации для роли backup.

  • Установите для параметра max_wal_senders достаточно большое значение, предусматривающее минимум одно подключение для процесса резервного копирования.

  • Задайте для параметра wal_level значение выше minimal.

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

После этих подготовительных действий вы можете делать резервные копии в режимах FULL, PAGE, DELTA и PTRACK, используя потоковую доставку WAL.

Примечание

Если вы намерены использовать .pgpass для прохождения аутентификации при выполнении копирования в потоковом режиме, файл .pgpass должен содержать учётные данные для подключения к базе данных replication. Например: pghost:5432:replication:backup_user:my_strong_password

Настройка непрерывного архивирования WAL #

Для выполнения копирования в режиме PAGE, восстановления на момент времени и создания резервных копий с использованием режима доставки WAL ARCHIVE должно осуществляться непрерывное архивирование WAL. Чтобы настроить непрерывное архивирование, выполните следующие действия:

  • Задайте для параметра wal_level значение выше minimal.

  • Если вы настраиваете резервное копирование на ведущем сервере, параметр archive_mode должен иметь значение on или always. Для выполнения резервного копирования на ведомом требуется значение always.

  • Установите параметр archive_command:

    archive_command = '"путь_инсталляции/pg_probackup" archive-push -B "каталог_копий" --instance=имя_экземпляра --wal-file-name=%f [параметры_удалённого_режима]'

Здесь путь_инсталляции — путь к каталогу установленной версии pg_probackup, которую вы хотите использовать, каталог_копий и имя_экземпляра должны указывать на уже проинициализированный для данного кластера БД копируемый экземпляр, а параметры_удалённого_режима должны задаваться только в случае расположения архива WAL в удалённой системе. Подробнее все возможные параметры archive-push рассматриваются в описании archive-push.

Параметр --wal-file-path задаёт путь к файлу WAL, используемому командой archive-push. Этот путь может быть абсолютным или относительным. Абсолютный путь используется как есть. Относительный путь интерпретируется относительно текущего рабочего каталога. При вызове через archive_command Postgres Pro выбирает текущим рабочим каталогом PGDATA, поэтому относительные пути вида pg_wal/... работают корректно:

archive_command = 'pg_probackup archive-push -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'

Если параметр --wal-file-path опущен, используется каталог pg_wal относительно текущего рабочего каталога:

archive_command = 'pg_probackup archive-push -B /backup --instance=main --wal-file-name=%f'

Примечание

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

Перед запуском сервера Postgres Pro можно проверить, что WAL корректно отправляется в архив, выполнив команду archive-push вручную из каталога PGDATA:

cd /var/lib/pgsql/data
pg_probackup archive-push -B /backup --instance=main --wal-file-path=pg_wal/000000010000000000000001 --wal-file-name=000000010000000000000001

После этих подготовительных действий вы сможете использовать режим доставки WAL ARCHIVE и делать резервные копии в режиме PAGE, а также выполнять восстановление на момент времени.

Вы можете просмотреть текущее состояние архива WAL, воспользовавшись командой show. За подробностями обратитесь к Подразделу «Просмотр оглавления архива WAL».

Если вы планируете выполнять страничное копирование и/или делать копии с ведомого сервера, используя режим доставки WAL ARCHIVE, при недостаточной транзакционной активности может потребоваться долго ждать заполнения очередного сегмента WAL. Чтобы ограничить время ожидания, вы можете воспользоваться параметром Postgres Pro archive_timeout на ведущем сервере. Значение этого параметра должно быть меньше значения --archive-timeout (по умолчанию 5 минут), чтобы заполненный сегмент успел передаться ведомому серверу и попасть в архив WAL, прежде чем копирование прервётся по тайм-ауту, заданному параметром --archive-timeout.

Примечание

Вместо использования команды pg_probackup archive-push вы можете воспользоваться любым другим средством, при условии, что в процессе непрерывного архивирования сегменты WAL будут попадать в каталог каталог_копий/wal/имя_экземпляра. Для сжатия сегментов, если в нём есть потребность, должен использоваться алгоритм gzip, а сжатые файлы сегментов должны иметь расширение .gz.

Примечание

Организовать непрерывное архивирование можно не только с помощью параметров archive_mode и archive_command, но и применяя утилиту pg_receivewal. В этом случае аргумент pg_receivewal -D каталог должен указывать на каталог каталог_копий/wal/имя_экземпляра. Программа pg_probackup принимает сжатые WAL, которые может сохранять pg_receivewal. Стратегию архивирования «без потерь» можно реализовать только с использованием pg_receivewal.

Настройка копирования с ведомого сервера #

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

После этих подготовительных действий вы можете делать резервные копии с ведомого сервера в режимах FULL, PAGE, DELTA или PTRACK, используя режим доставки WAL ARCHIVE или STREAM.

Копирование с ведомого сервера имеет следующие ограничения:

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

  • Все необходимые для резервной копии записи WAL должны содержать полные страницы. Для этого требуется включить режим full_page_writes на ведущем сервере и отказаться от использования в archive_command утилит, удаляющих полные страницы из файлов WAL, например, pg_compresslog.

Настройка проверки целостности кластера #

Для логической проверки кластера БД требуется дополнительная настройка (предполагается, что настройка производится для роли backup):

  • Установите расширение amcheck или amcheck_next в каждой базе кластера:

    CREATE EXTENSION amcheck;
  • Дайте роли backup в каждой базе данных кластера следующие права:

GRANT SELECT ON TABLE pg_catalog.pg_am TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_class TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_namespace TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_extension TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool, bool) TO backup;

Настройка частичного восстановления #

Если вы планируете производить частичное восстановление, выполните следующее дополнительное действие:

  • Дайте право на чтение pg_catalog.pg_database роли backup в той базе данных, через которую выполняется подключение к серверу Postgres Pro:

    GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;

Настройка удалённого режима #

Программа pg_probackup поддерживает удалённый режим, в котором резервное копирование, восстановление и архивирование WAL могут выполняться удалённо. В этом режиме каталог резервных копий находится в локальной системе, а целевой экземпляр Postgres Pro работает на удалённом компьютере. В настоящее время это поддерживается с использованием только одного сетевого протокола — SSH.

Настройте SSH #

Если вы хотите использовать pg_probackup в удалённом режиме (применяя SSH), выполните следующие действия:

  1. Установите pg_probackup в обеих системах: backup_host (сервер резервного копирования) и postgres_host (сервер баз данных).

  2. Для организации связи между узлами настройте подключение по SSH пользователя backup_user в системе backup_host к системе postrges_host под именем пользователя postgres без указания пароля:

    backup_user@backup_host:~$ ssh-copy-id postgres@postgres_host

    Здесь:

    • backup_host — система, в которой находится каталог копий.

    • postrges_host — система, в которой функционирует кластер Postgres Pro.

    • backup_user — пользователь в системе backup_host, от имени которого запускается pg_probackup.

    • postgres — пользователь в системе postgres_host, от имени которого запускаются процессы кластера Postgres Pro. Для Postgres Pro версии 11 и новее можно применить более безопасный подход, воспользовавшись возможностью предоставления доступа группе.

  3. Если вы будете использовать непрерывное архивирование WAL, настройте подключение по SSH пользователя postgres в системе postgres_host к системе backup_host под именем пользователя backup без указания пароля:

    postgres@postgres_host:~$ ssh-copy-id backup_user@backup_host
  4. Убедитесь, что pg_probackup в системе postgres_host можно найти при установке соединения по SSH. Например, чтобы обеспечить это в Bash можно изменить PATH в файле ~/.bashrc пользователя postgres (над строкой в bashrc, которая завершает скрипт для неинтерактивных оболочек). Либо для команд pg_probackup можно указать в параметре --remote-path путь к каталогу, содержащему программу pg_probackup в системе postgres_host.

pg_probackup работает в удалённом режиме по протоколу SSH следующим образом:

  • В удалённом режиме поддерживаются только следующие команды: add-instance, backup, restore, delete, catchup, archive-push и archive-get.

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

  • При запуске в удалённом режиме основной процесс pg_probackup в локальной системе подключается к удалённой по протоколу SSH и запускает в удалённой системе один или несколько агентов, которые называются удалёнными агентами. Количество удалённых агентов определяется значением параметра -j/--threads.

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

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

  • Основной процесс обычно запускается в системе backup_host и подключается к системе postgres_host, но для команд archive-push и archive-get основной процесс запускается в системе postgres_host и подключается к backup_host.

  • После завершения передачи данных удалённые агенты завершаются и подключения SSH закрываются.

  • Если какой-либо удалённый агент столкнулся с ошибкой, все агенты завершаются, а основной процесс pg_probackup выдаёт информацию о возникшей ошибке и также нештатно завершается.

  • Сжатие данных всегда осуществляется в системе postgres_host, а распаковка — в системе backup_host.

Примечание

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

Примечание

Если для pg_probackup, работающего в удалённом режиме через SSH, задать число потоков больше 10 (параметр -j/--threads), то фактическое число SSH-соединений может превысить максимально допустимое число одновременных SSH-соединений на удалённом сервере и, следовательно, приведёт к ошибке «ERROR: Agent error: kex_exchange_identification: Connection closed by remote host» (ОШИБКА: Ошибка агента: kex_exchange_identification: Соединение закрыто удалённым сервером). Чтобы исправить ошибку, либо уменьшите количество потоков pg_probackup, либо измените значение параметра конфигурации MaxStartups удалённого SSH-сервера. Если SSH настроен как служба xinetd на удалённом сервере, измените значение параметра конфигурации xinetd per_source, а не MaxStartups.

Настройка копирования PTRACK #

Примечание

Версии PTRACK ниже 2.0 признаны устаревшими и не поддерживаются. В Postgres Pro Standard и Postgres Pro Enterprise версии 11.9.1 и новее входит обновлённый PTRACK 2.0. Обновите ваш сервер, чтобы избежать проблем с резервными копиями, которые вы будете делать в дальнейшем, и обязательно сделайте копии ваших кластеров с обновлённым PTRACK, так как копии, полученные с использованием PTRACK 1.x, могут быть испорченными.

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

Примечание

Для роли, которая будет выполнять резервное копирование в режиме PTRACK (роль backup в примерах ниже), требуемые права доступа указаны в Подразделе «Настройка кластера баз данных». Роль должна иметь права только в той базе данных, которая используется для подключения к серверу Postgres Pro.

Для Postgres Pro версии 11 или новее:

  1. Создайте расширение PTRACK в базе данных, используемой для подключения к серверу Postgres Pro:

    CREATE EXTENSION ptrack;
  2. Чтобы включить отслеживание изменений страниц, задайте для параметра ptrack.map_size положительное целое значение и перезапустите сервер.

    Для оптимальной производительности рекомендуется задавать ptrack.map_size равным N / 1024, где N — объём кластера Postgres Pro в мегабайтах. Если он будет иметь меньшее значение, это увеличит вероятность наложения информации разных блоков в карте PTRACK, что повлечёт ложные положительные результаты при определении изменённых блоков и, как следствие, увеличение размера инкрементальной копии, так как в копию будут попадать и фактически неизменённые блоки. Использовать значения ptrack.map_size, превышающие 1024, не рекомендуется, хотя PTRACK поддерживает большие карты.

Примечание

В случае изменения значения ptrack.map_size ранее созданный файл карты PTRACK очищается, и отслеживание новых блоков начинается с начала. Таким образом, прежде чем создавать новые инкрементальные копии в режиме PTRACK после изменения ptrack.map_size необходимо сделать новую полную копию кластера.

Использование #

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

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

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

Здесь режим_копирования может принимать следующие значения: FULL, DELTA, PAGE, и PTRACK.

При восстановлении кластера из инкрементальной копии pg_probackup использует родительскую полную копию и все инкрементальные копии между ними, которые в совокупности образуют «цепочку копий». Таким образом, прежде чем делать инкрементальные копии, необходимо сделать как минимум одну полную со статусом OK или DONE в каталоге. Если родительская полная копия имеет статус MERGING или MERGED, выполнить инкрементальное резервное копирование невозможно.

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

ВНИМАНИЕ: Рабочая полная резервная копия не найдена в текущей линии времени, идёт поиск в предыдущих линиях времени
ВНИМАНИЕ: Невозможно найти рабочую резервную копию в предыдущих линиях времени
ОШИБКА: Создайте новую полную резервную копию до инкрементальной

Режим ARCHIVE #

Режим ARCHIVE используется в качестве режима доставки WAL по умолчанию.

Например, чтобы сделать полную копию в режиме доставки WAL ARCHIVE, выполните:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL

Резервное копирование ARCHIVE требует организации непрерывного архивирования, посредством которого считываются сегменты WAL, требующиеся для восстановления согласованного состояния кластера на момент создания копии.

В процессе резервного копирования pg_probackup помещает файлы WAL, содержащие записи от Start LSN до Stop LSN, в каталог каталог_копий/wal/имя_экземпляра. pg_probackup также проверяет, что записи WAL между Start LSN и Stop LSN корректно читаются. Это позволяет исключить риск хранения в архиве повреждённого WAL.

Режим STREAM #

Режим STREAM может использоваться в качестве альтернативного режима доставки WAL.

Например, чтобы сделать полную резервную копию в потоковом режиме, добавьте флаг --stream к команде, показанной выше:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --stream --temp-slot

Необязательный параметр --temp-slot обеспечивает наличие необходимых сегментов в случае прокрутки WAL до завершения резервного копирования.

В отличие от копий ARCHIVE, копии типа STREAM включают все сегменты WAL, необходимые для восстановления согласованного состояния кластера на момент создания копии.

В процессе выполнения команды backup программа pg_probackup передаёт файлы WAL, содержащие записи от Start LSN до Stop LSN в каталог каталог_копий/backups/имя_экземпляра/ид_резервной_копии/database/pg_wal. Чтобы исключить риск архивирования испорченных файлов WAL, pg_probackup также проверяет, что записи WAL от Start LSN до Stop LSN прочитываются корректно.

Даже если вы используете непрерывное архивирование, копирование в режиме STREAM может быть полезно в следующих случаях:

  • Копии типа STREAM могут быть восстановлены на сервере, не имеющем файлового доступа к архиву WAL.

  • Копии типа STREAM позволяют восстановить состояние кластера на тот момент времени, для которого уже нет файлов WAL.

  • Копирование в режиме STREAM можно производить с ведомого сервера, не дожидаясь заполнения сегментов WAL, что могло бы занять длительное время при небольшом объёме трафика WAL.

Проверка страниц #

Когда в кластере БД включены контрольные суммы, pg_probackup использует их для проверки целостности файлов данных в процессе резервного копирования. При чтении каждой страницы pg_probackup проверяет, совпадает ли вычисленная сумма с контрольной суммой, хранящейся в заголовке страницы. Это гарантирует, что в кластере Postgres Pro и самой резервной копии не содержатся испорченные страницы. Заметьте, что pg_probackup читает файлы данных непосредственно из файловой системы, поэтому при активной записи в момент копирования возможны ложные выявления некорректных контрольных сумм из-за частичной записи. В случае несовпадения контрольной суммы страница считывается повторно, и контрольная сумма проверяется ещё раз.

Страница признаётся испорченной, если проверка контрольной суммы не проходит более 300 раз. В этом случае резервное копирование прерывается.

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

Внешние каталоги #

Чтобы заархивировать каталог, размещённый вне каталога данных, воспользуйтесь необязательным параметром --external-dirs, в котором можно задать путь к нужному каталогу. Если вы хотите заархивировать несколько внешних каталогов, их пути нужно разделить двоеточиями в Linux или точками с запятой в Windows.

Например, чтобы в системе Linux включить каталоги /etc/dir1 и /etc/dir2 в полную копию экземпляра имя_экземпляра, которая будет размещаться в каталоге_копий, выполните:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --external-dirs=/etc/dir1:/etc/dir2

Например, чтобы включить каталоги C:\dir1 и C:\dir2 в полную копию, в Windows нужно выполнить:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --external-dirs=C:\dir1;C:\dir2

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

Чтобы нужные каталоги включались в каждую резервную копию вашего кластера, их список можно сохранить в файле конфигурации pg_probackup.conf, воспользовавшись командой set-config с ключом --external-dirs.

Проверка целостности кластера #

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

pg_probackup checkdb [-B каталог_копий [--instance=имя_экземпляра]] [-D каталог_данных] [параметры_подключения]

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

По умолчанию pg_probackup выполняет подобную проверку страницы автоматически в процессе создания копии. Команда checkdb позволяет при желании проводить проверки страниц в кластере, не создавая резервные копии (при этом даже необязательно настраивать копирование кластера в pg_probackup).

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

Важно понимать, что проверка на физическом уровне не позволяет выявить логические несоответствия, потерю или обнуление блоков или целых файлов и другие подобные аномалии. Провести логическую проверку в некотором объёме позволяют расширения amcheck и amcheck_next.

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

pg_probackup checkdb -D каталог_данных --amcheck [параметры_соединения]

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

pg_probackup checkdb --amcheck --skip-block-validation [параметры_соединения]

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

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

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

Если вы хотите пропустить проверку резервной копии, вы можете передать командам backup и restore флаг --no-validate.

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

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

pg_probackup validate -B каталог_копий --instance=имя_экземпляра --recovery-target-xid=4242

Если проверка проходит успешно, pg_probackup выдаёт сообщение об этом. В случае же неудачи вы получите сообщение об ошибке с указанием точного времени, идентификатора транзакции и значения LSN, до которого возможно восстановление.

Если вы укажете идентификатор копии в ключе -i/--backup-id, будет проверена только резервная копия с указанным идентификатором. Если идентификатор копии указывается вместе с параметрами точки восстановления, команда validate проверит, возможно ли восстановить указанную резервную копию до заданной точки.

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

pg_probackup validate -B каталог_копий --instance=имя_экземпляра -i SBOL6P --recovery-target-time="2024-04-10 18:18:26+03"

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

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

Восстановление кластера #

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

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

Здесь:

  • каталог_копий — каталог, в котором хранятся все файлы резервных копий и метаданные.

  • имя_экземпляра — имя экземпляра резервной копии кластера, который будет восстановлен.

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

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

Если вы восстанавливаете копию ARCHIVE, выполняете восстановление PITR или передаёте флаг --restore-as-replica команде restore для настройки ведомого сервера, pg_probackup создаёт файл конфигурации восстановления после копирования всех файлов данных в целевой каталог. Этот файл включает необходимые для восстановления параметры, за исключением пароля, заданного в primary_conninfo; если он требуется, его нужно дополнительно задать вручную или воспользоваться параметром --primary-conninfo. Для Postgres Pro версии 11 параметры восстановления сохраняются в файле recovery.conf, но для версий Postgres Pro, начиная с 12, pg_probackup сохраняет эти параметры в файле probackup_recovery.conf в каталоге данных и подключает его в postgresql.auto.conf.

Если восстанавливалась копия типа STREAM, восстановление завершается сразу, и кластер возвращается в согласованное состояние на момент времени, в который была сделана резервная копия. Для копий типа ARCHIVE Postgres Pro воспроизводит все имеющиеся в архиве сегменты WAL, в результате чего восстанавливается самое последнее состояние кластера на текущей линии времени. Это поведение можно изменить, определив параметры точки восстановления для команды restore как описывается в Подразделе «Выполнение восстановления на момент времени (PITR)».

Если кластер, подлежащий восстановлению, содержит табличные пространства, pg_probackup по умолчанию восстанавливает их в исходные расположения. Чтобы сменить расположения табличных пространств, воспользуйтесь параметром --tablespace-mapping/-T. В противном случае при восстановлении кластера на том же сервере произойдёт ошибка, если эти табличные пространства будут использоваться, так как восстанавливаемые данные нужно будет записать в те же каталоги.

Используя параметр --tablespace-mapping/-T, вы должны задать абсолютные пути к старому и новому каталогу табличного пространства. Если путь содержит знак равно (=), экранируйте его обратной косой чертой. Данный параметр может указываться неоднократно для перемещения нескольких табличных пространств. Например:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра -D каталог_данных -j 4 -i ид_резервной_копии -T каталог_табл_пространства1=новый_каталог_табл_пространства1 -T каталог_табл_пространства2=новый_каталог_табл_пространства2

Восстановление кластера на удалённом компьютере описано в Подразделе «Использование pg_probackup в удалённом режиме».

Примечание

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

Инкрементальное восстановление #

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

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

pg_probackup restore -B каталог_копий --instance=имя_экземпляра -D каталог_данных -I инкрементальный_режим
      

Здесь инкрементальный_режим может быть следующим:

  • CHECKSUM — прочитать все файлы данных в целевом каталоге, проверить заголовок и контрольную сумму каждой страницы и заменить только некорректные страницы, а также страницы, в которых контрольная сумма и LSN отличаются от значений в соответствующей странице в копии. Это самый простой и надёжный инкрементальный режим. Его рекомендуется использовать по умолчанию.

  • LSN — прочитать файл pg_control в каталоге данных, получить из него значения REDO LSN и REDO TLI, позволяющие определить точку в истории (точку сдвига), в которой состояние каталога данных сдвинулись с цепочки резервных копий. Если точка сдвига находится за пределами истории резервных копий, восстановление прерывается. Если же точка сдвига достижима, прочитываются все файлы данных в каталоге данных, проверяется заголовок и контрольная сумма на каждой странице, а затем заменяются только страницы с неверной контрольной суммой или с LSN, превышающим позицию точки сдвига. В этом режиме обеспечивается увеличенная скорость по сравнению с режимом CHECKSUM, но требуется выполнение двух условий. Во-первых, в целевом каталоге должны быть включены контрольные суммы (см. data_checksums), чтобы не произошло повреждения данных из-за изменения вспомогательных битов. Это условие будет проверяться перед инкрементальным восстановлением — в случае отсутствия контрольных сумм операция прерывается. Во-вторых, необходима синхронность файла pg_control с состоянием каталога данных. Это условие нельзя проверить в начале восстановления, так что гарантировать правильность информации в pg_control должен пользователь. Поэтому использовать режим LSN рекомендуется не во всех ситуациях, например, он противопоказан, когда файл pg_control повреждён или его содержимому нельзя доверять: после выполнения pg_resetxlog, после восстановления из копии без процедуры воспроизведения журнала и т. д.

  • NONE — обычное восстановление без инкрементальных оптимизаций.

Вне зависимости от выбранного инкрементального режима, pg_probackup будет проверять, что с заданным целевым каталогом не работает процесс postmaster и значения system-identifier в целевом экземпляре и копии совпадают.

Предположим, вы хотите восстановить старый ведущий сервер в виде реплики после переключения, используя инкрементальное восстановление в режиме LSN:

==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode    WAL Mode  TLI  Time   Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
==================================================================================================================================================
 node      17       SBOL8S  2024-04-09 18:19:43.707720+03  DELTA   STREAM    16/15    3s  114MB  64MB   lz4    1.42  0/3C003020  0/3E8D4930  OK     
 node      17       SBOL8G  2024-04-09 18:19:32.594670+03  PTRACK  STREAM    15/15    4s   30MB  16MB  zlib    2.23  0/31000028  0/310029E0  OK     
 node      17       SBOL83  2024-04-09 18:19:22.269595+03  PAGE    STREAM    15/15    7s   46MB  32MB  pglz    1.44  0/29000028  0/2A0000F8  OK     
 node      17       SBOL7P  2024-04-09 18:19:06.557301+03  FULL    STREAM    15/0     6s  144MB  16MB  zstd    2.47  0/22000028  0/220001C8  OK     

backup_user@backup_host:~$ pg_probackup restore -B /mnt/backups --instance=node -R -I lsn
INFO: Destination directory and tablespace directories are empty, disable incremental restore
INFO: Validating parents for backup SBOL8S
INFO: Validating backup SBOL7P
INFO: Backup SBOL7P data files are valid
INFO: Validating backup SBOL83
INFO: Backup SBOL83 data files are valid
INFO: Validating backup SBOL8G
INFO: Backup SBOL8G data files are valid
INFO: Validating backup SBOL8S
INFO: Backup SBOL8S data files are valid
INFO: Backup SBOL8S WAL segments are valid
INFO: Backup SBOL8S is valid.
INFO: Restoring the database from the backup starting at 2024-04-09 18:19:40+03
INFO: Start restoring backup files. PGDATA size: 616MB
INFO: Backup files are restored. Transferred bytes: 616MB, time elapsed: 2s
INFO: Restore incremental ratio (less is better): 100% (616MB/616MB)
INFO: Syncing restored files to disk
INFO: Restored backup files are synced, time elapsed: 2s
INFO: Restore of backup SBOL8S completed.

Примечание

Инкрементальное восстановление возможно только для копий, у которых program_version больше или равна 2.4.0.

Частичное восстановление #

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

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

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --db-include=имя_базы
      

Ключ --db-include может добавляться многократно. Например, чтобы восстановить только базы db1 и db2, выполните следующую команду:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --db-include=db1 --db-include=db2

Чтобы исключить одну или несколько баз из числа восстанавливаемых, используйте ключ --db-exclude:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --db-exclude=имя_базы

Ключ --db-exclude может добавляться многократно. Например, чтобы при восстановлении исключить базы данных db1 и db2, выполните следующую команду:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --db-exclude=db1 --db-exclude=db2

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

Чтобы максимально быстро разделить один кластер, содержащий несколько баз данных, на разные кластеры, можно выполнить частичное восстановление исходного кластера в виде ведомого, передав ключ --restore-as-replica для определённых баз данных.

Примечание

Базы template0 и template1 восстанавливаются всегда.

Примечание

Из-за особенностей восстановления, присущих версиям Postgres Pro до 12, при частичном восстановлении кластера Postgres Pro этих версий рекомендуется установить для параметра hot_standby значение off. В противном случае при восстановлении возможен сбой.

Выполнение восстановления на момент времени (PITR) #

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

Для восстановления на момент времени может использоваться копия типа STREAM или ARCHIVE, но при этом обязательно наличие архива WAL с момента создания копии или более раннего. Если параметр -i/--backup-id не задан, pg_probackup автоматически выбирает резервную копию, ближайшую к заданной цели восстановления, и начинает процесс восстановления. В противном случае pg_probackup попытается восстановить до заданной цели восстановления именно копию с заданным ид_резервной_копии.

  • Чтобы восстановить состояние кластера на определённый момент времени, укажите это время в параметре --recovery-target-time, в формате timestamp. Например:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target-time="2024-04-10 18:18:26+03"
  • Чтобы восстановить состояние кластера до определённой транзакции, воспользуйтесь ключом --recovery-target-xid:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target-xid=687
  • Чтобы восстановить состояние кластера до определённой позиции в журнале (LSN), воспользуйтесь ключом --recovery-target-lsn:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target-lsn=16/B374D848
  • Чтобы восстановить состояние кластера до заданной именованной точки восстановления, воспользуйтесь ключом --recovery-target-name:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target-name="before_app_upgrade"
  • Чтобы восстановить последнее возможное состояние, исходя из содержимого архива WAL, передайте в параметре --recovery-target значение latest:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target="latest"
  • Чтобы восстановить самое раннее из возможных согласованное состояние кластера, передайте в параметре --recovery-target значение immediate:

    pg_probackup restore -B каталог_копий --instance=имя_экземпляра --recovery-target='immediate'

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

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

Использование pg_probackup в удалённом режиме #

Программа pg_probackup поддерживает работу в удалённом режиме, то есть может выполнять операции backup и restore удалённо, используя SSH. В этом режиме каталог резервных копий располагается в локальной системе, а целевой экземпляр Postgres Pro работает в удалённой. При этом pg_probackup должен быть установлен в обеих системах.

Примечание

pg_probackup рассчитывает на то, что узлы будут взаимодействовать между собой с использованием SSH без пароля.

Примечание

Помимо подключения по SSH, pg_probackup использует для управления удалёнными операциями обычное подключение к базе данных. За подробной информацией о настройке подключения к базе данных обратитесь к разделу Настройка кластера базы данных.

Типичная схема его использования выглядит так:

Например, чтобы создать полную архивную копию кластера Postgres Pro, работающего в удалённой системе с адресом 192.168.0.2, подключившись к серверу по SSH через порт 2302 с именем пользователя postgres, выполните:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

Чтобы восстановить последнюю имеющуюся копию в удалённой системе с адресом 192.168.0.2, подключившись к серверу по SSH через порт 2302 с именем пользователя postgres, выполните:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

Для восстановления архивных копий или восстановления на момент времени в удалённом режиме требуется дополнительная информация: целевой адрес, порт и имя пользователя для установления SSH-подключения c сервера БД к системе, где находится каталог копий. Эту информацию будет использовать команда restore_command для копирования сегментов WAL из архива в каталог Postgres Pro pg_wal.

Для передачи этой информации вы можете задать параметры удалённого архива WAL.

Например, для восстановления последней копии в удалённой системе, настроенной для приёма подключения пользователя postgres по адресу 192.168.0.2 через порт 2302, с использованием каталога резервных копий в системе, настроенной для подключения пользователя backup по адресу 192.168.0.3 через порт 2303, выполните:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --archive-host=192.168.0.3 --archive-port=2303 --archive-user=backup

Переданные аргументы будут использоваться при составлении команды restore_command:

restore_command = '"путь_инсталляции/pg_probackup" archive-get -B "каталог_копий" --instance=имя_экземпляра --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Также вы можете воспользоваться ключом --restore-command и передать всю команду restore_command целиком:

pg_probackup restore -B каталог_копий --instance=имя_экземпляра --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --restore-command='"путь_инсталляции/pg_probackup" archive-get -B "каталог_копий" --instance=имя_экземпляра --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Примечание

Использование удалённого режима на платформе Windows в настоящее время не поддерживается.

Запуск pg_probackup в параллельных потоках #

Команды backup, restore, merge, delete, checkdb и validate могут выполняться в несколько параллельных потоков. Это может существенно ускорять работу pg_probackup при наличии достаточных ресурсов (ядер процессора, производительности дисковой подсистемы и сети).

Параллельным выполнением управляет ключ командной строки -j/--threads. Например, чтобы запустить резервное копирование в четыре параллельных потока, выполните:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL -j 4

Примечание

Восстановление происходит в параллельном режиме только на этапе копирования данных из каталога копий в каталог данных кластера. При запуске сервера Postgres Pro он должен будет воспроизвести записи из WAL, а это может происходить только последовательно.

Важно

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

Настройка pg_probackup #

Проинициализировав каталог резервных копий и добавив определение копируемого экземпляра, вы можете использовать файл pg_probackup.conf в каталоге каталог_копий/backups/имя_экземпляра для тонкой настройки конфигурации pg_probackup.

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

Примечание

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

Изначально pg_probackup.conf содержит следующие параметры:

  • PGDATA — путь к каталогу данных кластера, который будет копироваться.

  • system-identifier — уникальный идентификатор экземпляра Postgres Pro.

Вы можете дополнительно установить параметры удалённого режима, хранения копий, ведения журнала и сжатия, используя команду set-config:

pg_probackup set-config -B каталог_копий --instance=имя_экземпляра
[--external-dirs=путь_внешнего_каталога] [параметры_удалённого_режима] [параметры_соединения] [параметры_хранения] [параметры_журнала]

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

pg_probackup show-config -B каталог_копий --instance=имя_экземпляра

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

Указание параметров подключения #

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

Если не задано ничего, используются значения по умолчанию. В частности, pg_probackup пытается подключиться к Unix-сокету локального сервера (или к localhost в Windows), а в качестве имени базы данных и имени пользователя выбирает значение переменной окружения PGUSER либо имя текущего пользователя ОС.

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

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

Просмотр информации о резервных копиях #

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

pg_probackup show -B каталог_копий

pg_probackup выводит список всех имеющихся резервных копий. Например:

BACKUP INSTANCE 'node'
==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode    WAL Mode  TLI  Time   Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status
==================================================================================================================================================
 node      17       SBOL94  2024-04-09 18:19:56.603355+03  FULL    ARCHIVE   1/0    6s  377MB  16MB   lz4    1.46  0/41000028  0/420000C0  OK
 node      17       SBOL8S  2024-04-09 18:19:43.707720+03  DELTA   STREAM    1/1    3s  114MB  64MB   lz4    1.42  0/3C003020  0/3E8D4930  OK
 node      17       SBOL8G  2024-04-09 18:19:32.594670+03  PTRACK  STREAM    1/1    4s   30MB  16MB  zlib    2.23  0/31000028  0/310029E0  OK
 node      17       SBOL83  2024-04-09 18:19:22.269595+03  PAGE    STREAM    1/1    7s   46MB  32MB  pglz    1.44  0/29000028  0/2A0000F8  OK
 node      17       SBOL7P  2024-04-09 18:19:06.557301+03  FULL    STREAM    1/0    6s  144MB  16MB  zstd    2.47  0/22000028  0/220001C8  OK

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

  • Instance — имя экземпляра.

  • Version — базовая версия Postgres Pro.

  • ID — идентификатор резервной копии.

  • Recovery time — самое ранее время, на которое можно восстановить кластер из данной копии.

  • Mode — режим, в котором была сделана копия. Возможные значения: FULL (полная), PAGE (страничная), DELTA (инкрементальная), PTRACK (копирование изменений).

  • WAL Mode — режим доставки WAL. Возможные значения: STREAM (потоковый) и ARCHIVE (архивный).

  • TLI — идентификаторы линии времени текущей копии и её родителя.

  • Time — время, за которое была выполнена данная копия.

  • Data — объём файлов данных в этой копии. Это значение не включает в себя объём файлов WAL. Для копий, сделанных в режиме STREAM, общий размер можно рассчитать, сложив значения Data и WAL.

  • WAL — размер несжатых файлов WAL, которые должны быть применены в процессе восстановления копии для достижения согласованного состояния.

  • compress-alg — алгоритм сжатия, используемый при получении резервной копии. Возможные значения: zlib, pglz, lz4, zstd и none (сжатие не производилось).

  • Zratio — коэффициент сжатия, вычисленный как отношение «uncompressed-bytes» (объём несжатых данных в байтах) к «data-bytes» (итоговый объём данных).

  • Start LSN — последовательный номер в журнале WAL, соответствующий началу процесса копирования. С этой позиции накатываются изменения (REDO) в процессе восстановления Postgres Pro.

  • Stop LSN — последовательный номер в журнале WAL, соответствующий окончанию процесса копирования. Это позиция точки согласованности при восстановлении Postgres Pro.

  • Status — состояние резервной копии. Возможные варианты:

    • OK — резервная копия сделана и пригодна к использованию.

    • DONE — резервная копия сделана, но не проверена.

    • RUNNING — резервное копирование выполняется.

    • MERGING — резервная копия объединяется.

    • MERGED — файлы резервной копии были успешно обработаны в процессе объединения копий, но её метаданные ещё изменяются. Это состояние могут иметь только полные резервные копии.

    • DELETING — файлы резервной копии удаляются.

    • CORRUPT — некоторые файлы резервной копии повреждены.

    • ERROR — резервное копирование было прервано из-за неожиданной ошибки.

    • ORPHAN — резервная копия непригодна к использованию, так как её родительская копия испорчена или отсутствует.

    • HIDDEN_FOR_TEST — скрипт теста пометил копию как несуществующую. (Собственно pg_probackup никогда не устанавливает это состояние.)

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

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

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

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

#Configuration
backup-mode = FULL
stream = false
compress-alg = lz4
compress-level = 1
from-replica = false

#Compatibility
block-size = 8192
xlog-block-size = 8192
checksum-version = 1
program-version = 2.7.3
server-version = 17

#Result backup info
timelineid = 1
start-lsn = 0/41000028
stop-lsn = 0/420000C0
start-time = '2024-04-09 18:19:52+03'
end-time = '2024-04-09 18:19:58+03'
end-validation-time = '2024-04-09 18:19:59+03'
recovery-xid = 757
recovery-time = '2024-04-09 18:19:56.603355+03'
data-bytes = 395651278
wal-bytes = 16777216
uncompressed-bytes = 578552566
pgdata-bytes = 578552248
status = OK
primary_conninfo = 'user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable'
content-crc = 3862224379

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

  • compress-alg — алгоритм сжатия, используемый при получении резервной копии. Возможные значения: zlib, pglz, lz4, zstd и none (сжатие не производилось).

  • compress-level — уровень сжатия, применяемый в процессе резервного копирования.

  • from-replica — признак того, что копия была сделана с ведомого сервера. Возможные значения: 1, 0.

  • block-size — значение параметра block_size, установленное в кластере Postgres Pro, с которого была сделана копия.

  • checksum-version — признак включения параметра data_checksums в исходном кластере Postgres Pro. Возможные значения: 1, 0.

  • program-version — полная версия программы pg_probackup, которая создала эту копию.

  • start-time — время начала резервного копирования.

  • end-time — время окончания резервного копирования.

  • end-validation-time — время окончания проверки резервной копии.

  • expire-time — время, когда закреплённая копия может быть ликвидирована в соответствии с политикой хранения. Этот атрибут имеется только у закреплённых копий.

  • uncompressed-bytes — размер файлов данных до добавления заголовков страниц и сжатия. В случае использования сжатия оценить его эффективность можно, сопоставив объём uncompressed-bytes (байтов несжатых данных) с data-bytes (байтов данных).

  • pgdata-bytes — размер файлов данных Postgres Pro на момент копирования. Эффективность инкрементального метода копирования можно оценить, сопоставив объём pgdata-bytes (байтов в PGDATA) с uncompressed-bytes (байтов несжатых данных).

  • recovery-xid — идентификатор транзакции, соответствующей моменту окончания резервного копирования.

  • parent-backup-id — идентификатор родительской копии. Определён только для инкрементальных копий.

  • primary_conninfo — параметры подключения libpq, с использованием которых производилось подключение к кластеру Postgres Pro для получения этой резервной копии. Пароль в эти параметры не включается.

  • note — текстовое примечание, связанное с копией.

  • content-crc — контрольная сумма файла backup_content.control, рассчитанная по алгоритму CRC32. Она позволяет выявить повреждение метаданных копии.

Вы также можете получить подробную информацию о резервной копии в формате JSON:

pg_probackup show -B каталог_копий --instance=имя_экземпляра --format=json -i backup_id

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

[
    {
        "instance": "node",
        "backups": [
            {
                "id": "SBOL94",
                "status": "OK",
                "start-time": "2024-04-09 18:19:52+03",
                "backup-mode": "FULL",
                "wal": "ARCHIVE",
                "compress-alg": "lz4",
                "compress-level": 1,
                "from-replica": "false",
                "block-size": 8192,
                "xlog-block-size": 8192,
                "checksum-version": 1,
                "program-version": "2.7.3",
                "server-version": "17",
                "current-tli": 16,
                "parent-tli": 2,
                "start-lsn": "0/41000028",
                "stop-lsn": "0/420000C0",
                "end-time": "2024-04-09 18:19:58+03",
                "end-validation-time": "2024-04-09 18:19:59+03",
                "recovery-xid": 757,
                "recovery-time": "2024-04-09 18:19:56.603355+03",
                "data-bytes": 395651278,
                "wal-bytes": 16777216,
                "uncompressed-bytes": 578552566,
                "pgdata-bytes": 578552248,
                "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                "content-crc": 3862224379
            }
        ]
    }
]

Просмотр оглавления архива WAL #

Чтобы получить информацию об архиве WAL для каждого экземпляра, выполните команду:

pg_probackup show -B каталог_копий [--instance=имя_экземпляра] --archive

pg_probackup выводит список всех имеющихся файлов WAL, сгруппированных по линиям времени. Например:

ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          00000001000000000000001B  000000010000000000000042  40          640MB  1.00    5          OK     

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

  • TLI — идентификатор линии времени.

  • Parent TLI — идентификатор линии времени, от которой была ответвлена данная.

  • Switchpoint — LSN момента, когда эта линия времени ответвилась от родительской.

  • Min Segno — первый сегмент WAL, относящийся к этой линии времени.

  • Max Segno — последний сегмент WAL, относящийся к этой линии времени.

  • N segments — количество сегментов WAL, относящихся к этой линии времени.

  • Size — объём, который занимают файлы на диске.

  • Zalg — алгоритм сжатия, используемый при получении резервной копии. Возможные значения: zlib, pglz, lz4, zstd и none (сжатие не производилось).

  • Zratio — коэффициент сжатия, вычисляемый по формуле N segments * wal_segment_size * wal_block_size / Size.

  • N backups — число копий, относящихся к этой линии времени. Для получения подробных сведений об этих копиях воспользуйтесь форматом JSON.

  • Status — состояние архива WAL для этой линии времени. Возможные значения:

    • OK — в архиве присутствуют все сегменты WAL между Min Segno и Max Segno.

    • DEGRADED — отсутствуют некоторые сегменты WAL между Min Segno и Max Segno. Понять, какие файлы утрачены, можно, посмотрев этот отчёт в формате JSON. Такой статус может возникать, если несколько файлов WAL (в середине последовательности) были удалены командой delete с параметром --delete-wal в соответствии с политикой хранения. Данный статус не влияет на корректность восстановления, но восстановить кластер до некоторых точек восстановления может быть невозможно.

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

pg_probackup show -B каталог_копий [--instance=имя_экземпляра] --archive --format=json

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

[
    {
        "instance": "node",
        "timelines": [
            {
                "tli": 1,
                "parent-tli": 0,
                "switchpoint": "0/0",
                "min-segno": "00000001000000000000001B",
                "max-segno": "000000010000000000000042",
                "n-segments": 40,
                "size": 671088640,
                "zratio": 1.00,
                "closest-backup-id": "",
                "status": "OK",
                "lost-segments": [],
                "backups": [
                    {
                        "id": "SBOL94",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:52+03",
                        "backup-mode": "FULL",
                        "wal": "ARCHIVE",
                        "compress-alg": "lz4",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 2,
                        "parent-tli": 0,
                        "start-lsn": "0/41000028",
                        "stop-lsn": "0/420000C0",
                        "end-time": "2024-04-09 18:19:58+03",
                        "end-validation-time": "2024-04-09 18:19:59+03",
                        "recovery-xid": 757,
                        "recovery-time": "2024-04-09 18:19:56.603355+03",
                        "data-bytes": 395651278,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 578552566,
                        "pgdata-bytes": 578552248,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 3862224379
                    },
                    {
                        "id": "SBOL8S",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:40+03",
                        "parent-backup-id": "SBOL8G",
                        "backup-mode": "DELTA",
                        "wal": "STREAM",
                        "compress-alg": "lz4",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/3C003020",
                        "stop-lsn": "0/3E8D4930",
                        "end-time": "2024-04-09 18:19:43+03",
                        "end-validation-time": "2024-04-09 18:19:44+03",
                        "recovery-xid": 757,
                        "recovery-time": "2024-04-09 18:19:43.707720+03",
                        "data-bytes": 119350434,
                        "wal-bytes": 67108864,
                        "uncompressed-bytes": 170044286,
                        "pgdata-bytes": 578552248,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 1259851036
                    },
                    {
                        "id": "SBOL8G",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:28+03",
                        "parent-backup-id": "SBOL83",
                        "backup-mode": "PTRACK",
                        "wal": "STREAM",
                        "compress-alg": "zlib",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/31000028",
                        "stop-lsn": "0/310029E0",
                        "end-time": "2024-04-09 18:19:32+03",
                        "end-validation-time": "2024-04-09 18:19:33+03",
                        "recovery-xid": 756,
                        "recovery-time": "2024-04-09 18:19:32.594670+03",
                        "data-bytes": 31218302,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 69610366,
                        "pgdata-bytes": 510263736,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 2293248595
                    },
                    {
                        "id": "SBOL83",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:15+03",
                        "parent-backup-id": "SBOL7P",
                        "backup-mode": "PAGE",
                        "wal": "STREAM",
                        "compress-alg": "pglz",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/29000028",
                        "stop-lsn": "0/2A0000F8",
                        "end-time": "2024-04-09 18:19:22+03",
                        "end-validation-time": "2024-04-09 18:19:22+03",
                        "recovery-xid": 755,
                        "recovery-time": "2024-04-09 18:19:22.269595+03",
                        "data-bytes": 48394744,
                        "wal-bytes": 33554432,
                        "uncompressed-bytes": 69577598,
                        "pgdata-bytes": 441975224,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 343227200
                    },
                    {
                        "id": "SBOL7P",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:01+03",
                        "backup-mode": "FULL",
                        "wal": "STREAM",
                        "compress-alg": "zstd",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 0,
                        "start-lsn": "0/22000028",
                        "stop-lsn": "0/220001C8",
                        "end-time": "2024-04-09 18:19:07+03",
                        "end-validation-time": "2024-04-09 18:19:09+03",
                        "recovery-xid": 754,
                        "recovery-time": "2024-04-09 18:19:06.557301+03",
                        "data-bytes": 151177272,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 373695222,
                        "pgdata-bytes": 373694904,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 1636300818
                    }
                ]
            }
        ]
    }
]

В основном в этом формате представлены те же поля, что и в текстовом формате, с некоторыми исключениями:

  • Размер выражается в байтах.

  • Атрибут closest-backup-id содержит идентификатор самой последней доступной копии, принадлежащей к одной из предыдущих линий времени. Вы можете использовать эту копию для восстановления на момент, относящийся к этой линии времени. Если такой копии не существует, данный атрибут будет пустым.

  • В массиве lost-segments представлены интервалы отсутствующих сегментов на линиях времени в непригодном состоянии (DEGRADED). На линиях времени в целостном состоянии OK массив lost-segments пуст.

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

Настройка политики хранения #

Используя pg_probackup, вы можете реализовать политики хранения резервных копий, в соответствии с которыми могут удаляться лишние копии, очищаться ненужные сегменты WAL. Кроме того, можно закреплять определённые копии, чтобы они сохранялись независимо от политики, как описано ниже. Эти подходы можно комбинировать произвольным образом.

Удаление ненужных копий #

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

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

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

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

--retention-window=окно

Определяет самый ранний момент времени, на который pg_probackup может выполнить восстановление. В этом параметре задаётся количество дней от текущего момента. Например, если retention-window=7, должна сохраниться минимум одна копия старее 7 дней, вместе с соответствующими файлами WAL и всеми последующими копиями.

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

pg_probackup set-config -B каталог_копий --instance=имя_экземпляра --retention-redundancy=2 --retention-window=7

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

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

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-expired

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-expired --delete-wal

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-expired --retention-window=7 --retention-redundancy=2

Так как для инкрементальных копий требуется наличие всех родительских полных копий и всех предыдущих инкрементальных копий, даже по истечении срока их хранения эти копии нельзя удалить, пока минимум одна инкрементальная копия в цепочке удовлетворяет политике хранения. Чтобы не хранить устаревшие копии, которые всё ещё нужны для восстановления нужной инкрементальной копии, вы можете объединить их с ней, воспользовавшись ключом --merge-expired команды backup или delete.

Предположим, что вы заархивировали экземпляр узла в каталог_копий со значением параметра --retention-window, равным 6, и значением параметра --retention-redundancy, равным 2, и на 1 августа 2024 г. у вас есть следующие копии:

BACKUP INSTANCE 'node'
===========================================================================================================================================
 Instance  Version  ID      Recovery Time           Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
===========================================================================================================================================
 node      17       SHJ1N9  2024-08-01 09:50:00+03  FULL   ARCHIVE   1/0    5s    13MB  16MB  zstd    2,81  0/1D000028  0/1E0000C0  OK
 node      17       SHJ1N8  2024-08-01 09:49:59+03  DELTA  ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/1A000028  0/1B0000C0  OK
 node      17       SHH6Z8  2024-07-31 09:49:59+03  PAGE   ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/17000028  0/180000C0  OK
 node      17       SHFCB6  2024-07-30 09:49:57+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,83  0/14000028  0/150000C0  OK
 node      17       SH9SB5  2024-07-27 09:49:56+03  PAGE   ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/11000028  0/120000C0  OK
 ----------------------------------------------------------retention window-----------------------------------------------------------
 node      17       SH62Z5  2024-07-25 09:49:56+03  DELTA  ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/E000028   0/F0000C0   OK
 node      17       SH48B3  2024-07-24 09:49:54+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,86  0/B000028   0/C0000C0   OK
 node      17       SGWTN3  2024-07-20 09:49:54+03  PAGE   ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/8000028   0/90000C0   OK
 node      17       SGUYZ2  2024-07-19 09:49:53+03  DELTA  ARCHIVE   1/1    5s  6442kB  16MB  zstd    1,07  0/5000028   0/60000C0   OK
 node      17       SGT4B1  2024-07-18 09:49:52+03  FULL   ARCHIVE   1/0    5s    11MB  16MB  zstd    2,89  0/2000028   0/3003A28   OK

При запуске команды delete с флагом --delete-expired резервные копии с идентификаторами SGT4B1, SGUYZ2 и SGWTN3 будут удалены как устаревшие по критериям окна хранения и избыточности (требуемый набор полных резервных копий уже сохранён). SGUYZ2 и SGWTN3 также будут удалены, поскольку базовая полная копия потеряла актуальность.

При запуске команды delete с флагом --merge-expired резервные копии SH48B3 и SH62Z5 будут объединены с SH9SB5. Объединение произойдёт именно с SH9SB5, так как это первая актуальная разностная копия, которую можно объединить с неактуальной разностной копией SH62Z5 и неактуальной полной копией SH48B3.

pg_probackup delete -B каталог_копий --instance=узел --delete-expired --merge-expired
pg_probackup show -B каталог_копий
BACKUP INSTANCE 'node'
===========================================================================================================================================
 Instance  Version  ID      Recovery Time           Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status
===========================================================================================================================================
 node      17       SHJ1N9  2024-08-01 09:50:00+03  FULL   ARCHIVE   1/0    5s    13MB  16MB  zstd    2,81  0/1D000028  0/1E0000C0  OK
 node      17       SHJ1N8  2024-08-01 09:49:59+03  DELTA  ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/1A000028  0/1B0000C0  OK
 node      17       SHH6Z8  2024-07-31 09:49:59+03  PAGE   ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/17000028  0/180000C0  OK
 node      17       SHFCB6  2024-07-30 09:49:57+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,83  0/14000028  0/150000C0  OK
 node      17       SH9SB5  2024-07-27 09:49:56+03  FULL   ARCHIVE   1/0    1s    12MB  16MB  zstd    2,84  0/11000028  0/120000C0  OK

Поле Time (Время) для объединённой копии показывает время, которое заняла процедура объединения.

Закрепление резервных копий #

Если вам нужно хранить отдельные копии дольше, чем допускает установленная политика хранения, вы можете дополнительно закрепить их на определённое время. Например:

pg_probackup set-backup -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии --ttl=30d

Эта команда задаёт срок хранения заданной резервной копии 30 дней, начиная с момента, указанного в атрибуте recovery-time этой копии.

Вы также можете явно задать время истечения срока хранения копии, воспользовавшись ключом --expire-time. Например:

pg_probackup set-backup -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии --expire-time="2027-04-09 18:21:32+00"

Также можно воспользоваться ключами --ttl и --expire-time команды backup и сразу закрепить создаваемую копию:

pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --ttl=30d
pg_probackup backup -B каталог_копий --instance=имя_экземпляра -b FULL --expire-time="2027-04-09 18:21:32+00"

Определить, закреплена ли копия, можно с помощью команды show:

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

Если копия закреплена, у неё есть атрибут expire-time, содержащий время окончания срока её хранения:

...
recovery-time = '2024-04-09 18:21:32+00'
expire-time = '2027-04-09 18:21:32+00'
data-bytes = 22288792
...

Отменить закрепление копии можно, передав в параметре --ttl ноль:

pg_probackup set-backup -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии --ttl=0

Примечание

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

Настройка политики хранения архива WAL #

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

Чтобы настроить политику хранения архива WAL, запустите команду set-config с параметром --wal-depth, задающим количество копий, которые могут быть использованы для PITR. Этот параметр действует для всех линий времени, поэтому вы сможете выполнять PITR для одинакового количества копий на каждой линии времени, при их наличии. Закреплённые копии в этом числе не учитываются: если закрепляется одна из последних копий, pg_probackup обеспечивает возможность PITR для каждой дополнительной копии.

Чтобы удалить сегменты WAL, не удовлетворяющие заданной политике хранения архива WAL, вы должны просто выполнить команду delete или backup с флагом --delete-wal. Для архивных копий сегменты WAL между Start LSN и Stop LSN всегда сохраняются, так что эти копии остаются рабочими вне зависимости от значения --wal-depth и при необходимости могут быть восстановлены.

Вы также можете использовать параметр --wal-depth с командами delete и backup для переопределения ранее заданной политики сохранения WAL и удаления старых сегментов WAL «на лету».

Предположим, что вы заархивировали экземпляр node в каталог_копий и настроили непрерывное архивирование WAL:

pg_probackup show -B каталог_копий --instance=узел
==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
==================================================================================================================================================
 node      17       SBOLDA  2024-04-09 18:22:23.147138+03  DELTA  STREAM    1/1    1s  1165kB  16MB  zstd    1.09  0/6F000028  0/6F000190  OK     
 node      17       SBOLCY  2024-04-09 18:22:16.079841+03  FULL   STREAM    1/0   10s   278MB  16MB  zstd    2.46  0/6D000028  0/6D000190  OK     
 node      17       SBOLCW  2024-04-09 18:22:10.154022+03  DELTA  STREAM    1/1    2s  1364kB  16MB  zstd    1.01  0/6B000028  0/6B000190  OK     
 node      17       SBOLCS  2024-04-09 18:22:07.521646+03  DELTA  STREAM    1/1    4s    78MB  16MB  zstd    2.41  0/69000028  0/69000190  OK     
 node      17       SBOLCC  2024-04-09 18:21:55.830115+03  FULL   STREAM    1/0   15s   278MB  96MB  zstd    2.46  0/600060C8  0/64FE6640  OK     
 node      17       SBOLBW  2024-04-09 18:21:38.399702+03  FULL   STREAM    1/0   12s   278MB  96MB  zstd    2.46  0/54001830  0/589E5908  OK     

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

pg_probackup show -B каталог_копий --instance=node --archive
ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          000000010000000000000052  00000001000000000000006F  30          480MB  1.00    6          OK     

Операция очистки WAL без ключа --wal-depth может удалить лишь один сегмент:

pg_probackup delete -B каталог_копий --instance=node --delete-wal
ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          000000010000000000000054  00000001000000000000006F  28          448MB  1.00    6          OK     

Например, если вы хотите оставить только те сегменты, которые могут применяться к самой последней копии, передайте в параметре --wal-depth значение 1:

pg_probackup delete -B каталог_копий --instance=node --delete-wal --wal-depth=1
ARCHIVE INSTANCE 'node'
===============================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size  Zratio  N backups  Status
===============================================================================================================================
 1    0           0/0          000000010000000000000002  000000010000000000000047  70          34MB  32.00   6          OK     

Также вы можете использовать параметр --wal-depth с командой backup:

pg_probackup backup -B каталог_данных --instance=node -b DELTA --wal-depth=1 --delete-wal
ARCHIVE INSTANCE 'node'
===============================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size  Zratio  N backups  Status 
===============================================================================================================================
 1    0           0/0          000000010000000000000071  000000010000000000000071  1           16MB  1.00    7          OK     

Объединение резервных копий #

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

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

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

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

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

Если процесс объединения ещё не закончен, вы увидите состояние MERGING. Для полных копий также можно увидеть состояние MERGED в процессе изменения метаданных на последнем этапе объединения. В случае прерывания операции объединения она может быть перезапущена.

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

Не рекомендуется принудительно завершать операции объединения — это может нарушить дальнейшую работу команды merge и проверку резервных копий.

Удаление резервных копий #

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

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

Эта команда удалит резервную копию с заданным ид_резервной_копии вместе со всеми инкрементальными копиями, которые от неё зависят (если таковые найдутся). Таким образом вы можете удалить некоторые последние инкрементальные копии, сохранив предыдущую полную копию и некоторые следующие за ней инкрементальные копии.

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-wal

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-expired

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

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --delete-expired --merge-expired

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

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

Для удаления всех копий с определённым состоянием, воспользуйтесь параметром --status:

pg_probackup delete -B каталог_копий --instance=имя_экземпляра --status=ERROR
    

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

Клонирование и синхронизация экземпляра Postgres Pro #

В pg_probackup реализована команда catchup, которая позволяет создать копию экземпляра сервера Postgres Pro напрямую, не используя каталог резервных копий. Эта команда может быть полезна:

  • Для добавления нового ведомого сервера.

    Как правило, для создания копии экземпляра Postgres Pro используется pg_basebackup. Команда catchup, если указан пустой целевой каталог, сделает то же самое, но в параллельном режиме может сработать гораздо быстрее.

  • Для синхронизации отставшего ведомого сервера с ведущим.

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

Операция catchup отличается от других операций pg_probackup:

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

  • В качестве метода доставки WAL поддерживается только STREAM.

  • Копирование внешних каталогов не поддерживается.

  • Одновременно с catchup нельзя выполнять команды DDL CREATE TABLESPACE/DROP TABLESPACE.

  • При синхронизации catchup берёт файлы конфигурации, такие как postgresql.conf, postgresql.auto.conf или pg_hba.conf, с исходного сервера и заменяет ими соответствующие файлы на целевом сервере. Чтобы оставить файлы конфигурации без изменений, используйте параметр --exclude-path.

Чтобы подготовить экземпляр Postgres Pro к клонированию/синхронизации, настройте исходный сервер БД следующим образом:

Перед клонированием/синхронизацией экземпляра Postgres Pro убедитесь, что исходный сервер запущен и принимает подключения. Чтобы клонировать/синхронизировать экземпляр Postgres Pro, в системе с целевым сервером выполните команду catchup:

pg_probackup catchup -b режим_синхронизации --source-pgdata=путь_к_копируемому_каталогу_данных --destination-pgdata=путь_к_целевому_каталогу_данных --stream [параметры_подключения] [параметры_удалённого_режима]

Здесь режим_синхронизации может принимать следующие значения:

  • FULL — создаётся полная копия экземпляра Postgres Pro, для этого целевой каталог данных БД должен быть пустым.

  • DELTA — считываются все файлы данных в каталоге данных и создаётся инкрементальная копия для страниц, изменённых с момента остановки целевого экземпляра.

  • PTRACK — изменения в страницах отслеживаются на лету, считываются и копируются только страницы, изменённые с точки расхождения исходного и целевого экземпляров.

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

    Чтобы синхронизировать экземпляр в режиме PTRACK, необходим PTRACK версии 2.0 или выше, а значит, и Postgres Pro версии не ниже 11.

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

Вы можете задать параметры_подключения к исходной БД, а если она находится на другом сервере, также укажите параметры_удалённого_режима.

Если в исходной БД есть табличные пространства, которые должны располагаться в других каталогах в целевой системе, задайте также параметр --tablespace-mapping:

pg_probackup catchup -b режим_синхронизации --source-pgdata=путь_к_копируемому_каталогу_данных --destination-pgdata=путь_к_целевому_каталогу_данных --stream --tablespace-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ

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

pg_probackup catchup -b режим_синхронизации --source-pgdata=путь_к_копируемому_каталогу_данных --destination-pgdata=путь_к_целевому_каталогу_данных --stream --threads=число_потоков

Перед клонированием/синхронизацией экземпляра Postgres Pro вы можете запустить команду catchup с флагом --dry-run, чтобы оценить размер передаваемых файлов данных без внесения изменений на диск:

pg_probackup catchup -b режим_синхронизации --source-pgdata=путь_к_копируемому_каталогу_данных --destination-pgdata=путь_к_целевому_каталогу_данных --stream --dry-run

Например, предположим, что отстал удалённый ведомый экземпляр Postgres Pro, данные которого хранятся в каталоге /replica-pgdata. Чтобы синхронизировать этот экземпляр с экземпляром в каталоге данных /master-pgdata, вы можете выполнить команду catchup, включив режим PTRACK и используя четыре параллельных потока, следующим образом:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=PTRACK --remote-host=remote-hostname --remote-user=remote-unix-username -j 4 --exclude-path=postgresql.conf --exclude-path=postgresql.auto.conf --exclude-path=pg_hba.conf --exclude-path=pg_ident.conf

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

В примере ниже показано, как можно добавить ещё один удалённый ведомый сервер Postgres Pro с каталогом данных /replica-pga, запустив catchup в режиме FULL в четыре параллельных потока:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=FULL --remote-host=remote-hostname --remote-user=remote-unix-username -j 4

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

Команды #

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

version #

pg_probackup version [--format=json]

Выводит версию и редакцию pg_probackup, а также версию и редакцию сервера Postgres Pro.

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

pg_probackup version --format=json
{
"pg_probackup":
{
"version": "2.8.2",
"edition": "community"
},
"database":
{
"type": "Postgres Pro Standard",
"version": "16.3.1"
},
"compressions": [zlib, pglz, lz4, zstd]
}

help #

pg_probackup help [команда]

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

init #

pg_probackup init -B каталог_копий [--skip-if-exists] [--help]
[параметры_журнала]

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

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

add-instance #

pg_probackup add-instance -B каталог_копий -D каталог_данных --instance=имя_экземпляра
[--skip-if-exists] [--help] [--wal-tree] [параметры_журнала]

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

--skip-if-exists

Позволяет пропустить инициализацию без вызова ошибки, если экземпляр уже существует.

--wal-tree

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

За подробной информацией о команде add-instance обратитесь к подразделу Определение копируемого экземпляра.

del-instance #

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

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

set-config #

pg_probackup set-config -B каталог_копий --instance=имя_экземпляра
[--help] [--pgdata=путь_к_pgdata]
[--retention-redundancy=избыточность][--retention-window=окно][--wal-depth=глубина_wal]
[--compress-algorithm=алгоритм_сжатия] [--compress-level=уровень_сжатия]
[-d имя_базы] [-h сервер] [-p порт] [-U имя_пользователя]
[--archive-timeout=тайм-аут] [--external-dirs=путь_внешнего_каталога]
[--restore-command=команда]
[параметры_удалённого_режима] [параметры_удалённого_архива_wal] [параметры_журнала]

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

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

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

set-backup #

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

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

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

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

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

show-config #

pg_probackup show-config -B каталог_копий --instance имя_экземпляра [--format=plain|json]
[--default-units][параметры_журнала]

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

Также можно добавить параметр --no-scale-units, чтобы выводить значения конфигурационных параметров времени и объёма памяти в единицах измерения по умолчанию. В противном случае эти значения преобразуются в более крупные единицы для более удобного отображения. Например, значение параметра archive-timeout 300 будет выводиться как 5min, а значение archive-timeout 301 — как 301s. Кроме того, с указанием --no-scale-units параметры конфигурации выводятся без единиц измерения, а значения формата JSON, а также числовые и логические значения не заключаются в кавычки, что упрощает разбор.

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

show #

pg_probackup show -B каталог_копий
[--help] [--instance=имя_экземпляра [-i ид_резервной_копии | --archive]] [--format=plain|json] [--no-color] [--show-symlinks]
[параметры_журнала]

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

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

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

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

backup #

pg_probackup backup -B каталог_копий -b режим_копирования --instance=имя_экземпляра
[--help] [-j число_потоков] [--progress]
[--backup-threads число_потоков] [--validate-threads число_потоков]
[-C] [--stream [-S slot_name] [--temp-slot[=true|false|on|off]]] [--backup-pg-log]
[--no-validate] [--skip-block-validation]
[-w --no-password] [-W --password] [--allow-group-access]
[--write-rate-limit=скорость_записи]
[--archive-timeout=тайм-аут] [--external-dirs=путь_внешнего_каталога]
[--no-sync] [--note=заметка_к_копии]
[параметры_подключения] [параметры_сжатия] [параметры_удалённого_режима]
[параметры_хранения] [параметры_закрепления] [параметры_журнала]

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

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

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

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

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

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

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

-C
--smooth-checkpoint

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

--stream

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

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

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

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

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

--backup-pg-log

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

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

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

--allow-group-access

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

--write-rate-limit=скорость_записи

Задаёт скорость записи данных на диск (в мегабайтах/гигабайтах в секунду). По умолчанию указывается в мегабайтах в секунду. Например: --write-rate-limit=1GBps или --write-rate-limit=100 (мегабайты в секунду). Значение по умолчанию: 0 (без ограничений).

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

  • written — объём записанных данных, в МБ.

  • total time — время между первой и последней записью (в секундах). Обратите внимание, что это не общее время создания резервной копии.

  • sleep time — время принудительной задержки, в секундах.

  • average rate — фактическая средняя скорость записи, в мегабайтах в секунду.

Например:

INFO: Rate limit: written 14975.445 MB, total time 17.163 s, sleep time 2.370 s, average rate 872.560715 MBps
--archive-timeout=время_ожидания

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

Примечание

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

--skip-block-validation

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

--no-validate

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

--no-sync

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

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

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

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

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

restore #

pg_probackup restore -B каталог_копий --instance=имя_экземпляра
[--help] [--dry-run] [-D каталог_данных] [-i ид_резервной_копии]
[-j число_потоков] [--progress]
[-T СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ] [--external-mapping=СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ] [--skip-external-dirs]
[-R | --restore-as-replica] [--no-validate] [--skip-block-validation]
[--force] [--no-sync] [--allow-group-access]
[--restore-command=команда]
[--primary-conninfo=строка_подключения]
[-S | --primary-slot-name=имя_слота]
[-X каталог_wal | --waldir=каталог_wal]
[параметры_точки_восстановления] [параметры_журнала] [параметры_удалённого_режима]
[параметры_частичного_восстановления] [параметры_удалённого_архива_wal]

Восстанавливает экземпляр Postgres Pro из резервной копии, расположенной в каталоге каталог_копий. Если вы укажете один или несколько параметров точки восстановления, pg_probackup найдёт ближайшую к этой точке копию и выполнит восстановление до заданной точки. Если ни идентификатор копии, ни параметры точки восстановления не задаются, pg_probackup выполняет восстановление, используя самую последнюю копию.

-R
--restore-as-replica

Создаёт минимальный файл конфигурации восстановления для облегчения настройки ведомого сервера. Если для соединения репликации требуется пароль, его нужно дополнительно задать вручную в primary_conninfo. Для Postgres Pro версии 11 и ниже параметры восстановления сохраняются в каталоге данных в файле recovery.conf, но для версий Postgres Pro, начиная с 12, pg_probackup сохраняет эти параметры в файле probackup_recovery.conf.

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

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

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

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

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

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

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

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

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

--skip-external-dirs

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

--skip-block-validation

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

--no-validate

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

--allow-group-access

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

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

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

--force

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

--no-sync

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

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

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

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

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

checkdb #

pg_probackup checkdb
[-B каталог_копий] [--instance=имя_экземпляра] [-D каталог_данных]
[--help] [-j число_потоков] [--progress]
[--amcheck [--skip-block-validation] [--checkunique] [--heapallindexed]]
[параметры_соединения] [параметры_журнала]

Проверяет целостность кластера баз данных Postgres Pro, выявляя физические и логические повреждения.

--amcheck

Производит логическую проверку индексов для указанного экземпляра Postgres Pro, если не были выявлены повреждения при проверке файлов данных. Для проверки индексов в базе данных в ней должно быть установлено расширение amcheck или amcheck_next. В базах данных, где amcheck отсутствует, индексы проверяться не будут. Дополнительные параметры --checkunique и --heapallindexed действуют в зависимости от установленной версии amcheck.

--checkunique

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

Эта проверка возможна, только если в используемой вами версии расширения amcheck функция bt_index_check принимает параметр checkunique.

--heapallindexed

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

Эта проверка возможна, только если в используемой вами версии расширения amcheck/amcheck_next функция bt_index_check принимает параметр heapallindexed.

--skip-block-validation

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

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

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

validate #

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

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

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

merge #

pg_probackup merge -B каталог_копий --instance=имя_экземпляра -i ид_резервной_копии
[--dry-run] [--help] [-j число_потоков] [--progress] [--no-validate] [--no-sync]
[параметры_журнала]

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

--no-validate

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

--no-sync

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

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

delete #

pg_probackup delete -B каталог_копий --instance=имя_экземпляра
[--help] [-j число_потоков] [--progress]
[--retention-redundancy=избыточность][--retention-window=окно][--wal-depth=глубина_wal] [--delete-wal]
{-i ид_резервной_копии | --delete-expired [--merge-expired] | --merge-expired | --status=состояние}
[--dry-run] [--no-validate] [--no-sync] [параметры_журнала]

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

--no-validate

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

--no-sync

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

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

archive-push #

pg_probackup archive-push -B каталог_копий --instance=имя_экземпляра
--wal-file-name=имя_файла_wal [--wal-file-path=путь_файлов_wal]
[--help] [--dry-run] [--no-sync] [--compress] [--no-ready-rename] [--overwrite]
[-j число_потоков] [--batch-size=размер_пакета]
[--archive-timeout=тайм-аут]
[--compress-algorithm=алгоритм_сжатия]
[--compress-level=уровень_сжатия]
[параметры_удалённого_режима] [параметры_журнала]

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

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

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

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

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

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

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

archive-get #

pg_probackup archive-get -B каталог_копий --instance=имя_экземпляра --wal-file-path=путь_файлов_wal --wal-file-name=имя_файла_wal
[-j число_потоков] [--batch-size=размер_пакета]
[--prefetch-dir=каталог_предвыборки] [--no-validate-wal]
[--dry-run] [--help] [параметры_удалённого_режима] [параметры_журнала]

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

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

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

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

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

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

pg_probackup 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, чтобы пакеты сегментов копировались в несколько потоков.

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

catchup #

pg_probackup catchup -b режим_синхронизации
--source-pgdata=путь_к_копируемому_каталогу_данных
--destination-pgdata=путь_к_целевому_каталогу_данных
[--help] [-j | --threads=число_потоков] [--dry-run]
[--write-rate-limit=скорость_записи]
[--stream[--temp-slot[=true|false|on|off]] [-P | --perm-slot] [-S | --slot=имя_слота]
[--exclude-path=ПУТЬ]
[-T СТАРЫЙ_КАТАЛОГ=НОВЫЙ_КАТАЛОГ]
[-X | --waldir=каталог_wal]
[параметры_подключения] [параметры_удалённого_режима]
[параметры_журнала]

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

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

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

--source-pgdata=путь_к_копируемому_каталогу_данных

Задаёт путь к каталогу данных копируемого экземпляра. Каталог может находиться как локально, так и удалённо.

--destination-pgdata=путь_к_целевому_каталогу_данных

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

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

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

--stream

Копирует экземпляр в режиме доставки STREAM, при котором все необходимые файлы WAL передаются с исходного сервера по протоколу репликации. По умолчанию включён для catchup.

--write-rate-limit=скорость_записи

Задаёт скорость записи данных на диск (в мегабайтах/гигабайтах в секунду). По умолчанию указывается в мегабайтах в секунду. Например: --write-rate-limit=1GBps или --write-rate-limit=100 (мегабайты в секунду). Значение по умолчанию: 0 (без ограничений).

Если параметр указан, по завершении команды catchup выводится следующая информация:

  • written — объём записанных данных, в МБ.

  • total time — время между первой и последней записью (в секундах). Обратите внимание, что это не общее время выполнения команды catchup.

  • sleep time — время принудительной задержки, в секундах.

  • average rate — фактическая средняя скорость записи, в мегабайтах в секунду.

Например:

INFO: Rate limit: written 14975.445 MB, total time 17.163 s, sleep time 2.370 s, average rate 872.560715 MBps
-x=префикс_пути
--exclude-path=префикс_пути

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

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

Используйте этот параметр с осторожностью, поскольку исключение файлов может привести к неполной синхронизации.

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

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

-P
--perm-slot

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

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

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

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

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

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

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

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

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

maintain #

pg_probackup maintain --B каталог_копий --instance=имя_экземпляра
[-i ид_резервной_копии] --status-sync [--help] [--dry-run]
[--log-level-console=уровень_сообщений] [--log-level-file=уровень_сообщений]
[--log-format-console=формат_журнала] [--log-format-file=формат_журнала]
[--log-filename=файл_журнала]

Выполняет очистку каталога с резервными копиями указанного экземпляра после принудительного прерывания предыдущих команд pg_probackup.

--status-sync

Отслеживает устаревшие блокировки и зависшие резервные копии, а также обновляет состояния резервных копий.

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

Параметры #

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

За подробностями обратитесь к Подразделу «Настройка pg_probackup».

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

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

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

--dry-run

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

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

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

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

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

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

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

--instance имя_экземпляра

Указывает имя экземпляра Postgres Pro.

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

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

--progress

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

--help

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

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

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

--recovery-target=immediate|latest

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

  • Со значением immediate восстановление завершается сразу после достижения согласованного состояния выбранной копии, либо последней копии из имеющихся, если параметр -i/--backup-id опущен. Такое поведение по умолчанию применяется для копий типа STREAM.

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

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

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

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

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

  • Числовое значение.

--recovery-target-lsn=lsn

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

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

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

--recovery-target-time=время

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

Например: --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

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

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

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

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

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

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

--retention-window=окно

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

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

--wal-depth=глубина_wal

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

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

--delete-wal

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

--delete-expired

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

--merge-expired

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

--dry-run

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

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

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

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

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

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

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

--expire-time=время

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

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

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

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

--no-color

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

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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Максимальный размер отдельного файла журнала. Если это значение достигается, файл журнала прокручивается при выполнении какой-либо команды pg_probackup, за исключением help и version. Нулевое значение отключает прокрутку в зависимости от размера. Поддерживаются следующие единицы: kB (по умолчанию), MB, GB, TB.

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

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

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

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

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

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

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

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

Задаёт имя базы данных для подключения. Это подключение используется только для управления процессом резервного копирования, так что вы можете подключиться к любой существующей базе. Если этот параметр не задаётся в командной строке, переменной окружения PGDATABASE или в конфигурационном файле pg_probackup.conf, pg_probackup принимает в качестве имени базы значение переменной окружения 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, pglz и none. Любое значение, отличное от none, включает сжатие. При этом сжимаются и файлы данных, и файлы WAL. По умолчанию сжатие отключено. Для команды archive-push алгоритм сжатия pglz не поддерживается.

Примечание

Программа pg_probackup поддерживает алгоритмы сжатия, включённые в конкретную версию Postgres Pro. В частности:

  • lz4 поддерживается для Postgres Pro версии 14 и выше.

  • zstd поддерживается для Postgres Pro версии 15 и выше.

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

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

Определяет уровень сжатия. Этот параметр можно использовать вместе с параметром --compress-algorithm. Возможные значения зависят от указанного алгоритма сжатия:

  • 0 — 9 для zlib

  • 1 для pglz

  • 0 — 12 для lz4

  • -131072 — 22 для zstd

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

Примечание

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

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

--compress

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

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

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

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

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

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

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

Примечание

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

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

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

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

--no-ready-rename

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

--no-sync

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

--prefetch-dir=путь

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

--no-validate-wal

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

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

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

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

--remote-proto=протокол

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

  • ssh — включает удалённый режим с использованием SSH. Этот вариант используется по умолчанию.

  • none — явным образом отключает удалённый режим.

Этот параметр можно не задавать, если указывается --remote-host.

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

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

--remote-port=порт

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

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

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

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

--remote-path=путь

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

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

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

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

В этом подразделе описываются параметры, позволяющие задать аргументы archive-get для использования удалённого режима в команде restore_command при восстановлении PITR или восстановлении копий типа ARCHIVE.

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

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

--archive-port=порт

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

PGPROBACKUP_TESTS_SKIP_HIDDEN

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

--destroy-all-other-dbs

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

Важно

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

--lock-lifetime

Задаёт время жизни блокировок, устанавливаемых при копировании, в секундах. Значение по умолчанию — 300. Минимальное значение — 60.

PGPROBACKUP_TESTS_SKIP_EMPTY_COMMIT

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

Версионирование #

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

Авторы #

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

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

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

pg_probackup

pg_probackup — manage backup and recovery of Postgres Pro database clusters

Synopsis

pg_probackup version

pg_probackup help [command]

pg_probackup init -B backup_dir --skip-if-exists

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

pg_probackup del-instance -B backup_dir --instance instance_name

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

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

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

pg_probackup show -B backup_dir [option...]

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

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

pg_probackup checkdb -B backup_dir --instance instance_name -D data_dir [option...]

pg_probackup validate -B backup_dir [option...]

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

pg_probackup delete -B backup_dir --instance instance_name { -i backup_id | --delete-wal | --delete-expired | --merge-expired } [option...]

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

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

pg_probackup catchup -b catchup_mode --source-pgdata=path_to_pgdata_on_remote_server --destination-pgdata=path_to_local_dir [option...]

pg_probackup maintain -B backup_dir --instance instance_name [--backup-id backup_id] --status-sync [option...]

Description #

pg_probackup is a utility to manage backup and recovery of Postgres Pro database clusters. It is designed to perform periodic backups of the Postgres Pro instance that enable you to restore the server in case of a failure. pg_probackup supports PostgreSQL 11 or higher.

Overview #

As compared to other backup solutions, pg_probackup offers the following benefits that can help you implement different backup strategies and deal with large amounts of data:

  • Incremental backup: with three different incremental modes, you can plan the backup strategy in accordance with your data flow. Incremental backups allow you to save disk space and speed up backup as compared to taking full backups. It is also faster to restore the cluster by applying incremental backups than by replaying WAL files.

  • Incremental restore: speed up restore from a backup by reusing valid unchanged pages available in PGDATA.

  • Validation: automatic data consistency checks and on-demand backup validation without actual data recovery.

  • Verification: on-demand verification of Postgres Pro instance with the checkdb command.

  • Retention: managing WAL archive and backups in accordance with retention policy. You can configure retention policy based on recovery time or the number of backups to keep, as well as specify time to live (TTL) for a particular backup. Expired backups can be merged or deleted.

  • Parallelization: running backup, restore, merge, delete, validate, and checkdb processes on multiple parallel threads.

  • Compression: storing backup data in a compressed state to save disk space.

  • Deduplication: saving disk space by excluding non-data files (such as _vm or _fsm) from incremental backups if these files have not changed since they were copied into one of the previous backups in this incremental chain.

  • Remote operations: backing up Postgres Pro instance located on a remote system or restoring a backup remotely.

  • Backups from a standby: avoiding extra load on the primary by taking backups from a standby server.

  • External directories: backing up files and directories located outside of the Postgres Pro data directory (PGDATA), such as scripts, configuration files, logs, or SQL dump files.

  • Backup catalog: getting the list of backups and the corresponding meta information in plain text or JSON formats.

  • Archive catalog: getting the list of all WAL timelines and the corresponding meta information in plain text or JSON formats.

  • Partial restore: restoring only the specified databases.

  • Catchup: cloning a Postgres Pro instance for a fallen-behind standby server to “catch up” with the primary.

To manage backup data, pg_probackup creates a backup catalog. This is a directory that stores all backup files with additional meta information, as well as WAL archives required for point-in-time recovery. You can store backups for different instances in separate subdirectories of a single backup catalog.

Using pg_probackup, you can take full or incremental backups:

  • FULL backups contain all the data files required to restore the database cluster.

  • Incremental backups operate at the page level, only storing the data that has changed since the previous backup. It allows you to save disk space and speed up the backup process as compared to taking full backups. It is also faster to restore the cluster by applying incremental backups than by replaying WAL files. pg_probackup supports the following modes of incremental backups:

    • DELTA backup. In this mode, pg_probackup reads all data files in the data directory and copies only those pages that have changed since the previous backup. This mode can impose read-only I/O pressure equal to a full backup.

    • PAGE backup. In this mode, pg_probackup scans all WAL files in the archive from the moment the previous full or incremental backup was taken. Newly created backups contain only the pages that were mentioned in WAL records. This requires all the WAL files since the previous backup to be present in the WAL archive. If the size of these files is comparable to the total size of the database cluster files, speedup is smaller, but the backup still takes less space. You have to configure WAL archiving as explained in Setting up continuous WAL archiving to make PAGE backups.

    • PTRACK backup. In this mode, Postgres Pro tracks page changes on the fly. Continuous archiving is not necessary for it to operate. Each time a relation page is updated, this page is marked in a special PTRACK bitmap. Tracking implies some minor overhead on the database server operation, but speeds up incremental backups significantly.

Warning

After promoting a standby server to primary and switching timelines, take the first backup in either FULL or DELTA mode. Using other backup modes in this case may result in data corruption.

pg_probackup can take only physical online backups, and online backups require WAL for consistent recovery. So regardless of the chosen backup mode (FULL, PAGE or DELTA), any backup taken with pg_probackup must use one of the following WAL delivery modes:

  • ARCHIVE. Such backups rely on continuous archiving to ensure consistent recovery. This is the default WAL delivery mode.

  • STREAM. Such backups include all the files required to restore the cluster to a consistent state at the time the backup was taken. Regardless of continuous archiving having been set up or not, the WAL segments required for consistent recovery are streamed via replication protocol during backup and included into the backup files. That's why such backups are called autonomous, or standalone.

Limitations #

pg_probackup currently has the following limitations:

  • The remote mode is not supported on Windows systems.

  • On Unix systems, for Postgres Pro, a backup can be made only by the same OS user that has started the Postgres Pro server. For example, if Postgres Pro server is started by user postgres, the backup command must also be run by user postgres. To satisfy this requirement when taking backups in the remote mode using SSH, you must set --remote-user option to postgres.

  • The Postgres Pro server from which the backup was taken and the restored server must be compatible by the block_size and wal_block_size parameters and have the same major release number. Depending on cluster configuration, Postgres Pro itself may apply additional restrictions, such as CPU architecture or libc/icu versions.

Quick Start #

To quickly get started with pg_probackup, complete the steps below. This will set up FULL and DELTA backups in the remote mode and demonstrate some basic pg_probackup operations. In the following, these terms are used:

  • backup — Postgres Pro role used to connect to the Postgres Pro cluster.

  • backupdb — database used to connect to the Postgres Pro cluster.

  • backup_host — host with the backup catalog.

  • backup_user — user on backup_host running all pg_probackup operations.

  • /mnt/backups — directory on backup_host where the backup catalog is stored.

  • postgres_host — host with the Postgres Pro cluster.

  • postgres — user on postgres_host under which Postgres Pro cluster processes are running.

  • /var/lib/pgpro/std-16/data — Postgres Pro data directory on postgres_host.

Steps to perform: #

  1. Install pg_probackup on both backup_host and postgres_host.

  2. Set up an SSH connection from backup_host to postgres_host.

  3. Configure your database cluster for STREAM backups.

  4. Initialize the backup catalog:

    backup_user@backup_host:~$ pg_probackup init -B /mnt/backups
    INFO: Backup catalog '/mnt/backups' successfully initialized
    
  5. Add a backup instance called mydb to the backup catalog:

    backup_user@backup_host:~$ pg_probackup add-instance \
        -B /mnt/backups \
        -D /var/lib/pgpro/std-16/data \
        --instance=node \
        --remote-host=postgres_host \
        --remote-user=postgres
    INFO: Instance 'node' successfully initialized
    
  6. Make a FULL backup:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b FULL \
        --instance=node \
        --stream \
        --compress-algorithm=zstd \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6J, backup mode: FULL, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/8000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 2s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/9000000 currentpos 0/9000000
    INFO: backup->stop_lsn 0/8004E40
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 1s
    INFO: Validating backup SBOL6J
    INFO: Backup SBOL6J data files are valid
    INFO: Backup SBOL6J resident size: 53MB
    INFO: Backup SBOL6J completed
    
  7. List the backups of the instance:

    backup_user@backup_host:~$ pg_probackup show \
            -B /mnt/backups \
            --instance=node
    =============================================================================================================================================
     Instance  Version  ID      Recovery Time                  Mode  WAL Mode  TLI  Time  Data   WAL  Zalg  Zratio  Start LSN  Stop LSN   Status 
    =============================================================================================================================================
     node      17       SBOL6J  2024-04-09 18:18:21.970314+03  FULL  STREAM    1/0    4s  37MB  16MB  zstd    2.57  0/8000028  0/8004E40  OK     
    
  8. Make an incremental backup in the DELTA mode:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b DELTA \
        --instance=node \
        --stream \
        --compress-algorithm=zstd \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6N, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: Parent backup: SBOL6J
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/9000028, TLI: 1
    INFO: Parent Start LSN: 0/8000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 1s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/A000000 currentpos 0/A000000
    INFO: backup->stop_lsn 0/9000190
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 0
    INFO: Validating backup SBOL6N
    INFO: Backup SBOL6N data files are valid
    INFO: Backup SBOL6N resident size: 17MB
    INFO: Backup SBOL6N completed
    
  9. Add or modify some parameters in the pg_probackup configuration file, so that you do not have to specify them each time on the command line:

    backup_user@backup_host:~$ pg_probackup set-config \
        -B /mnt/backups \
        --instance=node \
        --remote-host=postgres_host \
        --remote-user=postgres \
        -U backup \
        -d backupdb
    
  10. Check the configuration of the instance:

    backup_user@backup_host:~$ pg_probackup show-config \
        -B /mnt/backups \
        --instance=node
    # Backup instance information
    pgdata = /var/lib/pgpro/std-16/data
    system-identifier = 7355886958826772732
    xlog-seg-size = 16777216
    # Connection parameters
    pgdatabase = backupdb
    pghost = postgres_host
    pguser = backup
    # Archive parameters
    archive-timeout = 5min
    # Logging parameters
    log-level-console = INFO
    log-level-file = OFF
    log-format-console = PLAIN
    log-format-file = PLAIN
    log-filename = pg_probackup.log
    log-rotation-size = 0TB
    log-rotation-age = 0d
    # Retention parameters
    retention-redundancy = 0
    retention-window = 0
    wal-depth = 0
    # Compression parameters
    compress-algorithm = none
    compress-level = 1
    # Remote access parameters
    remote-proto = ssh
    remote-host = postgres_host
    remote-user = postgres
    

    Note that the parameters not modified via set-config retain their default values.

  11. Make another incremental backup in the DELTA mode, omitting the parameters stored in the configuration file earlier:

    backup_user@backup_host:~$ pg_probackup backup \
        -B /mnt/backups \
        -b DELTA \
        --instance=node \
        --stream \
        --compress-algorithm=zstd
    INFO: Backup start, pg_probackup version: 2.7.3, instance: node, backup ID: SBOL6P, backup mode: DELTA, wal mode: STREAM, remote: true, compress-algorithm: zstd, compress-level: 1
    WARNING:  pgpro_edition() function is old-style and will be removed in future major release, use pgpro_edition GUC variable instead.
    INFO: This PostgreSQL instance was initialized with data block checksums. Data block corruption will be detected
    INFO: Database backup start
    INFO: wait for pg_backup_start()
    INFO: Parent backup: SBOL6N
    INFO: PGDATA size: 96MB
    INFO: Current Start LSN: 0/A000028, TLI: 1
    INFO: Parent Start LSN: 0/9000028, TLI: 1
    INFO: Start transferring data files
    INFO: Data files are transferred, time elapsed: 1s
    INFO: wait for pg_stop_backup()
    INFO: pg_stop_backup() successfully executed
    INFO: stop_stream_lsn 0/B000000 currentpos 0/B000000
    INFO: backup->stop_lsn 0/A000190
    INFO: Getting the Recovery Time from WAL
    INFO: Syncing backup files to disk
    INFO: Backup files are synced, time elapsed: 0
    INFO: Validating backup SBOL6P
    INFO: Backup SBOL6P data files are valid
    INFO: Backup SBOL6P resident size: 17MB
    INFO: Backup SBOL6P completed
    
  12. List the backups of the instance again:

    backup_user@backup_host:~$ pg_probackup show \
        -B /mnt/backups \
        --instance=node
    ================================================================================================================================================
     Instance  Version  ID      Recovery Time                  Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN  Stop LSN   Status 
    ================================================================================================================================================
     node      17       SBOL6P  2024-04-09 18:18:26.630175+03  DELTA  STREAM    1/1    1s  1147kB  16MB  zstd    1.00  0/A000028  0/A000190  OK     
     node      17       SBOL6N  2024-04-09 18:18:25.015713+03  DELTA  STREAM    1/1    2s  1160kB  16MB  zstd    1.04  0/9000028  0/9000190  OK     
     node      17       SBOL6J  2024-04-09 18:18:21.970314+03  FULL   STREAM    1/0    4s    37MB  16MB  zstd    2.57  0/8000028  0/8004E40  OK     
    
  13. Restore the data from the latest available backup to an arbitrary location:

    backup_user@backup_host:~$ pg_probackup restore \
        -B /mnt/backups \
        -D /var/lib/pgpro/std-16/staging-data \
        --instance=node
    INFO: Validating parents for backup SBOL6P
    INFO: Validating backup SBOL6J
    INFO: Backup SBOL6J data files are valid
    INFO: Validating backup SBOL6N
    INFO: Backup SBOL6N data files are valid
    INFO: Validating backup SBOL6P
    INFO: Backup SBOL6P data files are valid
    INFO: Backup SBOL6P WAL segments are valid
    INFO: Backup SBOL6P is valid.
    INFO: Restoring the database from the backup starting at 2024-04-09 18:18:25+03 on localhost
    INFO: Start restoring backup files. PGDATA size: 112MB
    INFO: Backup files are restored. Transferred bytes: 112MB, time elapsed: 2s
    INFO: Restore incremental ratio (less is better): 100% (112MB/112MB)
    INFO: Syncing restored files to disk
    INFO: Restored backup files are synced, time elapsed: 1s
    INFO: Restore of backup SBOL6P completed.
    

Installation and Setup #

Once you have pg_probackup installed, complete the following setup:

  • Initialize the backup catalog.

  • Add a new backup instance to the backup catalog.

  • Configure the database cluster to enable pg_probackup backups.

  • Optionally, configure SSH for running pg_probackup operations in the remote mode.

Initializing the Backup Catalog #

pg_probackup stores all WAL and backup files in the corresponding subdirectories of the backup catalog.

To initialize the backup catalog, run the following command:

pg_probackup init -B backup_dir

where backup_dir is the path to the backup catalog. If the backup_dir already exists, it must be empty. Otherwise, pg_probackup returns an error.

The user launching pg_probackup must have full access to the backup_dir directory.

pg_probackup creates the backup_dir backup catalog, with the following subdirectories:

  • wal/ — directory for WAL files.

  • backups/ — directory for backup files.

Once the backup catalog is initialized, you can add a new backup instance.

Adding a New Backup Instance #

pg_probackup can store backups for multiple database clusters in a single backup catalog. To set up the required subdirectories, you must add a backup instance to the backup catalog for each database cluster you are going to back up.

To add a new backup instance, run the following command:

pg_probackup add-instance -B backup_dir -D data_dir --instance=instance_name [remote_options]

Where:

  • data_dir is the data directory of the cluster you are going to back up. To set up and use pg_probackup, write access to this directory is required.

  • instance_name is the name of the subdirectories that will store WAL and backup files for this cluster.

  • remote_options are optional parameters that need to be specified only if data_dir is located on a remote system.

pg_probackup creates the instance_name subdirectories under the backups/ and wal/ directories of the backup catalog. The backups/instance_name directory contains the pg_probackup.conf configuration file that controls pg_probackup settings for this backup instance. If you run this command with the remote_options, the specified parameters will be added to pg_probackup.conf.

For details on how to fine-tune pg_probackup configuration, see the section called “Configuring pg_probackup”.

The user launching pg_probackup must have full access to backup_dir directory and at least read-only access to data_dir directory. If you specify the path to the backup catalog in the BACKUP_PATH environment variable, you can omit the corresponding option when running pg_probackup commands.

Note

For Postgres Pro 11 or higher, it is recommended to use the -g feature, so that backups can be done by any OS user in the same group as the cluster owner. In this case, the user should have read permissions for the cluster directory.

Configuring the Database Cluster #

Although pg_probackup can be used by a superuser, it is recommended to create a separate role with the minimum permissions required for the chosen backup strategy. In these configuration instructions, the backup role is used as an example.

For security reasons, it is recommended to run the configuration SQL queries below in a separate database.

postgres=# CREATE DATABASE backupdb;
postgres=# \c backupdb

To perform a backup, the following permissions for role backup are required only in the database used for connection to the Postgres Pro server.

For Postgres Pro versions 11 — 14:

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_stop_backup(boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;

For Postgres Pro 15 or higher:

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.current_setting(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.set_config(text, text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_is_in_recovery() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_start(text, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_backup_stop(boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_create_restore_point(text) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_switch_wal() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_last_wal_replay_lsn() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_current_snapshot() TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.txid_snapshot_xmax(txid_snapshot) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.pg_control_checkpoint() TO backup;
COMMIT;

In the pg_hba.conf file, allow connection to the database cluster on behalf of the backup role.

Since pg_probackup needs to read cluster files directly, pg_probackup must be started by (or connected to, if used in the remote mode) the OS user that has read access to all files and directories inside the data directory (PGDATA) you are going to back up.

Depending on whether you plan to take standalone or archive backups, Postgres Pro cluster configuration will differ, as specified in the sections below. To back up the database cluster from a standby server, run pg_probackup in the remote mode, or create PTRACK backups, additional setup is required.

For details, see the sections Setting up STREAM Backups, Setting up continuous WAL archiving, Setting up Backup from Standby, Configuring the Remote Mode, Setting up Partial Restore, and Setting up PTRACK Backups.

Setting up STREAM Backups #

To set up the cluster for STREAM backups, complete the following steps:

  • If the backup role does not exist, create it with the REPLICATION privilege when Configuring the Database Cluster:

    CREATE ROLE backup WITH LOGIN REPLICATION;
    
  • If the backup role already exists, grant it with the REPLICATION privilege:

    ALTER ROLE backup WITH REPLICATION;
    
  • In the pg_hba.conf file, allow replication on behalf of the backup role.

  • Make sure the parameter max_wal_senders is set high enough to leave at least one session available for the backup process.

  • Set the parameter wal_level to be higher than minimal.

If you are planning to take PAGE backups in the STREAM mode or perform PITR with STREAM backups, you still have to configure WAL archiving, as explained in the section Setting up continuous WAL archiving.

Once these steps are complete, you can start taking FULL, PAGE, DELTA, and PTRACK backups in the STREAM WAL mode.

Note

If you are planning to rely on .pgpass for authentication when running backup in STREAM mode, then .pgpass must contain credentials for replication database, used to establish connection via replication protocol. Example: pghost:5432:replication:backup_user:my_strong_password

Setting up Continuous WAL Archiving #

Making backups in the PAGE backup mode, performing PITR and making backups with the ARCHIVE WAL delivery mode require continuous WAL archiving to be enabled. To set up continuous archiving in the cluster, complete the following steps:

  • Make sure the wal_level parameter is higher than minimal.

  • If you are configuring archiving on the primary, archive_mode must be set to on or always. To perform archiving on a standby, set this parameter to always.

  • Set the archive_command parameter, as follows:

    archive_command = '"install_dir/pg_probackup" archive-push -B "backup_dir" --instance=instance_name --wal-file-name=%f [remote_options]'
    

where install_dir is the installation directory of the pg_probackup version you are going to use, backup_dir and instance_name refer to the already initialized backup catalog instance for this database cluster, and remote_options only need to be specified to archive WAL on a remote host. For details about all possible archive-push parameters, see the section archive-push.

The --wal-file-path option provides the path to the WAL file used by the archive-push command. 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. When invoked via archive_command, Postgres Pro sets the current working directory to PGDATA, so relative paths like pg_wal/... work correctly:

archive_command = 'pg_probackup archive-push -B /backup --instance=main --wal-file-path=%p --wal-file-name=%f'

If --wal-file-path is omitted, pg_wal relative to the current working directory is used:

archive_command = 'pg_probackup archive-push -B /backup --instance=main --wal-file-name=%f'

Note

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

Before starting the Postgres Pro server, you can verify that WAL is correctly sent to the archive by running the archive-push command manually from PGDATA:

cd /var/lib/pgsql/data
pg_probackup archive-push -B /backup --instance=main --wal-file-path=pg_wal/000000010000000000000001 --wal-file-name=000000010000000000000001

Once these steps are complete, you can start making backups in the ARCHIVE WAL mode, backups in the PAGE backup mode, as well as perform PITR.

You can view the current state of the WAL archive using the show command. For details, see the section called “Viewing WAL Archive Information”.

If you are planning to make PAGE backups and/or backups with ARCHIVE WAL mode from a standby server that generates a small amount of WAL traffic, without long waiting for WAL segment to fill up, consider setting the archive_timeout Postgres Pro parameter on the primary. The value of this parameter should be slightly lower than the --archive-timeout setting (5 minutes by default), so that there is enough time for the rotated segment to be streamed to a standby and sent to WAL archive before the backup is aborted because of --archive-timeout.

Note

Instead of using the archive-push command provided by pg_probackup, you can use any other tool to set up continuous archiving as long as it delivers WAL segments into backup_dir/wal/instance_name directory. If compression is used, it should be gzip, and .gz suffix in filename is mandatory.

Note

Instead of configuring continuous archiving by setting the archive_mode and archive_command parameters, you can opt for using the pg_receivewal utility. In this case, pg_receivewal -D directory option should point to backup_dir/wal/instance_name directory. pg_probackup supports WAL compression that can be done by pg_receivewal. “Zero Data Loss” archive strategy can be achieved only by using pg_receivewal.

Setting up Backups from a Standby #

pg_probackup can take backups from a standby server. This requires the following additional setup:

Once these steps are complete, you can start taking FULL, PAGE, DELTA, or PTRACK backups with appropriate WAL delivery mode: ARCHIVE or STREAM, from the standby server.

Backups from a standby server have the following limitations:

  • If a standby is promoted to a primary during the backup process, the backup fails.

  • All WAL records required for the backup must contain sufficient full-page writes. This requires you to enable full_page_writes on the primary, and not to use tools like pg_compresslog as archive_command to remove full-page writes from WAL files.

Setting up Cluster Verification #

Logical verification of a database cluster requires the following additional setup. Role backup is used as an example:

  • Install the amcheck or amcheck_next extension in every database of the cluster:

    CREATE EXTENSION amcheck;
    
  • Grant the following permissions to the backup role in every database of the cluster:

GRANT SELECT ON TABLE pg_catalog.pg_am TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_class TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_namespace TO backup;
GRANT SELECT ON TABLE pg_catalog.pg_extension TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool) TO backup;
GRANT EXECUTE ON FUNCTION bt_index_check(regclass, bool, bool) TO backup;

Setting up Partial Restore #

If you are planning to use partial restore, complete the following additional step:

  • Grant the read-only access to pg_catalog.pg_database to the backup role only in the database used for connection to Postgres Pro server:

    GRANT SELECT ON TABLE pg_catalog.pg_database TO backup;
    

Configuring the Remote Mode #

pg_probackup supports the remote mode that allows you to perform backup, restore and WAL archiving operations remotely. In this mode, the backup catalog is stored on a local system, while Postgres Pro instance to backup and/or to restore is located on a remote system. Currently the only supported remote protocol is SSH.

Set up SSH #

If you are going to use pg_probackup in remote mode via SSH, complete the following steps:

  1. Install pg_probackup on both systems: backup_host and postgres_host.

  2. For communication between the hosts set up a passwordless SSH connection between the backup_user user on backup_host and the postgres user on postgres_host:

    backup_user@backup_host:~$ ssh-copy-id postgres@postgres_host
    

    Where:

    • backup_host is the system with backup catalog.

    • postgres_host is the system with the Postgres Pro cluster.

    • backup_user is the OS user on backup_host used to run pg_probackup.

    • postgres is the user on postgres_host under which Postgres Pro cluster processes are running. For Postgres Pro 11 or higher a more secure approach can be used thanks to -g feature.

  3. If you are going to rely on continuous WAL archiving, set up a passwordless SSH connection between the postgres user on postgres_host and the backup user on backup_host:

    postgres@postgres_host:~$ ssh-copy-id backup_user@backup_host
    
  4. Make sure pg_probackup on postgres_host can be located when a connection via SSH is made. For example, for Bash, you can modify PATH in ~/.bashrc of the postgres user (above the line in bashrc that exits the script for non-interactive shells). Alternatively, for pg_probackup commands, specify the path to the directory containing the pg_probackup binary on postgres_host via the --remote-path option.

pg_probackup in the remote mode via SSH works as follows:

  • Only the following commands can be launched in the remote mode: add-instance, backup, restore, delete, catchup, archive-push, and archive-get.

  • Operating in remote mode requires pg_probackup binary to be installed on both local and remote systems. The versions of local and remote binary must be the same.

  • When started in the remote mode, the main pg_probackup process on the local system connects to the remote system via SSH and launches one or more agent processes on the remote system, which are called remote agents. The number of remote agents is equal to the -j/--threads setting.

  • The main pg_probackup process uses remote agents to access remote files and transfer data between local and remote systems.

  • Remote agents try to minimize the network traffic and the number of round-trips between hosts.

  • The main process is usually started on backup_host and connects to postgres_host, but in case of archive-push and archive-get commands the main process is started on postgres_host and connects to backup_host.

  • Once data transfer is complete, remote agents are terminated and SSH connections are closed.

  • If an error condition is encountered by a remote agent, then all agents are terminated and error details are reported by the main pg_probackup process, which exits with an error.

  • Compression is always done on postgres_host, while decompression is always done on backup_host.

Note

You can impose additional restrictions on SSH settings to protect the system in the event of account compromise.

Note

Setting the number of threads (-j/--threads option) to a value greater than 10 for pg_probackup working in the remote mode via SSH may result in the actual number of SSH connections exceeding the maximum allowed number of simultaneous SSH connections on the remote server and consequently lead to an “ERROR: Agent error: kex_exchange_identification: Connection closed by remote host” error. To correct the error, either reduce the number of pg_probackup threads or adjust the value of MaxStartups configuration parameter of the remote SSH server. If SSH is set up as a xinetd service on the remote server, adjust the value of the xinetd per_source configuration parameter rather than MaxStartups.

Setting up PTRACK Backups #

Note

PTRACK versions lower than 2.0 are deprecated and not supported. Postgres Pro Standard and Postgres Pro Enterprise versions starting with 11.9.1 contain PTRACK 2.0. Upgrade your server to avoid issues in backups that you will take in future and be sure to take fresh backups of your clusters with the upgraded PTRACK since the backups taken with PTRACK 1.x might be corrupt.

If you are going to use PTRACK backups, complete the following additional steps.

Note

The permissions required for the role that will perform PTRACK backups (the backup role in the examples below) are listed in the section called “Configuring the Database Cluster”. The role must have permissions only in the database used for connection to the Postgres Pro server.

For Postgres Pro 11 or higher:

  1. Create PTRACK extension in the database used for connection to the Postgres Pro server:

    CREATE EXTENSION ptrack;
    

  2. To enable tracking page updates, set ptrack.map_size parameter to a positive integer and restart the server.

    For optimal performance, it is recommended to set ptrack.map_size to N / 1024, where N is the size of the Postgres Pro cluster, in MB. If you set this parameter to a lower value, PTRACK is more likely to map several blocks together, which leads to false-positive results when tracking changed blocks and increases the incremental backup size as unchanged blocks can also be copied into the incremental backup. Setting ptrack.map_size to a higher value does not affect PTRACK operation, but it is not recommended to set this parameter to a value higher than 1024.

Note

If you change the ptrack.map_size parameter value, the previously created PTRACK map file is cleared, and tracking newly changed blocks starts from scratch. Thus, you have to retake a full backup before taking incremental PTRACK backups after changing ptrack.map_size.

Usage #

Creating a Backup #

To create a backup, run the following command:

pg_probackup backup -B backup_dir --instance=instance_name -b backup_mode

Where backup_mode can take one of the following values: FULL, DELTA, PAGE, and PTRACK.

When restoring a cluster from an incremental backup, pg_probackup relies on the parent full backup and all the incremental backups between them, which is called “the backup chain”. Thus, to perform incremental backups, it is necessary to have the last parent full backup with the status OK or DONE in the directory. If the parent full backup has the MERGING or MERGED status, an incremental backup cannot be performed.

For example, if merge has already been launched with a single full backup, an attempt to perform an incremental backup will end with the following messages:

WARNING: Valid full backup on current timeline 1 is not found, trying to look up on previous timelines
WARNING: Cannot find valid backup on previous timelines
ERROR: Create new full backup before an incremental one

ARCHIVE Mode #

ARCHIVE is the default WAL delivery mode.

For example, to make a FULL backup in ARCHIVE mode, run:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL

ARCHIVE backups rely on continuous archiving to get WAL segments required to restore the cluster to a consistent state at the time the backup was taken.

When a backup is taken, pg_probackup ensures that WAL files containing WAL records between Start LSN and Stop LSN actually exist in backup_dir/wal/instance_name directory. pg_probackup also ensures that WAL records between Start LSN and Stop LSN can be parsed. This precaution eliminates the risk of silent WAL corruption.

STREAM Mode #

STREAM is the optional WAL delivery mode.

For example, to make a FULL backup in the STREAM mode, add the --stream flag to the command from the previous example:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL --stream --temp-slot

The optional --temp-slot flag ensures that the required segments remain available if the WAL is rotated before the backup is complete.

Unlike backups in ARCHIVE mode, STREAM backups include all the WAL segments required to restore the cluster to a consistent state at the time the backup was taken.

During backup pg_probackup streams WAL files containing WAL records between Start LSN and Stop LSN to backup_dir/backups/instance_name/backup_id/database/pg_wal directory. To eliminate the risk of silent WAL corruption, pg_probackup also checks that WAL records between Start LSN and Stop LSN can be parsed.

Even if you are using continuous archiving, STREAM backups can still be useful in the following cases:

  • STREAM backups can be restored on the server that has no file access to WAL archive.

  • STREAM backups enable you to restore the cluster state at the point in time for which WAL files in archive are no longer available.

  • Backup in STREAM mode can be taken from a standby of a server that generates small amount of WAL traffic, without long waiting for WAL segment to fill up.

Page Validation #

If data_checksums are enabled in the database cluster, pg_probackup uses this information to check correctness of data files during backup. While reading each page, pg_probackup checks whether the calculated checksum coincides with the checksum stored in the page header. This guarantees that the Postgres Pro instance and the backup itself have no corrupt pages. Note that pg_probackup reads database files directly from the filesystem, so under heavy write load during backup it can show false-positive checksum mismatches because of partial writes. If a page checksum mismatch occurs, the page is re-read and checksum comparison is repeated.

A page is considered corrupt if checksum comparison has failed more than 300 times. In this case, the backup is aborted.

Even if data checksums are not enabled, pg_probackup always performs sanity checks for page headers.

External Directories #

To back up a directory located outside of the data directory, use the optional --external-dirs parameter that specifies the path to this directory. If you would like to add more than one external directory, you can provide several paths separated by colons on Linux systems or semicolons on Windows systems.

For example, to include /etc/dir1 and /etc/dir2 directories into the full backup of your instance_name instance that will be stored under the backup_dir directory on Linux, run:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL --external-dirs=/etc/dir1:/etc/dir2

Similarly, to include C:\dir1 and C:\dir2 directories into the full backup on Windows, run:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL --external-dirs=C:\dir1;C:\dir2

pg_probackup recursively copies the contents of each external directory into a separate subdirectory in the backup catalog. Since external directories included into different backups do not have to be the same, when you are restoring the cluster from an incremental backup, only those directories that belong to this particular backup will be restored. Any external directories stored in the previous backups will be ignored.

To include the same directories into each backup of your instance, you can specify them in the pg_probackup.conf configuration file using the set-config command with the --external-dirs option.

Performing Cluster Verification #

To verify that Postgres Pro database cluster is not corrupt, run the following command:

pg_probackup checkdb [-B backup_dir [--instance=instance_name]] [-D data_dir] [connection_options]

This command performs physical verification of all data files located in the specified data directory by running page header sanity checks, as well as block-level checksum verification if checksums are enabled. If a corrupt page is detected, checkdb continues cluster verification until all pages in the cluster are validated.

By default, similar page validation is performed automatically while a backup is taken by pg_probackup. The checkdb command enables you to perform such page validation on demand, without taking any backup copies, even if the cluster is not backed up using pg_probackup at all.

To perform cluster verification, pg_probackup needs to connect to the cluster to be verified. In general, it is enough to specify the backup instance of this cluster for pg_probackup to determine the required connection options. However, if -B and --instance options are omitted, you have to provide connection options and data_dir via environment variables or command-line options.

Physical verification cannot detect logical inconsistencies, missing or nullified blocks and entire files, or similar anomalies. Extensions amcheck and amcheck_next provide a partial solution to these problems.

If you would like, in addition to physical verification, to verify all indexes in all databases using these extensions, you can specify the --amcheck flag when running the checkdb command:

pg_probackup checkdb -D data_dir --amcheck [connection_options]

You can skip physical verification by specifying the --skip-block-validation flag. In this case, you can omit backup_dir and data_dir options, only connection options are mandatory:

pg_probackup checkdb --amcheck --skip-block-validation [connection_options]

Logical verification can be done more thoroughly with the --heapallindexed flag by checking that all heap tuples that should be indexed are actually indexed, but at the higher cost of CPU, memory, and I/O consumption.

Validating a Backup #

pg_probackup calculates checksums for each file in a backup during the backup process. The process of checking checksums of backup data files is called the backup validation. By default, validation is run immediately after the backup is taken and right before the restore, to detect possible backup corruption.

If you would like to skip backup validation, you can specify the --no-validate flag when running backup and restore commands.

To ensure that all the required backup files are present and can be used to restore the database cluster, you can run the validate command with the exact recovery target options you are going to use for recovery.

For example, to check that you can restore the database cluster from a backup copy up to transaction ID 4242, run this command:

pg_probackup validate -B backup_dir --instance=instance_name --recovery-target-xid=4242

If validation completes successfully, pg_probackup displays the corresponding message. If validation fails, you will receive an error message with the exact time, transaction ID, and LSN up to which the recovery is possible.

If you specify backup_id via -i/--backup-id option, then only the backup copy with specified backup ID will be validated. If backup_id is specified with recovery target options, the validate command will check whether it is possible to restore the specified backup to the specified recovery target.

For example, to check that you can restore the database cluster from a backup copy with the SBOL6P backup ID up to the specified timestamp, run this command:

pg_probackup validate -B backup_dir --instance=instance_name -i SBOL6P --recovery-target-time="2024-04-10 18:18:26+03"

If you specify the backup_id of an incremental backup, all its parents starting from FULL backup will be validated.

If you omit all the parameters, all backups are validated.

Restoring a Cluster #

To restore the database cluster from a backup, run the restore command with at least the following options:

pg_probackup restore -B backup_dir --instance=instance_name -i backup_id

Where:

  • backup_dir is the backup catalog that stores all backup files and meta information.

  • instance_name is the backup instance for the cluster to be restored.

  • backup_id specifies the backup to restore the cluster from. If you omit this option, pg_probackup uses the latest valid backup available for the specified instance. If you specify an incremental backup to restore, pg_probackup automatically restores the underlying full backup and then sequentially applies all the necessary increments.

Once the restore command is complete, start the database service.

If you restore ARCHIVE backups, perform PITR, or specify the --restore-as-replica flag with the restore command to set up a standby server, pg_probackup creates a recovery configuration file once all data files are copied into the target directory. This file includes the minimal settings required for recovery, except for the password in the primary_conninfo parameter; you have to add the password manually or use the --primary-conninfo option, if required. For Postgres Pro 11, recovery settings are written into the recovery.conf file. Starting from Postgres Pro 12, pg_probackup writes these settings into the probackup_recovery.conf file and then includes it into postgresql.auto.conf.

If you are restoring a STREAM backup, the restore is complete at once, with the cluster returned to a self-consistent state at the point when the backup was taken. For ARCHIVE backups, Postgres Pro replays all available archived WAL segments, so the cluster is restored to the latest state possible within the current timeline. You can change this behavior by using the recovery target options with the restore command, as explained in the section called “Performing Point-in-Time (PITR) Recovery”.

If the cluster to restore contains tablespaces, pg_probackup restores them to their original location by default. To restore tablespaces to a different location, use the --tablespace-mapping/-T option. Otherwise, restoring the cluster on the same host will fail if tablespaces are in use, because the backup would have to be written to the same directories.

When using the --tablespace-mapping/-T option, you must provide absolute paths to the old and new tablespace directories. If a path happens to contain an equals sign (=), escape it with a backslash. This option can be specified multiple times for multiple tablespaces. For example:

pg_probackup restore -B backup_dir --instance=instance_name -D data_dir -j 4 -i backup_id -T tablespace1_dir=tablespace1_newdir -T tablespace2_dir=tablespace2_newdir

To restore the cluster on a remote host, follow the instructions in the section called “Using pg_probackup in the Remote Mode”.

Note

By default, the restore command validates the specified backup before restoring the cluster. If you run regular backup validations and would like to save time when restoring the cluster, you can specify the --no-validate flag to skip validation and speed up the recovery.

Incremental Restore #

The speed of restore from backup can be significantly improved by replacing only invalid and changed pages in already existing Postgres Pro data directory using incremental restore options with the restore command.

To restore the database cluster from a backup in incremental mode, run the restore command with the following options:

pg_probackup restore -B backup_dir --instance=instance_name -D data_dir -I incremental_mode
      

Where incremental_mode can take one of the following values:

  • CHECKSUM — read all data files in the data directory, validate header and checksum in every page and replace only invalid pages and those with checksum and LSN not matching with corresponding page in backup. This is the simplest, the most fool-proof incremental mode. Recommended to use by default.

  • LSN — read the pg_control in the data directory to obtain redo LSN and redo TLI, which allows you to determine a point in history(shiftpoint), where data directory state shifted from target backup chain history. If shiftpoint is not within reach of backup chain history, then restore is aborted. If shiftpoint is within reach of backup chain history, then read all data files in the data directory, validate header and checksum in every page and replace only invalid pages and those with LSN greater than shiftpoint. This mode offers a greater speed up compared to CHECKSUM, but rely on two conditions to be met. First, data_checksums parameter must be enabled in data directory (to avoid corruption due to hint bits). This condition will be checked at the start of incremental restore and the operation will be aborted if checksums are disabled. Second, the pg_control file must be synched with state of data directory. This condition cannot checked at the start of restore, so it is a user responsibility to ensure that pg_control contain valid information. Therefore it is not recommended to use LSN mode in any situation, where pg_control cannot be trusted or has been tampered with: after pg_resetxlog execution, after restore from backup without recovery been run, etc.

  • NONE — regular restore without any incremental optimizations.

Regardless of chosen incremental mode, pg_probackup will check, that postmaster in given destination directory is not running and system-identifier is the same as in the backup.

Suppose you want to return an old primary as a replica after switchover using incremental restore in LSN mode:

==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode    WAL Mode  TLI  Time   Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
==================================================================================================================================================
 node      17       SBOL8S  2024-04-09 18:19:43.707720+03  DELTA   STREAM    16/15    3s  114MB  64MB   lz4    1.42  0/3C003020  0/3E8D4930  OK     
 node      17       SBOL8G  2024-04-09 18:19:32.594670+03  PTRACK  STREAM    15/15    4s   30MB  16MB  zlib    2.23  0/31000028  0/310029E0  OK     
 node      17       SBOL83  2024-04-09 18:19:22.269595+03  PAGE    STREAM    15/15    7s   46MB  32MB  pglz    1.44  0/29000028  0/2A0000F8  OK     
 node      17       SBOL7P  2024-04-09 18:19:06.557301+03  FULL    STREAM    15/0     6s  144MB  16MB  zstd    2.47  0/22000028  0/220001C8  OK     

backup_user@backup_host:~$ pg_probackup restore -B /mnt/backups --instance=node -R -I lsn
INFO: Destination directory and tablespace directories are empty, disable incremental restore
INFO: Validating parents for backup SBOL8S
INFO: Validating backup SBOL7P
INFO: Backup SBOL7P data files are valid
INFO: Validating backup SBOL83
INFO: Backup SBOL83 data files are valid
INFO: Validating backup SBOL8G
INFO: Backup SBOL8G data files are valid
INFO: Validating backup SBOL8S
INFO: Backup SBOL8S data files are valid
INFO: Backup SBOL8S WAL segments are valid
INFO: Backup SBOL8S is valid.
INFO: Restoring the database from the backup starting at 2024-04-09 18:19:40+03
INFO: Start restoring backup files. PGDATA size: 616MB
INFO: Backup files are restored. Transferred bytes: 616MB, time elapsed: 2s
INFO: Restore incremental ratio (less is better): 100% (616MB/616MB)
INFO: Syncing restored files to disk
INFO: Restored backup files are synced, time elapsed: 2s
INFO: Restore of backup SBOL8S completed.

Note

Incremental restore is possible only for backups with program_version equal or greater than 2.4.0.

Partial Restore #

If you have enabled partial restore before taking backups, you can restore only some of the databases using partial restore options with the restore commands.

To restore the specified databases only, run the restore command with the following options:

pg_probackup restore -B backup_dir --instance=instance_name --db-include=database_name
      

The --db-include option can be specified multiple times. For example, to restore only databases db1 and db2, run the following command:

pg_probackup restore -B backup_dir --instance=instance_name --db-include=db1 --db-include=db2

To exclude one or more databases from restore, use the --db-exclude option:

pg_probackup restore -B backup_dir --instance=instance_name --db-exclude=database_name

The --db-exclude option can be specified multiple times. For example, to exclude the databases db1 and db2 from restore, run the following command:

pg_probackup restore -B backup_dir --instance=instance_name --db-exclude=db1 --db-exclude=db2

Partial restore relies on lax behavior of Postgres Pro recovery process toward truncated files. For recovery to work properly, files of excluded databases are restored as files of zero size. After the Postgres Pro cluster is successfully started, you must drop the excluded databases using DROP DATABASE command.

To decouple a single cluster containing multiple databases into separate clusters with minimal downtime, you can do partial restore of the cluster as a standby using the --restore-as-replica option for specific databases.

Note

The template0 and template1 databases are always restored.

Note

Due to recovery specifics of Postgres Pro versions earlier than 12, it is advisable that you set the hot_standby parameter to off when running partial restore of a Postgres Pro cluster of version earlier than 12. Otherwise the recovery may fail.

Performing Point-in-Time (PITR) Recovery #

If you have enabled continuous WAL archiving before taking backups, you can restore the cluster to its state at an arbitrary point in time (recovery target) using recovery target options with the restore command.

You can use both STREAM and ARCHIVE backups for point in time recovery as long as the WAL archive is available at least starting from the time the backup was taken. If -i/--backup-id option is omitted, pg_probackup automatically chooses the backup that is the closest to the specified recovery target and starts the restore process, otherwise pg_probackup will try to restore the specified backup to the specified recovery target.

  • To restore the cluster state at the exact time, specify the --recovery-target-time option, in the timestamp format. For example:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target-time="2024-04-10 18:18:26+03"
    
  • To restore the cluster state up to a specific transaction ID, use the --recovery-target-xid option:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target-xid=687
    
  • To restore the cluster state up to the specific LSN, use --recovery-target-lsn option:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target-lsn=16/B374D848
    
  • To restore the cluster state up to the specific named restore point, use --recovery-target-name option:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target-name="before_app_upgrade"
    
  • To restore the backup to the latest state available in the WAL archive, use --recovery-target option with latest value:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target="latest"
    
  • To restore the cluster to the earliest point of consistency, use --recovery-target option with the immediate value:

    pg_probackup restore -B backup_dir --instance=instance_name --recovery-target='immediate'
    

You can also 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_probackup archive-get -B /backup --instance=main --wal-file-path=/var/lib/pgsql/data/pg_wal/RECOVERYXLOG --wal-file-name=000000010000000000000001

Using pg_probackup in the Remote Mode #

pg_probackup supports the remote mode that allows you to perform backup and restore operations remotely via SSH. In this mode, the backup catalog is stored on a local system, while Postgres Pro instance to be backed up is located on a remote system. You must have pg_probackup installed on both systems.

Note

pg_probackup relies on passwordless SSH connection for communication between the hosts.

Note

In addition to SSH connection, pg_probackup uses a regular connection to the database to manage the remote operation. See the section Configuring the Database Cluster for details of how to set up a database connection.

The typical workflow is as follows:

For example, to create an archive full backup of a Postgres Pro cluster located on a remote system with host address 192.168.0.2 on behalf of the postgres user via SSH connection through port 2302, run:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

To restore the latest available backup on a remote system with host address 192.168.0.2 on behalf of the postgres user via SSH connection through port 2302, run:

pg_probackup restore -B backup_dir --instance=instance_name --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302

Restoring an ARCHIVE backup or performing PITR in the remote mode require additional information: destination address, port and username for establishing an SSH connection from the host with database to the host with the backup catalog. This information will be used by the restore_command to copy WAL segments from the archive to the Postgres Pro pg_wal directory.

To solve this problem, you can use Remote WAL Archive Options.

For example, to restore latest backup on remote system using remote mode through SSH connection to user postgres on host with address 192.168.0.2 via port 2302 and user backup on backup catalog host with address 192.168.0.3 via port 2303, run:

pg_probackup restore -B backup_dir --instance=instance_name --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --archive-host=192.168.0.3 --archive-port=2303 --archive-user=backup

Provided arguments will be used to construct the restore_command:

restore_command = '"install_dir/pg_probackup" archive-get -B "backup_dir" --instance=instance_name --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Alternatively, you can use the --restore-command option to provide the entire restore_command:

pg_probackup restore -B backup_dir --instance=instance_name --remote-user=postgres --remote-host=192.168.0.2 --remote-port=2302 --restore-command='"install_dir/pg_probackup" archive-get -B "backup_dir" --instance=instance_name --wal-file-path=%p --wal-file-name=%f --remote-host=192.168.0.3 --remote-port=2303 --remote-user=backup'

Note

The remote mode is currently unavailable for Windows systems.

Running pg_probackup on Parallel Threads #

backup, restore, merge, delete, catchup, checkdb, and validate processes can be executed on several parallel threads. This can significantly speed up pg_probackup operation given enough resources (CPU cores, disk, and network bandwidth).

Parallel execution is controlled by the -j/--threads command-line option. For example, to create a backup using four parallel threads, run:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL -j 4

Note

Parallel restore applies only to copying data from the backup catalog to the data directory of the cluster. When Postgres Pro server is started, WAL records need to be replayed, and this cannot be done in parallel.

Important

A technique is implemented that prevents repeatable copying of one file when pg_probackup runs on multiple threads. With this technique, however, when disks are slow or the system is overloaded, parallel copying might fail. To handle this situation, resolve issues with your system resources.

Configuring pg_probackup #

Once the backup catalog is initialized and a new backup instance is added, you can use the pg_probackup.conf configuration file located in the backup_dir/backups/instance_name directory to fine-tune pg_probackup configuration.

For example, backup and checkdb commands use a regular Postgres Pro connection. To avoid specifying connection options each time on the command line, you can set them in the pg_probackup.conf configuration file using the set-config command.

Note

It is not recommended to edit pg_probackup.conf manually.

Initially, pg_probackup.conf contains the following settings:

  • PGDATA — the path to the data directory of the cluster to back up.

  • system-identifier — the unique identifier of the Postgres Pro instance.

Additionally, you can define remote mode, retention, logging, and compression settings using the set-config command:

pg_probackup set-config -B backup_dir --instance=instance_name
[--external-dirs=external_directory_path] [remote_options] [connection_options] [retention_options] [logging_options]

To view the current settings, run the following command:

pg_probackup show-config -B backup_dir --instance=instance_name

You can override the settings defined in pg_probackup.conf when running pg_probackup commands via the corresponding environment variables and/or command line options.

Specifying Connection Settings #

If you define connection settings in the pg_probackup.conf configuration file, you can omit connection options in all the subsequent pg_probackup commands. However, if the corresponding environment variables are set, they get higher priority. The options provided on the command line overwrite both environment variables and configuration file settings.

If nothing is given, the default values are taken. By default pg_probackup tries to use local connection via Unix domain socket (localhost on Windows) and tries to get the database name and the user name from the PGUSER environment variable or the current OS user name.

Managing the Backup Catalog #

With pg_probackup, you can manage backups from the command line:

Viewing Backup Information #

To view the list of existing backups for every instance, run the command:

pg_probackup show -B backup_dir

pg_probackup displays the list of all the available backups. For example:

BACKUP INSTANCE 'node'
==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode    WAL Mode  TLI  Time   Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status
==================================================================================================================================================
 node      17       SBOL94  2024-04-09 18:19:56.603355+03  FULL    ARCHIVE   1/0    6s  377MB  16MB   lz4    1.46  0/41000028  0/420000C0  OK
 node      17       SBOL8S  2024-04-09 18:19:43.707720+03  DELTA   STREAM    1/1    3s  114MB  64MB   lz4    1.42  0/3C003020  0/3E8D4930  OK
 node      17       SBOL8G  2024-04-09 18:19:32.594670+03  PTRACK  STREAM    1/1    4s   30MB  16MB  zlib    2.23  0/31000028  0/310029E0  OK
 node      17       SBOL83  2024-04-09 18:19:22.269595+03  PAGE    STREAM    1/1    7s   46MB  32MB  pglz    1.44  0/29000028  0/2A0000F8  OK
 node      17       SBOL7P  2024-04-09 18:19:06.557301+03  FULL    STREAM    1/0    6s  144MB  16MB  zstd    2.47  0/22000028  0/220001C8  OK

For each backup, the following information is provided:

  • Instance — the instance name.

  • Version — Postgres Pro major version.

  • ID — the backup identifier.

  • Recovery time — the earliest moment for which you can restore the state of the database cluster.

  • Mode — the method used to take this backup. Possible values: FULL, PAGE, DELTA, PTRACK.

  • WAL Mode — WAL delivery mode. Possible values: STREAM and ARCHIVE.

  • TLI — timeline identifiers of the current backup and its parent.

  • Time — the time it took to perform the backup.

  • Data — the size of the data files in this backup. This value does not include the size of WAL files. For STREAM backups, the total size of the backup can be calculated as Data + WAL.

  • WAL — the uncompressed size of WAL files that need to be applied during recovery for the backup to reach a consistent state.

  • compress-alg — compression algorithm used during backup. Possible values: zlib, pglz, lz4, zstd, none.

  • Zratio — compression ratio calculated as “uncompressed-bytes” / “data-bytes”.

  • Start LSN — WAL log sequence number corresponding to the start of the backup process. REDO point for Postgres Pro recovery process to start from.

  • Stop LSN — WAL log sequence number corresponding to the end of the backup process. Consistency point for Postgres Pro recovery process.

  • Status — backup status. Possible values:

    • OK — the backup is complete and valid.

    • DONE — the backup is complete, but was not validated.

    • RUNNING — the backup is in progress.

    • MERGING — the backup is being merged.

    • MERGED — the backup data files were successfully merged, but its metadata is in the process of being updated. Only full backups can have this status.

    • DELETING — the backup files are being deleted.

    • CORRUPT — some of the backup files are corrupt.

    • ERROR — the backup was aborted because of an unexpected error.

    • ORPHAN — the backup is invalid because one of its parent backups is corrupt or missing.

    • HIDDEN_FOR_TEST — a test script marked the backup as nonexistent. (pg_probackup never sets this status by itself.)

You can restore the cluster from the backup only if the backup status is OK or DONE.

To get more detailed information about the backup, run the show command with the backup ID:

pg_probackup show -B backup_dir --instance=instance_name -i backup_id

The sample output is as follows:

#Configuration
backup-mode = FULL
stream = false
compress-alg = lz4
compress-level = 1
from-replica = false

#Compatibility
block-size = 8192
xlog-block-size = 8192
checksum-version = 1
program-version = 2.7.3
server-version = 17

#Result backup info
timelineid = 1
start-lsn = 0/41000028
stop-lsn = 0/420000C0
start-time = '2024-04-09 18:19:52+03'
end-time = '2024-04-09 18:19:58+03'
end-validation-time = '2024-04-09 18:19:59+03'
recovery-xid = 757
recovery-time = '2024-04-09 18:19:56.603355+03'
data-bytes = 395651278
wal-bytes = 16777216
uncompressed-bytes = 578552566
pgdata-bytes = 578552248
status = OK
primary_conninfo = 'user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable'
content-crc = 3862224379

Detailed output has additional attributes:

  • compress-alg — compression algorithm used during backup. Possible values: zlib, pglz, lz4, zstd, none.

  • compress-level — compression level used during backup.

  • from-replica — was this backup taken on a standby? Possible values: 1, 0.

  • block-size — the block_size setting of Postgres Pro cluster at the backup start.

  • checksum-version — are data_checksums enabled in the backed up Postgres Pro cluster? Possible values: 1, 0.

  • program-version — full version of pg_probackup binary used to create the backup.

  • start-time — the backup start time.

  • end-time — the backup end time.

  • end-validation-time — the backup validation end time.

  • expire-time — the point in time when a pinned backup can be removed in accordance with retention policy. This attribute is only available for pinned backups.

  • uncompressed-bytes — the size of data files before adding page headers and applying compression. You can evaluate the effectiveness of compression by comparing uncompressed-bytes to data-bytes if compression if used.

  • pgdata-bytes — the size of Postgres Pro cluster data files at the time of backup. You can evaluate the effectiveness of an incremental backup by comparing pgdata-bytes to uncompressed-bytes.

  • recovery-xid — transaction ID at the backup end time.

  • parent-backup-id — ID of the parent backup. Available only for incremental backups.

  • primary_conninfo — libpq connection parameters used to connect to the Postgres Pro cluster to take this backup. The password is not included.

  • note — text note attached to backup.

  • content-crc — CRC32 checksum of backup_content.control file. It is used to detect corruption of backup metainformation.

You can also get the detailed information about the backup in the JSON format:

pg_probackup show -B backup_dir --instance=instance_name --format=json -i backup_id

The sample output is as follows:

[
    {
        "instance": "node",
        "backups": [
            {
                "id": "SBOL94",
                "status": "OK",
                "start-time": "2024-04-09 18:19:52+03",
                "backup-mode": "FULL",
                "wal": "ARCHIVE",
                "compress-alg": "lz4",
                "compress-level": 1,
                "from-replica": "false",
                "block-size": 8192,
                "xlog-block-size": 8192,
                "checksum-version": 1,
                "program-version": "2.7.3",
                "server-version": "17",
                "current-tli": 16,
                "parent-tli": 2,
                "start-lsn": "0/41000028",
                "stop-lsn": "0/420000C0",
                "end-time": "2024-04-09 18:19:58+03",
                "end-validation-time": "2024-04-09 18:19:59+03",
                "recovery-xid": 757,
                "recovery-time": "2024-04-09 18:19:56.603355+03",
                "data-bytes": 395651278,
                "wal-bytes": 16777216,
                "uncompressed-bytes": 578552566,
                "pgdata-bytes": 578552248,
                "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                "content-crc": 3862224379
            }
        ]
    }
]

Viewing WAL Archive Information #

To view the information about WAL archive for every instance, run the command:

pg_probackup show -B backup_dir [--instance=instance_name] --archive

pg_probackup displays the list of all the available WAL files grouped by timelines. For example:

ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          00000001000000000000001B  000000010000000000000042  40          640MB  1.00    5          OK     

For each timeline, the following information is provided:

  • TLI — timeline identifier.

  • Parent TLI — identifier of the timeline from which this timeline branched off.

  • Switchpoint — LSN of the moment when the timeline branched off from its parent timeline.

  • Min Segno — the first WAL segment belonging to the timeline.

  • Max Segno — the last WAL segment belonging to the timeline.

  • N segments — number of WAL segments belonging to the timeline.

  • Size — the size that files take on disk.

  • Zalg — compression algorithm used during backup. Possible values: zlib, pglz, lz4, zstd, none.

  • Zratio — compression ratio calculated as N segments * wal_segment_size * wal_block_size / Size.

  • N backups — number of backups belonging to the timeline. To get the details about backups, use the JSON format.

  • Status — status of the WAL archive for this timeline. Possible values:

    • OK — all WAL segments between Min Segno and Max Segno are present.

    • DEGRADED — some WAL segments between Min Segno and Max Segno are missing. To find out which files are lost, view this report in the JSON format. This status may appear if several WAL files (in the middle of the sequence) were deleted by the delete command with the --delete-wal option according to the retention policy. This status does not affect the restore correctness, but it can be impossible to perform PITR of the cluster to some recovery targets.

To get more detailed information about the WAL archive in the JSON format, run the command:

pg_probackup show -B backup_dir [--instance=instance_name] --archive --format=json

The sample output is as follows:

[
    {
        "instance": "node",
        "timelines": [
            {
                "tli": 1,
                "parent-tli": 0,
                "switchpoint": "0/0",
                "min-segno": "00000001000000000000001B",
                "max-segno": "000000010000000000000042",
                "n-segments": 40,
                "size": 671088640,
                "zratio": 1.00,
                "closest-backup-id": "",
                "status": "OK",
                "lost-segments": [],
                "backups": [
                    {
                        "id": "SBOL94",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:52+03",
                        "backup-mode": "FULL",
                        "wal": "ARCHIVE",
                        "compress-alg": "lz4",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 2,
                        "parent-tli": 0,
                        "start-lsn": "0/41000028",
                        "stop-lsn": "0/420000C0",
                        "end-time": "2024-04-09 18:19:58+03",
                        "end-validation-time": "2024-04-09 18:19:59+03",
                        "recovery-xid": 757,
                        "recovery-time": "2024-04-09 18:19:56.603355+03",
                        "data-bytes": 395651278,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 578552566,
                        "pgdata-bytes": 578552248,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 3862224379
                    },
                    {
                        "id": "SBOL8S",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:40+03",
                        "parent-backup-id": "SBOL8G",
                        "backup-mode": "DELTA",
                        "wal": "STREAM",
                        "compress-alg": "lz4",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/3C003020",
                        "stop-lsn": "0/3E8D4930",
                        "end-time": "2024-04-09 18:19:43+03",
                        "end-validation-time": "2024-04-09 18:19:44+03",
                        "recovery-xid": 757,
                        "recovery-time": "2024-04-09 18:19:43.707720+03",
                        "data-bytes": 119350434,
                        "wal-bytes": 67108864,
                        "uncompressed-bytes": 170044286,
                        "pgdata-bytes": 578552248,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 1259851036
                    },
                    {
                        "id": "SBOL8G",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:28+03",
                        "parent-backup-id": "SBOL83",
                        "backup-mode": "PTRACK",
                        "wal": "STREAM",
                        "compress-alg": "zlib",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/31000028",
                        "stop-lsn": "0/310029E0",
                        "end-time": "2024-04-09 18:19:32+03",
                        "end-validation-time": "2024-04-09 18:19:33+03",
                        "recovery-xid": 756,
                        "recovery-time": "2024-04-09 18:19:32.594670+03",
                        "data-bytes": 31218302,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 69610366,
                        "pgdata-bytes": 510263736,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 2293248595
                    },
                    {
                        "id": "SBOL83",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:15+03",
                        "parent-backup-id": "SBOL7P",
                        "backup-mode": "PAGE",
                        "wal": "STREAM",
                        "compress-alg": "pglz",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 1,
                        "start-lsn": "0/29000028",
                        "stop-lsn": "0/2A0000F8",
                        "end-time": "2024-04-09 18:19:22+03",
                        "end-validation-time": "2024-04-09 18:19:22+03",
                        "recovery-xid": 755,
                        "recovery-time": "2024-04-09 18:19:22.269595+03",
                        "data-bytes": 48394744,
                        "wal-bytes": 33554432,
                        "uncompressed-bytes": 69577598,
                        "pgdata-bytes": 441975224,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 343227200
                    },
                    {
                        "id": "SBOL7P",
                        "status": "OK",
                        "start-time": "2024-04-09 18:19:01+03",
                        "backup-mode": "FULL",
                        "wal": "STREAM",
                        "compress-alg": "zstd",
                        "compress-level": 1,
                        "from-replica": "false",
                        "block-size": 8192,
                        "xlog-block-size": 8192,
                        "checksum-version": 1,
                        "program-version": "2.7.3",
                        "server-version": "17",
                        "current-tli": 1,
                        "parent-tli": 0,
                        "start-lsn": "0/22000028",
                        "stop-lsn": "0/220001C8",
                        "end-time": "2024-04-09 18:19:07+03",
                        "end-validation-time": "2024-04-09 18:19:09+03",
                        "recovery-xid": 754,
                        "recovery-time": "2024-04-09 18:19:06.557301+03",
                        "data-bytes": 151177272,
                        "wal-bytes": 16777216,
                        "uncompressed-bytes": 373695222,
                        "pgdata-bytes": 373694904,
                        "primary_conninfo": "user=backup channel_binding=prefer host=localhost port=5432 sslmode=prefer sslcompression=0 sslcertmode=allow sslsni=1 ssl_min_protocol_version=TLSv1.2 gssencmode=prefer krbsrvname=postgres gssdelegation=0 target_session_attrs=any load_balance_hosts=disable",
                        "content-crc": 1636300818
                    }
                ]
            }
        ]
    }
]

Most fields are consistent with the plain format, with some exceptions:

  • The size is in bytes.

  • The closest-backup-id attribute contains the ID of the most recent valid backup that belongs to one of the previous timelines. You can use this backup to perform point-in-time recovery to this timeline. If such a backup does not exist, this string is empty.

  • The lost-segments array provides with information about intervals of missing segments in DEGRADED timelines. In OK timelines, the lost-segments array is empty.

  • The backups array lists all backups belonging to the timeline. If the timeline has no backups, this array is empty.

Configuring Retention Policy #

With pg_probackup, you can configure retention policy to remove redundant backups, clean up unneeded WAL files, as well as pin specific backups to ensure they are kept for the specified time, as explained in the sections below. All these actions can be combined together in any way.

Removing Redundant Backups #

By default, all backup copies created with pg_probackup are stored in the specified backup catalog. To save disk space, you can configure retention policy to remove redundant backup copies.

To configure retention policy, set one or more of the following variables in the pg_probackup.conf file via set-config:

--retention-redundancy=redundancy

Specifies the number of full backup copies to keep in the backup catalog.

--retention-window=window

Defines the earliest point in time for which pg_probackup can complete the recovery. This option is set in the number of days from the current moment. For example, if retention-window=7, pg_probackup must keep at least one backup copy that is older than seven days, with all the corresponding WAL files, and all the backups that follow.

If both --retention-redundancy and --retention-window options are set, both these conditions have to be taken into account when purging the backup catalog. For example, if you set --retention-redundancy=2 and --retention-window=7, pg_probackup has to keep two full backup copies, as well as all the backups required to ensure recoverability for the last seven days:

pg_probackup set-config -B backup_dir --instance=instance_name --retention-redundancy=2 --retention-window=7

It is recommended to always keep at least two last parent full backups to avoid errors when creating incremental backups.

To clean up the backup catalog in accordance with retention policy, you have to run the delete command with retention flags, as shown below, or use the backup command with these flags to process the outdated backup copies right when the new backup is created.

For example, to remove all backup copies that no longer satisfy the defined retention policy, run the following command with the --delete-expired flag:

pg_probackup delete -B backup_dir --instance=instance_name --delete-expired

If you would like to also remove the WAL files that are no longer required for any of the backups, you should also specify the --delete-wal flag:

pg_probackup delete -B backup_dir --instance=instance_name --delete-expired --delete-wal

You can also set or override the current retention policy by specifying --retention-redundancy and --retention-window options directly when running delete or backup commands:

pg_probackup delete -B backup_dir --instance=instance_name --delete-expired --retention-window=7 --retention-redundancy=2

Since incremental backups require that their parent full backup and all the preceding incremental backups are available, if any of such backups expire, they still cannot be removed while at least one incremental backup in this chain satisfies the retention policy. To avoid keeping expired backups that are still required to restore an active incremental one, you can merge them with this backup using the --merge-expired flag when running backup or delete commands.

Suppose you have backed up the node instance in the backup_dir directory, with the --retention-window option set to 6 and --retention-redundancy option set to 2, and you have the following backups available on August 01, 2024:

BACKUP INSTANCE 'node'
===========================================================================================================================================
 Instance  Version  ID      Recovery Time           Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
===========================================================================================================================================
 node      17       SHJ1N9  2024-08-01 09:50:00+03  FULL   ARCHIVE   1/0    5s    13MB  16MB  zstd    2,81  0/1D000028  0/1E0000C0  OK
 node      17       SHJ1N8  2024-08-01 09:49:59+03  DELTA  ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/1A000028  0/1B0000C0  OK
 node      17       SHH6Z8  2024-07-31 09:49:59+03  PAGE   ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/17000028  0/180000C0  OK
 node      17       SHFCB6  2024-07-30 09:49:57+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,83  0/14000028  0/150000C0  OK
 node      17       SH9SB5  2024-07-27 09:49:56+03  PAGE   ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/11000028  0/120000C0  OK
 ----------------------------------------------------------retention window-----------------------------------------------------------
 node      17       SH62Z5  2024-07-25 09:49:56+03  DELTA  ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/E000028   0/F0000C0   OK
 node      17       SH48B3  2024-07-24 09:49:54+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,86  0/B000028   0/C0000C0   OK
 node      17       SGWTN3  2024-07-20 09:49:54+03  PAGE   ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/8000028   0/90000C0   OK
 node      17       SGUYZ2  2024-07-19 09:49:53+03  DELTA  ARCHIVE   1/1    5s  6442kB  16MB  zstd    1,07  0/5000028   0/60000C0   OK
 node      17       SGT4B1  2024-07-18 09:49:52+03  FULL   ARCHIVE   1/0    5s    11MB  16MB  zstd    2,89  0/2000028   0/3003A28   OK

If you run the delete command with the --delete-expired flag, the backups with IDs SGT4B1, SGUYZ2, and SGWTN3 will be removed as they are expired both according to the retention window and due to redundancy (the required set of full backups has already been retained). SGUYZ2 and SGWTN3 will also be removed since the base full backup is expired.

Running the delete command with the --merge-expired flag will merge backups SH48B3 and SH62Z5 with SH9SB5. The merge will occur with SH9SB5 as it is the first non-expired delta backup, which can be merged with expired delta backups SH62Z5 and expired full backup SH48B3.

pg_probackup delete -B backup_dir --instance=node --delete-expired --merge-expired
pg_probackup show -B backup_dir
BACKUP INSTANCE 'node'
===========================================================================================================================================
 Instance  Version  ID      Recovery Time           Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status
===========================================================================================================================================
 node      17       SHJ1N9  2024-08-01 09:50:00+03  FULL   ARCHIVE   1/0    5s    13MB  16MB  zstd    2,81  0/1D000028  0/1E0000C0  OK
 node      17       SHJ1N8  2024-08-01 09:49:59+03  DELTA  ARCHIVE   1/1    5s  6432kB  16MB  zstd    1,06  0/1A000028  0/1B0000C0  OK
 node      17       SHH6Z8  2024-07-31 09:49:59+03  PAGE   ARCHIVE   1/1    5s  6431kB  16MB  zstd    1,06  0/17000028  0/180000C0  OK
 node      17       SHFCB6  2024-07-30 09:49:57+03  FULL   ARCHIVE   1/0    5s    12MB  16MB  zstd    2,83  0/14000028  0/150000C0  OK
 node      17       SH9SB5  2024-07-27 09:49:56+03  FULL   ARCHIVE   1/0    1s    12MB  16MB  zstd    2,84  0/11000028  0/120000C0  OK

The Time field for the merged backup displays the time required for the merge.

Pinning Backups #

If you need to keep certain backups longer than the established retention policy allows, you can pin them for arbitrary time. For example:

pg_probackup set-backup -B backup_dir --instance=instance_name -i backup_id --ttl=30d

This command sets the expiration time of the specified backup to 30 days starting from the time indicated in its recovery-time attribute.

You can also explicitly set the expiration time for a backup using the --expire-time option. For example:

pg_probackup set-backup -B backup_dir --instance=instance_name -i backup_id --expire-time="2027-04-09 18:21:32+00"

Alternatively, you can use the --ttl and --expire-time options with the backup command to pin the newly created backup:

pg_probackup backup -B backup_dir --instance=instance_name -b FULL --ttl=30d
pg_probackup backup -B backup_dir --instance=instance_name -b FULL --expire-time="2027-04-09 18:21:32+00"

To check if the backup is pinned, run the show command:

pg_probackup show -B backup_dir --instance=instance_name -i backup_id

If the backup is pinned, it has the expire-time attribute that displays its expiration time:

...
recovery-time = '2024-04-09 18:21:32+00'
expire-time = '2027-04-09 18:21:32+00'
data-bytes = 22288792
...

You can unpin the backup by setting the --ttl option to zero:

pg_probackup set-backup -B backup_dir --instance=instance_name -i backup_id --ttl=0

Note

A pinned incremental backup implicitly pins all its parent backups. If you unpin such a backup later, its implicitly pinned parents will also be automatically unpinned.

Configuring WAL Archive Retention Policy #

When continuous WAL archiving is enabled, archived WAL segments can take a lot of disk space. Even if you delete old backup copies from time to time, the --delete-wal flag can purge only those WAL segments that do not apply to any of the remaining backups in the backup catalog. However, if point-in-time recovery is critical only for the most recent backups, you can configure WAL archive retention policy to keep WAL archive of limited depth and win back some more disk space.

To configure WAL archive retention policy, you have to run the set-config command with the --wal-depth option that specifies the number of backups that can be used for PITR. This setting applies to all the timelines, so you should be able to perform PITR for the same number of backups on each timeline, if available. Pinned backups are not included into this count: if one of the latest backups is pinned, pg_probackup ensures that PITR is possible for one extra backup.

To remove WAL segments that do not satisfy the defined WAL archive retention policy, you simply have to run the delete or backup command with the --delete-wal flag. For archive backups, WAL segments between Start LSN and Stop LSN are always kept intact, so such backups remain valid regardless of the --wal-depth setting and can still be restored, if required.

You can also use the --wal-depth option with the delete and backup commands to override the previously defined WAL archive retention policy and purge old WAL segments on the fly.

Suppose you have backed up the node instance in the backup_dir directory and configured continuous WAL archiving:

pg_probackup show -B backup_dir --instance=node
==================================================================================================================================================
 Instance  Version  ID      Recovery Time                  Mode   WAL Mode  TLI  Time    Data   WAL  Zalg  Zratio  Start LSN   Stop LSN    Status 
==================================================================================================================================================
 node      17       SBOLDA  2024-04-09 18:22:23.147138+03  DELTA  STREAM    1/1    1s  1165kB  16MB  zstd    1.09  0/6F000028  0/6F000190  OK     
 node      17       SBOLCY  2024-04-09 18:22:16.079841+03  FULL   STREAM    1/0   10s   278MB  16MB  zstd    2.46  0/6D000028  0/6D000190  OK     
 node      17       SBOLCW  2024-04-09 18:22:10.154022+03  DELTA  STREAM    1/1    2s  1364kB  16MB  zstd    1.01  0/6B000028  0/6B000190  OK     
 node      17       SBOLCS  2024-04-09 18:22:07.521646+03  DELTA  STREAM    1/1    4s    78MB  16MB  zstd    2.41  0/69000028  0/69000190  OK     
 node      17       SBOLCC  2024-04-09 18:21:55.830115+03  FULL   STREAM    1/0   15s   278MB  96MB  zstd    2.46  0/600060C8  0/64FE6640  OK     
 node      17       SBOLBW  2024-04-09 18:21:38.399702+03  FULL   STREAM    1/0   12s   278MB  96MB  zstd    2.46  0/54001830  0/589E5908  OK     

You can check the state of the WAL archive by running the show command with the --archive flag:

pg_probackup show -B backup_dir --instance=node --archive
ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          000000010000000000000052  00000001000000000000006F  30          480MB  1.00    6          OK     

WAL purge without --wal-depth cannot achieve much, only one segment is removed:

pg_probackup delete -B backup_dir --instance=node --delete-wal
ARCHIVE INSTANCE 'node'
================================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size   Zratio  N backups  Status 
================================================================================================================================
 1    0           0/0          000000010000000000000054  00000001000000000000006F  28          448MB  1.00    6          OK     

If you would like, for example, to keep only those WAL segments that can be applied to the latest valid backup, set the --wal-depth option to 1:

pg_probackup delete -B backup_dir --instance=node --delete-wal --wal-depth=1
ARCHIVE INSTANCE 'node'
===============================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size  Zratio  N backups  Status 
===============================================================================================================================
 1    0           0/0          00000001000000000000006F  00000001000000000000006F  1           16MB  1.00    6          OK     

Alternatively, you can use the --wal-depth option with the backup command:

pg_probackup backup -B backup_dir --instance=node -b DELTA --wal-depth=1 --delete-wal
ARCHIVE INSTANCE 'node'
===============================================================================================================================
 TLI  Parent TLI  Switchpoint  Min Segno                 Max Segno                 N segments  Size  Zratio  N backups  Status 
===============================================================================================================================
 1    0           0/0          000000010000000000000071  000000010000000000000071  1           16MB  1.00    7          OK     

Merging Backups #

As you take more and more incremental backups, the total size of the backup catalog can substantially grow. To save disk space, you can merge incremental backups to their parent full backup by running the merge command, specifying the backup ID of the most recent incremental backup you would like to merge:

pg_probackup merge -B backup_dir --instance=instance_name -i backup_id

This command 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. Thus, the merge operation is virtually equivalent to retaking a full backup and removing all the outdated backups, but it allows you to save much time, especially for large data volumes, as well as I/O and network traffic if you are using pg_probackup in the remote mode.

Before the merge, pg_probackup validates all the affected backups to ensure that they are valid. You can check the current backup status by running the show command with the backup ID:

pg_probackup show -B backup_dir --instance=instance_name -i backup_id

If the merge is still in progress, the backup status is displayed as MERGING. For full backups, it can also be shown as MERGED while the metadata is being updated at the final stage of the merge. The merge is idempotent, so you can restart the merge if it was interrupted.

Warning

Avoid force-terminating the merge operation, as it may cause subsequent merge commands to fail and disrupt backup validation.

Deleting Backups #

To delete a backup that is no longer required, run the following command:

pg_probackup delete -B backup_dir --instance=instance_name -i backup_id

This command will delete the backup with the specified backup_id, together with all the incremental backups that descend from backup_id, if any. This way you can delete some recent incremental backups, retaining the underlying full backup and some of the incremental backups that follow it.

To delete obsolete WAL files that are not necessary to restore any of the remaining backups, use the --delete-wal flag:

pg_probackup delete -B backup_dir --instance=instance_name --delete-wal

To delete backups that are expired according to the current retention policy, use the --delete-expired flag:

pg_probackup delete -B backup_dir --instance=instance_name --delete-expired

Expired backups cannot be removed while at least one incremental backup that satisfies the retention policy is based on them. If you would like to minimize the number of backups still required to keep incremental backups valid, specify the --merge-expired flag when running this command:

pg_probackup delete -B backup_dir --instance=instance_name --delete-expired --merge-expired

In this case, pg_probackup searches for the oldest incremental backup that satisfies the retention policy and merges this backup with the underlying full and incremental backups that have already expired, thus making it a full backup. Once the merge is complete, the remaining expired backups are deleted.

Before merging or deleting backups, you can run the delete command with the --dry-run flag, which displays the status of all the available backups according to the current retention policy, without performing any irreversible actions.

To delete all backups with specific status, use the --status:

pg_probackup delete -B backup_dir --instance=instance_name --status=ERROR
    

Deleting backups by status ignores established retention policies.

Cloning and Synchronizing Postgres Pro Instance #

pg_probackup can create a copy of a Postgres Pro instance directly, without using the backup catalog. To do this, you can run the catchup command. It can be useful in the following cases:

  • To add a new standby server.

    Usually, pg_basebackup is used to create a copy of a Postgres Pro instance. If the data directory of the destination instance is empty, the catchup command works similarly, but it can be faster if run in parallel mode.

  • To have a fallen-behind standby server “catch up” with the primary.

    Under write-intensive load, replicas may fail to replay WAL fast enough to keep up with the primary and hence may lag behind. A usual solution to create a new replica and switch to it requires a lot of extra space and data transfer. The catchup command allows you to update an existing replica much faster by bringing differences from the primary.

catchup is different from other pg_probackup operations:

  • The backup catalog is not required.

  • STREAM WAL delivery mode is only supported.

  • Copying external directories is not supported.

  • DDL commands CREATE TABLESPACE/DROP TABLESPACE cannot be run simultaneously with catchup.

  • catchup takes configuration files, such as postgresql.conf, postgresql.auto.conf, or pg_hba.conf, from the source server and overwrites them on the target server. The --exclude-path option allows you to keep the configuration files intact.

To prepare for cloning/synchronizing a Postgres Pro instance, set up the source server as follows:

Before cloning/synchronizing a Postgres Pro instance, ensure that the source server is running and accepting connections. To clone/sync a Postgres Pro instance, on the server with the destination instance, you can run the catchup command as follows:

pg_probackup catchup -b catchup_mode --source-pgdata=path_to_pgdata_on_remote_server --destination-pgdata=path_to_local_dir --stream [connection_options] [remote_options]

Where catchup_mode can take one of the following values:

  • FULL — creates a full copy of the Postgres Pro instance. The data directory of the destination instance must be empty for this mode.

  • DELTA — reads all data files in the data directory and creates an incremental copy for pages that have changed since the destination instance was shut down.

  • PTRACK — tracking page changes on the fly, only reads and copies pages that have changed since the point of divergence of the source and destination instances.

    Warning

    PTRACK catchup mode requires PTRACK not earlier than 2.0 and hence, Postgres Pro not earlier than 11.

By specifying the --stream option, you can set STREAM WAL delivery mode of copying, which will include all the necessary WAL files by streaming them from the server via replication protocol.

You can use connection_options to specify the connection to the source database cluster. If it is located on a different server, also specify remote_options.

If the source database cluster contains tablespaces that must be located in a different directory, additionally specify the --tablespace-mapping option:

pg_probackup catchup -b catchup_mode --source-pgdata=path_to_pgdata_on_remote_server --destination-pgdata=path_to_local_dir --stream --tablespace-mapping=OLDDIR=NEWDIR

To run the catchup command on parallel threads, specify the number of threads with the --threads option:

pg_probackup catchup -b catchup_mode --source-pgdata=path_to_pgdata_on_remote_server --destination-pgdata=path_to_local_dir --stream --threads=num_threads

Before cloning/synchronising a Postgres Pro instance, you can run the catchup command with the --dry-run flag to estimate the size of data files to be transferred, but make no changes on disk:

pg_probackup catchup -b catchup_mode --source-pgdata=path_to_pgdata_on_remote_server --destination-pgdata=path_to_local_dir --stream --dry-run

For example, assume that a remote standby server with the Postgres Pro instance having /replica-pgdata data directory has fallen behind. To sync this instance with the one in /master-pgdata data directory, you can run the catchup command in the PTRACK mode on four parallel threads as follows:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=PTRACK --remote-host=remote-hostname --remote-user=remote-unix-username -j 4 --exclude-path=postgresql.conf --exclude-path=postgresql.auto.conf --exclude-path=pg_hba.conf --exclude-path=pg_ident.conf

Note that in this example, the configuration files will not be overwritten during synchronization.

Another example shows how you can add a new remote standby server with the Postgres Pro data directory /replica-pgdata by running the catchup command in the FULL mode on four parallel threads:

pg_probackup catchup --source-pgdata=/master-pgdata --destination-pgdata=/replica-pgdata -p 5432 -d postgres -U remote-postgres-user --stream --backup-mode=FULL --remote-host=remote-hostname --remote-user=remote-unix-username -j 4

Command-Line Reference #

Commands #

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

version #

pg_probackup version [--format=json]

Prints pg_probackup version and edition, as well as Postgres Pro version and edition.

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

pg_probackup version --format=json
{
    "pg_probackup":
    {
        "version": "2.8.2",
        "edition": "community"
    },
    "database":
    {
        "type": "Postgres Pro Standard",
        "version": "16.3.1"
    },
    "compressions": [zlib, pglz, lz4, zstd]
}

help #

pg_probackup help [command]

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

init #

pg_probackup init -B backup_dir [--skip-if-exists] [--help]
[logging_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_probackup 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 details, see the section Initializing the Backup Catalog.

add-instance #

pg_probackup add-instance -B backup_dir -D data_dir --instance=instance_name
[--skip-if-exists] [--help] [--wal-tree] [logging_options]

Initializes a new backup instance inside the backup catalog backup_dir and generates the pg_probackup.conf configuration file that controls pg_probackup settings for the cluster with the specified data_dir data directory.

--skip-if-exists

Allows skipping initialization without raising an error if an instance already exists.

--wal-tree

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 on the add-instance command, see the section Adding a New Backup Instance.

del-instance #

pg_probackup del-instance -B backup_dir --instance=instance_name [--help]
[logging_options]

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

set-config #

pg_probackup set-config -B backup_dir --instance=instance_name
[--help] [--pgdata=pgdata-path]
[--retention-redundancy=redundancy][--retention-window=window][--wal-depth=wal_depth]
[--compress-algorithm=compression_algorithm] [--compress-level=compression_level]
[-d dbname] [-h host] [-p port] [-U username]
[--archive-timeout=timeout] [--external-dirs=external_directory_path]
[--restore-command=cmdline]
[remote_options] [remote_wal_archive_options] [logging_options]

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

For all available settings, see the Options section.

It is not recommended to edit pg_probackup.conf manually.

set-backup #

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

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

--note=backup_note

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

For all available pinning settings, see the section Pinning Options.

show-config #

pg_probackup show-config -B backup_dir --instance instance_name [--format=plain|json]
[--no-scale-units] [logging_options]

Displays all the current pg_probackup configuration settings, including those that are specified in the pg_probackup.conf configuration file located in the backup_dir/backups/instance_name directory and those that were provided on a command line. You can specify the --format=json option to get the result in the JSON format. By default, configuration settings are shown as plain text.

You can also specify the --no-scale-units option to display time and memory configuration settings in their base (unscaled) units. Otherwise, the values are scaled to larger units for optimal display. For example, if archive-timeout is 300, then 5min is displayed, but if archive-timeout is 301, then 301s is displayed. Also, if the --no-scale-units option is specified, configuration settings are displayed without units and for the JSON format, numeric and boolean values are not enclosed in quotes. This facilitates parsing the output.

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

show #

pg_probackup show -B backup_dir
[--help] [--instance=instance_name [-i backup_id | --archive]] [--format=plain|json] [--no-color] [--show-symlinks]
[logging_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 WAL archive of the backup catalog.

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.

If the --show-symlinks option is specified, the command also shows the links between merged backups and the original full backups that incremental backups were merged to.

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

backup #

pg_probackup backup -B backup_dir -b backup_mode --instance=instance_name
[--help] [-j num_threads] [--progress]
[--backup-threads num_threads] [--validate-threads num_threads]
[-C] [--stream [-S slot_name] [--temp-slot[=true|false|on|off]]] [--backup-pg-log]
[--no-validate] [--skip-block-validation]
[-w --no-password] [-W --password] [--allow-group-access]
[--write-rate-limit=bitrate]
[--archive-timeout=timeout] [--external-dirs=external_directory_path]
[--no-sync] [--note=backup_note]
[connection_options] [compression_options] [remote_options]
[retention_options] [pinning_options] [logging_options]

Creates a backup copy of the Postgres Pro instance.

-b mode
--backup-mode=mode

Specifies the backup mode to use. Possible values are: FULL, DELTA, PAGE, and PTRACK.

--backup-threads num_threads

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

--validate-threads num_threads

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

-C
--smooth-checkpoint

Spreads out the checkpoint over a period of time. By default, pg_probackup tries to complete the checkpoint as soon as possible.

--stream

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

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

Creates a temporary physical replication slot for streaming WAL from the backed up Postgres Pro instance. --temp-slot is enabled by default. It ensures that all the required WAL segments remain available if WAL is rotated while the backup is in progress. This flag can only be used together with the --stream flag. The default slot name is pg_probackup_slot. To change it, use the --slot/-S option and explicitly specify --temp-slot or --temp-slot=true|on.

-S slot_name
--slot=slot_name

Specifies the replication slot to connect to for WAL streaming. This option can only be used together with the --stream flag.

--backup-pg-log

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

-E external_directory_path
--external-dirs=external_directory_path

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

--allow-group-access

Provides read access to backups stored on the backup host to any OS user in the same group as the OS user on the backup host who runs pg_probackup operations.

--write-rate-limit=bitrate

Sets the rate of writing data to disk, in MBps or GBps. The default unit is MBps. For example: --write-rate-limit=1GBps or --write-rate-limit=100 (MBps). The default value is 0 — no limitation.

If this option is specified, the following information is displayed at the end of the backup:

  • written — the amount of data written, in MB.

  • total time — the time that elapsed between the first and last writes, in seconds. Note that this is not the total backup time.

  • sleep time — the amount of forced delay time, in seconds.

  • average rate — the actual average write rate, in MBps.

For example:

INFO: Rate limit: written 14975.445 MB, total time 17.163 s, sleep time 2.370 s, average rate 872.560715 MBps

--archive-timeout=wait_time

Sets the timeout for WAL segment archiving and streaming, in seconds. By default, pg_probackup waits 300 seconds.

Note

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

--skip-block-validation

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

--no-validate

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

--no-sync

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

--note=backup_note

Sets the text note for backup copy. If backup_note contain 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.

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

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

restore #

pg_probackup restore -B backup_dir --instance=instance_name
[--help] [--dry-run] [-D data_dir] [-i backup_id]
[-j num_threads] [--progress]
[-T OLDDIR=NEWDIR] [--external-mapping=OLDDIR=NEWDIR] [--skip-external-dirs]
[-R | --restore-as-replica] [--no-validate] [--skip-block-validation]
[--force] [--no-sync] [--allow-group-access]
[--restore-command=cmdline]
[--primary-conninfo=primary_conninfo]
[-S | --primary-slot-name=slot_name]
[-X wal_dir | --waldir=wal_dir]
[recovery_target_options] [logging_options] [remote_options]
[partial_restore_options] [remote_wal_archive_options]

Restores the Postgres Pro instance from a backup copy located in the backup_dir backup catalog. If you specify a recovery target option, pg_probackup finds the closest backup and restores it to the specified recovery target. If neither the backup ID nor recovery target options are provided, pg_probackup uses the most recent backup to perform the recovery.

-R
--restore-as-replica

Creates a minimal recovery configuration file to facilitate setting up a standby server. If the replication connection requires a password, you must specify the password manually in the primary_conninfo parameter as it is not included. For Postgres Pro 11 or lower, recovery settings are written into the recovery.conf file. Starting from Postgres Pro 12, pg_probackup writes these settings into the probackup_recovery.conf file in the data directory, and then includes them into the postgresql.auto.conf when the cluster is is started.

--primary-conninfo=primary_conninfo

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

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

-S
--primary-slot-name=slot_name

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

-T OLDDIR=NEWDIR
--tablespace-mapping=OLDDIR=NEWDIR

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

--external-mapping=OLDDIR=NEWDIR

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

--skip-external-dirs

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

--skip-block-validation

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

--no-validate

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

--allow-group-access

Provides any OS user in the same group as the cluster owner with the same access to the PGDATA directory on the database server as the cluster owner has. Running restore with this option will set the same permissions as when the cluster is created using the command

initdb ---g

--restore-command=cmdline

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

--force

Allows to ignore an invalid status of the backup. You can use this flag if you need to restore the Postgres Pro cluster from a corrupt or an invalid backup. Use with caution. If PGDATA contains a non-empty directory with system ID different from that of the backup being restored, incremental restore with this flag overwrites the directory contents (while an error occurs without the flag). If tablespaces are remapped through the --tablespace-mapping option into non-empty directories, the contents of such directories will be deleted.

--no-sync

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

-X wal_dir
--waldir=wal_dir

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

For more details of the command settings, see sections Common Options, Recovery Target Options, Remote Mode Options, Remote WAL Archive Options, Logging Options, and Partial Restore Options.

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

checkdb #

pg_probackup checkdb
[-B backup_dir] [--instance=instance_name] [-D data_dir]
[--help] [-j num_threads] [--progress]
[--amcheck [--skip-block-validation] [--checkunique] [--heapallindexed]]
[connection_options] [logging_options]

Verifies the Postgres Pro database cluster correctness by detecting physical and logical corruption.

--amcheck

Performs logical verification of indexes for the specified Postgres Pro instance if no corruption was found while checking data files. You must have the amcheck extension or the amcheck_next extension installed in the database to check its indexes. For databases without amcheck, index verification will be skipped. Additional options --checkunique and --heapallindexed are effective depending on the version of amcheck installed.

--checkunique

Verifies unique constraints during logical verification of indexes. You can use this flag only together with the --amcheck flag when the amcheck extension is installed in the database.

The verification of unique constraints is only possible if in the version of the amcheck extension you are using, the bt_index_check function takes the checkunique parameter.

--heapallindexed

Checks that all heap tuples that should be indexed are actually indexed. You can use this flag only together with the --amcheck flag.

This check is only possible if in the version of the amcheck/amcheck_next extension you are using, the bt_index_check function takes the heapallindexed parameter.

--skip-block-validation

Skip validation of data files. You can use this flag only together with the --amcheck flag, so that only logical verification of indexes is performed.

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

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

validate #

pg_probackup validate -B backup_dir
[--help] [--instance=instance_name] [-i backup_id]
[-j num_threads] [--progress] [--wal]
[--skip-block-validation]
[recovery_target_options] [logging_options]

Verifies that all the files required to restore the cluster are present and are not corrupt. If instance_name is not specified, pg_probackup validates all backups available in the backup catalog. If you specify the instance_name without any additional options, pg_probackup validates all the backups available for this backup instance. If you specify the instance_name with a recovery target option and/or a backup_id, pg_probackup checks whether it is possible to restore the cluster using these options. If the --wal option is specified, full check of the WAL archive will be performed instead of only checking WAL segments needed to restore the cluster.

For details, see the section Validating a Backup.

merge #

pg_probackup merge -B backup_dir --instance=instance_name -i backup_id
[--dry-run] [--help] [-j num_threads] [--progress] [--no-validate] [--no-sync]
[logging_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.

--no-validate

Skips automatic validation before and after merge.

--no-sync

Do not sync merged files to disk. You can use this flag to speed up the merge process. Using this flag can result in data corruption in case of operating system or hardware crash.

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

delete #

pg_probackup delete -B backup_dir --instance=instance_name
[--help] [-j num_threads] [--progress]
[--retention-redundancy=redundancy][--retention-window=window][--wal-depth=wal_depth] [--delete-wal]
{-i backup_id | --delete-expired [--merge-expired] | --merge-expired | --status=backup_status}
[--dry-run] [--no-validate] [--no-sync] [logging_options]

Deletes backup with specified backup_id or launches the retention purge of backups and archived WAL that do not satisfy the current retention policies.

--no-validate

Skips automatic validation before and after retention merge.

--no-sync

Do not sync merged files to disk. You can use this flag to speed up the retention merge process. Using this flag can result in data corruption in case of operating system or hardware crash.

For details, see the sections Deleting Backups, Retention Options, and Configuring Retention Policy.

archive-push #

pg_probackup archive-push -B backup_dir --instance=instance_name
--wal-file-name=wal_file_name [--wal-file-path=wal_file_path]
[--help] [--dry-run] [--no-sync] [--compress] [--no-ready-rename] [--overwrite]
[-j num_threads] [--batch-size=batch_size]
[--archive-timeout=timeout]
[--compress-algorithm=compression_algorithm]
[--compress-level=compression_level]
[remote_options] [logging_options]

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

If the files to be copied already exists in the backup catalog, pg_probackup 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. If you would like to replace WAL files in the case of checksum mismatch, run the archive-push command with the --overwrite flag.

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

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

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.

archive-get #

pg_probackup archive-get -B backup_dir --instance=instance_name --wal-file-path=wal_file_path --wal-file-name=wal_file_name
[-j num_threads] [--batch-size=batch_size]
[--prefetch-dir=prefetch_dir_path] [--no-validate-wal]
[--dry-run] [--help] [remote_options] [logging_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_probackup as part of the restore_command when restoring backups using a WAL archive. You do not need to set it manually.

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

restore_command = 'pg_probackup 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_probackup archive-get -B /backup --instance=main --wal-file-path=/var/lib/pgsql/data/pg_wal/RECOVERYXLOG --wal-file-name=000000010000000000000001

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

pg_probackup 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 option is used, then you can also specify the -j option to copy the batch of WAL segments on multiple threads.

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

catchup #

pg_probackup catchup -b catchup_mode
--source-pgdata=path_to_pgdata_on_remote_server
--destination-pgdata=path_to_local_dir
[--help] [-j | --threads=num_threads] [--dry-run]
[--write-rate-limit=bitrate]
[--stream [--temp-slot[=true|false|on|off]] [-P | --perm-slot] [-S | --slot=slot_name]]
[--exclude-path=PATHNAME]
[-T OLDDIR=NEWDIR]
[-X | --waldir=wal_dir]
[connection_options] [remote_options]
[logging_options]

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

-b catchup_mode
--backup-mode=catchup_mode

Specifies the catchup mode to use. Possible values are: FULL, DELTA, and PTRACK.

--source-pgdata=path_to_pgdata_on_remote_server

Specifies the path to the data directory of the instance to be copied. The path can be local or remote.

--destination-pgdata=path_to_local_dir

Specifies the path to the local data directory to copy to.

-j num_threads
--threads=num_threads

Sets the number of parallel threads for catchup process.

--stream

Copies the instance in STREAM WAL delivery mode, including all the necessary WAL files by streaming them from the server via replication protocol. For catchup, it is enabled by default.

--write-rate-limit=bitrate

Sets the rate of writing data to disk, in MBps or GBps. The default unit is MBps. For example: --write-rate-limit=1GBps or --write-rate-limit=100 (MBps). The default value is 0 — no limitation.

If this option is specified, the following information is displayed at the end of the catchup operation:

  • written — the amount of data written, in MB.

  • total time — the time that elapsed between the first and last writes, in seconds. Note that this is not the total duration of the catchup operation.

  • sleep time — the amount of forced delay time, in seconds.

  • average rate — the actual average write rate, in MBps.

For example:

INFO: Rate limit: written 14975.445 MB, total time 17.163 s, sleep time 2.370 s, average rate 872.560715 MBps

-x=path_prefix
--exclude-path=path_prefix

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

Warning

This option is dangerous since excluding files from synchronization can result in incomplete synchronization; use with care.

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

Creates a temporary physical replication slot for streaming WAL from the Postgres Pro instance being copied. --temp-slot is enabled by default. It ensures that all the required WAL segments remain available if WAL is rotated while the backup is in progress. This flag can only be used together with the --stream flag and cannot be used together with the --perm-slot flag. The default slot name is pg_probackup_slot. To change it, use the --slot/-S option and explicitly specify --temp-slot or --temp-slot=true|on.

-P
--perm-slot

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

-S slot_name
--slot=slot_name

Specifies the replication slot to connect to for WAL streaming. This option can only be used together with the --stream flag.

-T OLDDIR=NEWDIR
--tablespace-mapping=OLDDIR=NEWDIR

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

-X wal_dir
--waldir=wal_dir

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

For more details of the command settings, see sections Common Options, Connection Options, and Remote Mode Options.

For details on usage, see the section Cloning and Synchronizing Postgres Pro Instance.

maintain #

pg_probackup maintain --B backup_dir --instance=instance_name
[-i backup_id] --status-sync [--help] [--dry-run]
[--log-level-console=log-level-console] [--log-level-file=log-level-file]
[--log-format-console=log-format-console] [--log-format-file=log-format-file]
[--log-filename=log-filename]

Performs a cleanup of the directory with backups of the specified instance after a forced termination of previous pg_probackup commands.

--status-sync

Detects expired locks and hanging backups, as well as updates backup statuses.

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

Options #

This section describes command-line options for pg_probackup 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_probackup.conf configuration file located in the backup catalog.

For details, see the section called “Configuring pg_probackup”.

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

Common Options #

The list of general options.

--dry-run

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

-B directory
--backup-path=directory
BACKUP_PATH

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

-D directory
--pgdata=directory
PGDATA

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

-i backup_id
--backup-id=backup_id

Specifies the unique identifier of the backup.

--instance instance_name

Specifies the name of the Postgres Pro instance.

-j num_threads
--threads=num_threads

Sets the number of parallel threads for backup, restore, merge, validate, checkdb, and archive-push processes.

--progress

Shows the progress of operations.

--help

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

Recovery Target Options #

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

--recovery-target=immediate|latest

Defines when to stop the recovery:

  • The immediate value stops the recovery after reaching the consistent state of the specified backup, or the latest available backup if the -i/--backup-id option is omitted. This is the default behavior for STREAM backups.

  • The latest value continues the recovery until all WAL segments available in the archive are applied. Setting this value of --recovery-target also sets --recovery-target-timeline to latest.

--recovery-target-timeline=timeline

Specifies a particular timeline to be used for recovery:

  • current — the timeline of the specified backup, default.

  • latest — the timeline of the latest available backup.

  • A numeric value.

--recovery-target-lsn=lsn

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

--recovery-target-name=recovery_target_name

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

--recovery-target-time=time

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

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

--recovery-target-xid=xid

Specifies the transaction ID up to which recovery will proceed.

--recovery-target-inclusive=boolean

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

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

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

Default: pause

Retention Options #

You can use these options together with backup and delete commands.

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

--retention-redundancy=redundancy

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

Default: 0

--retention-window=window

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

Default: 0

--wal-depth=wal_depth

Number of latest valid backups on every timeline that must retain the ability to perform PITR. Must be a non-negative integer. The zero value disables this setting.

Default: 0

--delete-wal

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

--delete-expired

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

--merge-expired

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

--dry-run

Displays the current status of all the available backups, without deleting or merging expired backups, if any.

Pinning Options #

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

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

--ttl=ttl

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

Example: --ttl=30d

--expire-time=time

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

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

Logging Options #

You can use these options with any command.

--no-color

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

--log-level-console=log_level

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

Default: info

Note

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

--log-level-file=log_level

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

Default: off

--log-filename=log_filename

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

Default: pg_probackup.log

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

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

--error-log-filename=error_log_filename

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

Default: none

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

This option is useful for troubleshooting and monitoring.

--log-directory=log_directory

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

Default: $BACKUP_PATH/log/

--log-format-console=log_format

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

  • plain — sets the plain-text format of the console log.

  • json — sets the JSON format of the console log.

Default: plain

--log-format-file=log_format

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

  • plain — sets the plain-text format of log files.

  • json — sets the JSON format of log files.

Default: plain

--log-rotation-size=log_rotation_size

Maximum size of an individual log file. If this value is reached, the log file is rotated once a pg_probackup command is launched, except help and version commands. The zero value disables size-based rotation. Supported units: kB, MB, GB, TB (kB by default).

Default: 0

--log-rotation-age=log_rotation_age

Maximum lifetime of an individual log file. If this value is reached, the log file is rotated once a pg_probackup command is launched, except help and version commands. The time of the last log file creation is stored in $BACKUP_PATH/log/log_rotation. The zero value disables time-based rotation. Supported units: ms, s, min, h, d (min by default).

Default: 0

Connection Options #

You can use these options together with backup, catchup, and checkdb commands.

All libpq environment variables are supported.

-d dbname
--pgdatabase=dbname
PGDATABASE

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

-h host
--pghost=host
PGHOST

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

Default: localhost

-p port
--pgport=port
PGPORT

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

Default: 5432

-U username
--pguser=username
PGUSER

User name to connect as.

-w
--no-password

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

-W
--password

Forces a password prompt. (Deprecated)

Compression Options #

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

--compress-algorithm=compression_algorithm

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

Note

pg_probackup supports compression algorithms included in the Postgres Pro version. In particular:

  • lz4 is supported for Postgres Pro 14 and higher.

  • zstd is supported for Postgres Pro 15 and higher.

Default: none

--compress-level=compression_level

Defines the compression level. This option can be used together with the --compress-algorithm option. Possible values depend on the compression algorithm specified:

  • 0 — 9 for zlib

  • 1 for pglz

  • 0 — 12 for lz4

  • -131072 — 22 for zstd

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

Note

The pure lz4 algorithmn has only one compression level — 1. So, if the specified compression algorithm is lz4 and --compress-level is greater than 1, the lz4hc algorithm is actually used, which is much slower although does better compression.

Default: 1

--compress

Specifies the default compression algorithm and --compress-level=1. The default algorithm is selected among those supported by Postgres Pro according to the priorities: zstd (highest) -> lz4 -> zlib -> pglz. The --compress option overrides the --compression-algorithm and --compress-level settings and cannot be specified together with them.

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, remote mode options and logging options can be used.

--wal-file-path=wal_file_path

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

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

Note

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

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

--wal-file-name=wal_file_name

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

--overwrite

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

--batch-size=batch_size

Used to speed up archiving in case of archive-push or to speed up recovery in case of archive-get. Sets the maximum number of WAL files that can be copied into the archive by a single archive-push process, or from the archive by a single archive-get process.

--archive-timeout=wait_time

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

--no-ready-rename

Do not rename status files in the archive_status directory. This option should be used only if archive_command contains multiple commands. This option can be used only with archive-push command.

--no-sync

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

--prefetch-dir=path

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

--no-validate-wal

Do not validate prefetched WAL file before using it. Use this option if you want to increase the speed of recovery. This option can be used only with archive-get command.

Remote Mode Options #

This section describes the options related to running pg_probackup operations remotely via SSH. These options can be used with add-instance, set-config, backup, catchup, restore, archive-push, and archive-get commands.

For details on configuring and using the remote mode, see the section called “Configuring the Remote Mode” and the section called “Using pg_probackup in the Remote Mode”.

--remote-proto=proto

Specifies the protocol to use for remote operations. Currently only the SSH protocol is supported. Possible values are:

  • ssh enables the remote mode via SSH. This is the default value.

  • none explicitly disables the remote mode.

You can omit this option if the --remote-host option is specified.

--remote-host=destination

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

--remote-port=port

Specifies the remote host port to connect to.

Default: 22

--remote-user=username

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

--remote-path=path

Specifies pg_probackup installation directory on the remote system.

--ssh-options=ssh_options

Provides a string of SSH command-line options. For example, the following options can be used to set keep-alive for SSH connections opened by pg_probackup: --ssh-options="-o ServerAliveCountMax=5 -o ServerAliveInterval=60". For the full list of possible options, see ssh_config manual page.

Remote WAL Archive Options #

This section describes the options used to provide the arguments for remote mode options in archive-get used in the restore_command command when restoring ARCHIVE backups or performing PITR.

--archive-host=destination

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

--archive-port=port

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

Default: 22

--archive-user=username

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

Default: Postgres Pro user

Incremental Restore Options #

This section describes the options for incremental cluster restore. These options can be used with the restore command.

-I incremental_mode
--incremental-mode=incremental_mode

Specifies the incremental mode to be used. Possible values are:

  • CHECKSUM — replace only pages with mismatched checksum and LSN.

  • LSN — replace only pages with LSN greater than point of divergence.

  • NONE — regular restore.

Partial Restore Options #

This section describes the options for partial cluster restore. These options can be used with the restore command.

--db-exclude=dbname

Specifies the name of the database to exclude from restore. All other databases in the cluster will be restored as usual, including template0 and template1. This option can be specified multiple times for multiple databases.

--db-include=dbname

Specifies the name of the database to restore from a backup. All other databases in the cluster will not be restored, with the exception of template0 and template1. This option can be specified multiple times for multiple databases.

Testing and Debugging Options #

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

PGPROBACKUP_TESTS_SKIP_HIDDEN

Instructs pg_probackup to ignore backups marked as hidden. Note that pg_probackup can never mark a backup as hidden. It can only be done by directly editing the backup.control file. This option can only be set with environment variables.

--destroy-all-other-dbs

By default, pg_probackup exits with an error if an attempt is made to perform a partial incremental restore since this destroys databases not included in the restore set. This flag allows you to suppress the error and proceed with the partial incremental restore (e.g., to keep a development database snapshot up-to-date with a production one). This option can be used with the restore command.

Important

Never use this flag in a production cluster.

--lock-lifetime

Specifies the lifetime for locks taken when performing a backup, in seconds. The default value is 300. The minimum value is 60.

PGPROBACKUP_TESTS_SKIP_EMPTY_COMMIT

Instructs pg_probackup to skip empty commits after pg_backup_stop.

Versioning #

pg_probackup follows semantic versioning.

Authors #

Postgres Professional, Moscow, Russia.

Credits #

pg_probackup utility is based on pg_arman, which was originally written by NTT and then developed and maintained by Michael Paquier.

FAQ