Инструмент резервного копирования qbackup

qbackup — инструмент для управления резервным копированием и восстановлением кластеров баз данных QHB.

Синтаксис


qbackup help [команда]

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

qbackup backup -B каталог_копий [-D каталог_данных] [--incremental]
        [--compress] [--direct] [параметр...]

qbackup replica -D каталог_данных [параметр...]

qbackup restore -B каталог_копий -D каталог_данных
        -i идентификатор_копии [--connection] [параметр...]

qbackup remove -B каталог_копий -i идентификатор_копии ...
        [--single] [параметр...]

qbackup validate -B каталог_копий -i идентификатор_копии
        [-D каталог_данных] [-t тип_проверки] [параметр...]

qbackup backup-wal -B каталог_копий -D каталог_данных [--compress] -p путь_файла_wal
        -f имя_файла_wal [параметр...]

qbackup restore-wal -p путь_файла_wal
        -f путь_для_файла_wal [параметр...]

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

Постраничное инкрементальное копирование: позволяет сэкономить место на диске и создавать копии быстрее, чем при полном копировании. Восстановление инкрементальных копий также осуществляется быстрее, чем воспроизведение файлов WAL.
Реализация создания кумулятивной инкрементальной резервной копии с возможностью выбора родителя для инкрементального бэкапа.
Параллельное выполнение: выполнение внутренних процессов команд backup и restore в несколько параллельных потоков.
Сжатие: хранение копируемых данных в сжатом состоянии для экономии дискового пространства.
Каталогизация резервных копий: получение списка резервных копий и соответствующей метаинформации в виде простого текста или JSON.
Расширенные возможности работы с удаленным резервным копированием.
Для потокового (stream) резервного копирования используется протокол репликации.
Возможность удаленного восстановления из резервной копии.
Расширенные возможности валидации резервных копий и восстановленных кластеров.

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

Используя qbackup в режиме потокового (stream) резервного копирования, вы можете выполнять полное или инкрементальное резервное копирование с локального кластера, а также с удаленного:

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

qbackup в режиме прямого (direct) резервного копирования может производить полное копирование как работающего, так и остановленного экземпляра. Для копирования WAL используются внутренние механизмы QHB (см. подраздел скрипты archive_command).

Ограничения применимости

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

qbackup работает с серверами QHB версии 1.5.1 и новее.
На сервере QHB, где была сделана копия, и на сервере, где она будет восстанавливаться, должны быть одинаковые значения параметров block_size и wal_block_size и одинаковая основная версия. В зависимости от конфигурации кластера, QHB может накладывать дополнительные ограничения, например, по архитектуре процессора и версии libc/libicu.
Прямое (direct) резервное копирование предусмотрено только для создания локальных полных резервных копий. Для инкрементального бэкапирования используется потоковое (stream) резервное копирование как для локального, так и для удаленного хоста.
Невозможно сделать потоковую (stream) резервную копию на остановленном сервере. Для этого предусмотрено резервное копирование в режиме direct, которое не требует обязательного подключения к базе.
Инкрементальные резервные копии невозможно базировать на резервных копиях, созданных на остановленном сервере.
После включении CDC для инкрементального бэкапирования необходимо предварительно сделать полную резервную копию для корректного последующего захвата изменений данных.

Термины

Каталог копий — директория с резервными копиями. Внутри нее могут содержаться директории с резервными копиями, информация о них в файле каталога catalog.json и директория wal. Директорию каталога нужно создать до начала резервного копирования.

Каталог данных — директория с кластером баз данных.

Следующие поля в файле каталога копий являются служебными, но могут быть полезны. Они меняются с каждой дополнительной версией QHB:

Версия кластера (cluster_version) — бинарная версия QHB. Это номер сборки базы данных.
Версия qbackup (qbackup_version).

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

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

Создайте каталог копий.
Настройте кластер баз данных для использования qbackup.
Настройте SSH для выполнения удаленного восстановления из резервных копий, если вы планируете использовать данную функциональность.

Создание каталога копий

qbackup хранит резервные копии в каталоге копий, путь к которому указывается в переменной среды BACKUPS_DIR или в аргументе командной строки -B (--backups-dir). Каталог копий должен быть создан пользователем перед началом работы с утилитой и не должен содержать никаких файлов. Ручное редактирование файлов в каталоге копий не допускается. Пользователь, запускающий qbackup, должен иметь полный доступ к каталогу_копий и как минимум доступ на чтение всего содержимого каталога_данных.

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

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

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

Настройки для использования qbackup в режиме прямого (direct) резервного копирования

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

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

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.qhb_start_backup(text, boolean, boolean) TO backup;
GRANT EXECUTE ON FUNCTION pg_catalog.qhb_stop_backup(boolean, boolean) TO backup;
COMMIT;

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

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

Настройки для использования qbackup в режиме потокового (stream) резервного копирования

Программа qbackup в режиме stream позволяет получить копию кластера базы данных с удаленного или локального сервера по сети, используя протокол репликации. Если вы используете qbackup через отдельного пользователя (например, backup), не забудьте дать ему роль REPLICATION в базе данных и соответствующие права в qhb_hba.conf.

Пример:

CREATE USER backup REPLICATION PASSWORD 'backup';

В файле qhb_hba.conf разрешите выполнение репликации для роли backup:

# qhb_hba.conf
host replication backup <master_ip> md5
host replication backup <standby_ip> md5
host all backup <master_ip> md5
host all backup <standby_ip> md5

В файле qhb.conf установите в параметре wal_level значение выше minimal.

Пример:

# qhb.conf
wal_level='replica'

Для потокового резервного копирования предусмотрены полное и инкрементальное бэкапирование (в том числе удаленное) на включенной СУБД. Для инкрементальных резервных копий реализован механизм CDC — захват изменения данных (Change Data Capture). Для использования CDC необходимо настроить параметр qcdc_registry_size. Он принимает размер в мегабайтах. После перезапуска базы данных в ее корне появится файл qhb-cdc.map с указанным размером. Размер может быть любым в указанных далее пределах; для оптимальной работы следует выбирать его исходя из правила: предполагаемый размер кластера / 1000. Максимальное значение этого параметра — 10 Гб (10240 Мб), минимальное — 1 Мб. При значении 0 CDC считается выключенным.

Пример:

# qhb.conf
# Предполагаемый размер кластера — 30GB
qcdc_registry_size=30MB

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

В режиме потокового резервного копирования все необходимые файлы WAL будут автоматически архивированы (см. параграф варианты архивации).

ВНИМАНИЕ!
При наличии шифрованных таблиц в базе данных не рекомендуется использовать потоковое резервное копирование с указанием wal-method=stream. Для формирования зашифрованной потоковой резервной копии требуется наличие непрерывной архивации WAL и потокового резервного копирования в режиме wal-method=fetch или wal-method=none.

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

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

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

Чтобы настроить непрерывное архивирование через программу qbackup, модифицируйте файл конфигурации qhb.conf:

Установите в параметре wal_level значение выше minimal.
Установите в параметре archive_mode значение on или always.
Установите параметр archive_command:
```
archive_command='путь_установки/qbackup backup-wal
  -B каталог_копий -f %f -p %p'
```
Здесь путь_установки — путь к каталогу установленной версии qbackup, которую вы хотите использовать.

В результате команды qbackup backup-wal все сегменты WAL будут располагаться в директории каталог_копий/wal. Подкаталог /wal будет сформирован автоматически после начала работы.

Примечание
Вместо команды qbackup backup-wal можно воспользоваться любым другим средством при условии, что в процессе непрерывного архивирования сегменты WAL будут попадать в каталог каталог_копий/wal.

Пример возможной конфигурации для копирования работающего кластера:

# qhb.conf
wal_level='replica'
archive_mode='on'
archive_command='/usr/bin/qbackup backup-wal -B /opt/backup_dir -f %f -p %p'

Установка archive_command необходима для прямого (direct) резервного копирования работающего кластера. Для копирования остановленного кластера этот параметр устанавливать не требуется. Для потокового резервного копирования или при использовании подкоманды replica параметры archive_mode и archive_command можно не настраивать. Все необходимые файлы WAL будут автоматически архивированы (возможны варианты архивации). Подробнее о параметрах для репликации, указываемых в qhb.conf, можно прочитать в подразделе Репликация.

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

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

на основном сервере в qhb.conf установите для параметра full_page_writes значение on и ненулевое значение для параметра archive_timeout;
на резервном сервере в qhb.conf установите для параметра archive_mode значение always, а для параметра hot_standby — on.

Пример:

# qhb.conf
full_page_writes = on
hot_standby = on
# Следующий параметр обязателен для резервного сервера, если предполагается архивация WAL
archive_mode = always

Для получения самодостаточных копий с резервного сервера выполните действия, описанные в подразделе Настройки для использования qbackup в режиме потокового (stream) резервного копирования.

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

После этих подготовительных действий вы можете делать резервные копии с резервного сервера в режимах stream и direct.

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

Если резервный сервер повышается до ведущего во время копирования, копирование прерывается с ошибкой.
На основном сервере необходимо установить ненулевой параметр archive_timeout. Это связано с тем, что утилита qbackup на резервном сервере ожидает переключения сегмента WAL на основном сервере для возможности завершить архивацию на резервном сервере. В противном случае выводится уведомление:
```
Warning! Still waiting for all required wal segments to be archived.
# Предупреждение! Все еще ожидаю завершения архивации всех требуемых сегментов WAL.
```
Все необходимые для резервной копии записи WAL должны содержать полные страницы. Для этого требуется включить режим full_page_writes на основном сервере и отказаться от использования в archive_command утилит, удаляющих полные страницы из файлов WAL.
Чтобы qbackup на резервном сервере смогла отправить команду переключения сегмента WAL на основной сервер, необходимо предоставить права на переключение сегмента пользователю, который отвечает за репликацию, например, пользователю repluser. Какой пользователь отвечает за репликацию, можно увидеть в qhb.auto.conf.
```
GRANT execute ON function pg_switch_wal TO repluser
```

Настройка SSH для выполнения удаленного восстановления

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

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

Установите qbackup в обеих системах: backup_host (сервер резервного копирования) и db_host (сервер баз данных). На удаленном компьютере qbackup должна находиться в таком месте, чтобы она могла запускаться без указания пути к программе
Для организации связи между узлами настройте SSH-соединение без пароля для подключения пользователя (например, backup) на компьютере backup_host к серверу db_host под именем qhb:
```
[backup@backup_host] ssh-keygen -t rsa
[backup@backup_host] ssh-copy-id -i ~/.ssh/id_rsa.pub qhb@db_host
```
При необходимости может потребоваться запустить ssh-агент вручную:
```
[backup@backup_host] eval `ssh-agent`
[backup@backup_host] ssh-add
```
Проверьте верность настроек с помощью попытки удаленного запуска на backup_host команды:
```
[backup@backup_host] ssh qhb@db_host qbackup apply-inc --help
```
Здесь:
- backup_host — система, в которой находится каталог копий.
- db_host — система, в которой функционирует кластер QHB.
- backup — пользователь в системе backup_host, от имени которого запускается qbackup.
- qhb — пользователь в системе db_host, от имени которого запускается кластер QHB.

В удаленном режиме восстановления qbackup работает следующим образом:

Основной процесс запускается в системе backup_host и подключается к системе db_host.
В процессе работы на db_host копируются файлы резервной копии, а файлы инкрементальных изменений накладываются путем вызова на db_host программы qbackup.
Если qbackup на db_host сталкивается с ошибкой, основной процесс qbackup выдает информацию о возникшей ошибке и завершает работу.
Распаковка сжатой резервной копии всегда осуществляется в системе backup_host.

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

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

Создание прямой (direct) резервной копии

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

qbackup backup -B каталог_копий -D каталог_данных --direct [--compress]
    [параметры подключения...] [параметр...]

Флаг --compress значительно уменьшает размер резервной копии, но может привести к замедлению процесса копирования.

Создание потоковой (stream) резервной копии

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

qbackup backup -B каталог_копий [--compress] [--incremental] [--from идентификатор_копии]
    [параметры подключения...] [параметр...]

qbackup в режиме stream (по умолчанию) поддерживает два основных типа создания резервных копий:

Полные копии. Содержимое каталога_данных копируется в каталог_копий, за исключением необязательных файлов. В каталоге_копий может содержаться любое количество независимых резервных копий.
Инкрементальные копии. При передаче флага --incremental qbackup запрашивает у сервера данные об изменившихся файлах и на основе этих данных создает резервную копию. В инкрементальной копии хранятся только те файлы (или части файлов), которые изменились с момента создания полной копии. Это значительно сокращает размер резервной копии, но может потребовать больше времени для выполнения операций сравнения файлов. (Это экспериментальная функция, но, несмотря на это, резервные копии всегда будут согласованными.) Обратите внимание, что инкрементальные резервные копии могут создаваться продолжительное время и иметь большой размер.

При восстановлении кластера из инкрементальной копии qbackup использует родительскую полную копию и все инкрементальные копии между ними, в совокупности образующие «цепочку копий». Таким образом, прежде чем делать инкрементальные копии, необходимо сделать как минимум одну полную, причем после включения CDC.

Флаг --from применяется для создания дополнительной цепи резервных копий. Применяется только для инкрементальных резервных копий для выбора, на основе какой из копий (любых полных или инкрементальных) будет сделан инкремент. Также этот флаг необходим, если восстановлению подлежала не последняя резервная копия из цепочки; в таком случае для продолжения инкрементального бэкапирования необходимо указать --from id_восстановленного_бэкапа. Последующие инкрементальные резервные копии могут быть созданы без дополнительного параметра --from. Подробнее можно ознакомиться в подразделе Дополнительные параметры для команды backup.

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

qbackup поддерживает протокол репликации для получения резервных копий с удаленного сервера.

Создание реплики кластера

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

qbackup replica -D каталог_данных [--compress] [параметры подключения...]
    [параметры репликации...] [параметр...]

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

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

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

qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии [--tablespace-mapping старый_путь=новый_путь] [--connection] [--wal-directory] [параметры...]

Здесь:

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

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

Параметр --wal-directory используется для переопределения директории расположения архива WAL файлов, если она отличалась от каталога_копий. См. описание параметра --wal-directory ниже.

См. описание параметра --tablespace-mapping ниже.

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

ВАЖНО
Восстановление по умолчанию осуществляется до последнего LSN в бэкапе. При наличии непрерывного архива wal можно восстановить до последнего существующего в архиве LSN через указание --target-lsn=latest.

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

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

Чтобы восстановить состояние кластера на определенный момент времени, укажите это время в параметре --target-time, в формате timestamp. Например:
```
qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии --target-time='2017-05-18 14:18:11+03'
```
Чтобы восстановить состояние кластера до определенной транзакции, воспользуйтесь параметром --target-xid. Например:
```
qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии --target-xid=687
```
Чтобы восстановить состояние кластера до определенной позиции в журнале (LSN), воспользуйтесь параметром --target-lsn. Например:
```
qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии --target-lsn=16/B374D848
```

Примечание
При указании --target-lsn=latest восстановление будет осуществлено до последнего LSN в непрерывном архиве wal.

Чтобы восстановить состояние кластера до заданной именованной точки восстановления, воспользуйтесь параметром --target-name. Например:
```
qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии --target-name='before_app_upgrade'
```
Чтобы восстановить самое раннее из возможных согласованное состояние кластера, укажите флаг --immediate:
```
qbackup restore -B каталог_копий -D каталог_данных
  -i идентификатор_копии --immediate
```

В дополнение к параметрам, устанавливающим точку восстановления, можно также указать параметры --action, --timeline и --inclusive.

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

Команда validate позволяет проверить (и в некоторых случая восстановить) целостность резервной копии, а также восстановленного кластера. Существует три вида проверки:

checksum (режим по умолчанию)

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

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

qhb-checksum

Позволяет проверить контрольные суммы файлов таблиц баз данных. Эта функция аналогична qhb_checksums за исключением того, что данный режим работает с каталогизированными qbackup резервными копиями. Если резервная копия была сделана с включенными контрольными суммами, то данный вариант позволяет сверить их. Если контрольные суммы были выключены в кластере на момент резервного копирования, то флаг -e --enable позволяет включить их. Может использоваться исключительно на полных несжатых резервных копиях в режиме direct.

database

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

Пример:

$ qbackup backup -B /tmp/backup -h localhost -u user1 -fc # сетевая полная сжатая резервная копия ID: QZWGEI
$ qbackup backup -B /tmp/backup -h localhost -u user1 -fi # сетевая инкрементальная резервная копия ID: QZWGFJ

$ qbackup validate -B /tmp/cat -t checksum -i QZWGFJ # Проверка типа checksum
$ qbackup validate -B /tmp/cat -t qhbchecksum -i QZWGEI # Проверка типа qhb-checksum

$ qbackup restore -B /tmp/backup -i QZWGFJ -D /tmp/qhb-data/ # Восстановление

# Предположительное повреждение файла `/tmp/qhb-data/base/12677/175`

$ qbackup validate -B /tmp/backup -i QZWGFJ -D /tmp/qhb-data/ -t database # Проверка типа database
You are going to restore
/tmp/cat/QZWH7I/base/12677/175 into /tmp/qhb-data/base/12677/175
You are going to restore
/tmp/cat/QZWH7I/base/12677/175 into /tmp/qhb-data/base/12677/175
 yes

$ qbackup validate -B /tmp/backup -i QZWGFJ -D /tmp/qhb-data/ -t database # Проверка типа database (успешная)

При использовании режима проверки database можно использовать флаг -y --yes, позволяющий автоматически согласиться на восстановление

Примечание
В каких ситуациях восстановить файл не получится:

Повреждены одинаковые файлы внутри резервной копии и внутри кластера

Файл были изменен с помощью СУБД

Файл был полностью удален

В файле поврежден заголовок (информация о последнем изменении)

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

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

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

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

qbackup backup -B каталог_копий [-D каталог_данных] [--direct] [--compress] [--incremental] -j 4

По умолчанию или если заданное число потоков равно 0, qbackup автоматически выбирает число потоков, которое обеспечит максимальную производительность копирования (в ущерб другим операциям).

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

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

Просматривать имеющиеся резервные копии
Удалять резервные копии

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

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

qbackup list -B каталог_копий

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

+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+
|    ID    | status |   size   | compressed size |         kind         | start lsn |  parent  |         start time         |          end time          |  comment   |
+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+
| LE4D8X48 |  Done  | 43.26MiB |     5.24MiB     |    Full (Stream)     | 0/2000028 |    —     | 2023-02-14 17:55:14 +03:00 | 2023-02-14 17:55:29 +03:00 |     —      |
+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+
| LE4D99DU |  Done  | 25.49MiB |     1.82MiB     | Incremental (Stream) | 0/4000028 | LE4D8X48 | 2023-02-14 17:55:30 +03:00 | 2023-02-14 17:55:44 +03:00 |     —      |
+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+
| LE4D9L7B |  Done  | 25.49MiB |     1.81MiB     | Incremental (Stream) | 0/6000028 | LE4D99DU | 2023-02-14 17:55:45 +03:00 | 2023-02-14 17:55:59 +03:00 |     —      |
+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+
| LE4DB3RG |  Done  | 61.05MiB |     8.69MiB     |    Full (Direct)     | 0/8000028 |    —     | 2023-02-14 17:56:56 +03:00 | 2023-02-14 17:57:21 +03:00 | backup1402 |
+----------+--------+----------+-----------------+----------------------+-----------+----------+----------------------------+----------------------------+------------+

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

ID — уникальный идентификатор копии.

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

Done — резервная копия выполнена и готова к использованию;
In Progress — резервное копирование еще выполняется;
Error — резервное копирование завершилось с ошибкой;
Cancelled — резервное копирование отменено.

size — размер резервной копии (в несжатом виде).

compressed size — размер сжатой резервной копии (только для сжатых копий).

kind — тип резервной копии. Возможные варианты:

Full (Stream) — полная потоковая резервная копия;
Incremental (Stream) — инкрементальная потоковая резервная копия;
Full (Direct) — полная прямая резервная копия;

is compressed — сжата ли копия.

start lsn — LSN (Log Sequence Number, последовательный номер в журнале WAL) в момент начала копирования. Отсутствует для копий остановленного кластера.

parent — идентификатор предыдущей копии для инкрементальных копий;

start time — системное время начала резервного копирования;

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

Также можно получить информацию о резервных копиях в формате JSON:

qbackup list -B каталог_копий --json

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

[
  {
    "identifier": "LE8EH39A",
    "status": "Done",
    "size": 45364828,
    "compressed_size": 5498462,
    "kind": {
      "Full": "Stream"
    },
    "start_lsn": "0/2000028",
    "start_time": "2023-02-17T13:40:40+03:00",
    "end_time": "2023-02-17T13:40:55+03:00",
    "parent": null,
    "comment": null
  },
  {
    "identifier": "LE8EHFOO",
    "status": "Done",
    "size": 26723166,
    "compressed_size": 1911987,
    "kind": {
      "Incremental": "Stream"
    },
    "start_lsn": "0/4000028",
    "start_time": "2023-02-17T13:40:56+03:00",
    "end_time": "2023-02-17T13:41:10+03:00",
    "parent": "LE8EH39A",
    "comment": null
  },
  {
    "identifier": "LE8EHR4V",
    "status": "Done",
    "size": 26725616,
    "compressed_size": 1902556,
    "kind": {
      "Incremental": "Stream"
    },
    "start_lsn": "0/6000028",
    "start_time": "2023-02-17T13:41:11+03:00",
    "end_time": "2023-02-17T13:41:25+03:00",
    "parent": "LE8EHFOO",
    "comment": null
  }
]

Более подробную системную информацию можно получить в файле каталог_копий/catalog.json.

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

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

qbackup remove -B каталог_копий -i идентификатор_копии

Эта команда удалит резервную копию с заданным идентификатором_копии вместе со всеми инкрементальными копиями, которые от нее зависят (если таковые имеются). Таким образом вы можете удалить некоторые последние инкрементальные копии из «цепочки копий». В параметре -i можно передавать несколько идентификаторов через пробел. Перед удалением программа выводит информацию об удаляемых резервных копиях и требует дополнительного подтверждения; это можно выключить с помощью флага -y.

Подробнее о расширенных параметрах этой команды можно прочитать в подразделе Дополнительные параметры для команды remove.

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

Команды

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

help

qbackup help [команда]

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

Аналогичную роль выполняет флаг --help, доступный для любой из команд.

list

qbackup list -B каталог_копий [--json] [--help]

Показывает содержимое каталога копий.

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

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

backup

qbackup backup -B каталог_копий [-D каталог_данных] [--direct]
[--compress] [--incremental]
[--help] [-j число_потоков] [--progress] [параметры репликации...]

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

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

Подробнее о расширенных параметрах этой команды можно прочитать в подразделе Дополнительные параметры для команды backup.

restore

qbackup restore -B каталог_копий -D каталог_данных -i идентификатор_копии
[--help]
[-j число_потоков] [--progress] [--connection] [--wal-directory]
[параметры точки восстановления...]

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

Более подробно использование этой команды описывается в подразделе Восстановление кластера. Подробную информацию по параметрам точки восстановления см. в подразделе Выполнение восстановления на момент времени (PITR).

replica

qbackup replica -D каталог_данных
[--compress] [--help] [--progress] [параметры репликации...]

Создает реплику экземпляра QHB.

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

remove

qbackup remove -B каталог_копий -i идентификатор_копии [идентификатор_копии_2]... [--single]
[--help] [--progress]

Удаляет копию с заданным идентификатором_копии и все инкрементальные копии, которые от нее зависят. Если передан флаг --single, удаляет только указанную копию.

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

validate

qbackup validate -B каталог_копий -i идентификатор_копии [-D каталог_данных] [-t тип_проверки]
[--help] [--progress] [параметр...]

Проверяет корректность резервной копии с заданным идентификатором_копии. Существует три типа проверки: checksum, qhb-checksum и database; подробную информацию см в подразделе Проверка резервных копий.

backup-wal

qbackup backup-wal -B каталог_копий [--compress] --wal-file-name=имя_файла_wal --wal-file-path=путь_к_файлу_wal
[--help]

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

Флаг --compress значительно уменьшает размер архивированного WAL, но может привести к замедлению процесса копирования.

Команду backup-wal можно указать как значение параметра archive_command QHB при настройке непрерывного архивирования WAL. Подробную информацию см. в подразделе Настройка непрерывного архивирования WAL.

restore-wal

qbackup restore-wal --destination-wal-file-path=путь_и_имя_файла_wal --source-wal-file-path=путь_к_исходному_файлу_wal
[--help]

Копирует файлы WAL в соответствующий подкаталог с нужным именем.

Команда restore-wal автоматически используется как restore_command в qbackup.conf после восстановления.

Пример использования:

restore_command='qbackup restore-wal -f /tmp/catalog/wal/%f -p %p'

Параметры

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

Общие параметры поддерживаются большей частью команд qbackup.

-j
--threads
Позволяет указать количество потоков для операций, которые поддерживают параллельное выполнение (backup и restore).
По умолчанию, если значение параметра не установлено или равно 0, используется оптимальное число потоков для данной системы.

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

-v
--verbose
Выводит более подробную информацию о процессе выполнения операции.

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

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

Для подключения к базе необходимо указать ряд параметров. Обязательными для успешного подключения являются только два из них: имя пользователя и имя хоста базы. Необходимость остальных параметров определяется настройками кластера.

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

-u
--user
Имя пользователя базы, от имени которого выполняется копирование. Значение по умолчанию qhb.
Если установлена переменная среды QBACKUP_USER, используется ее значение. Параметр, указанный в командной строке, имеет приоритет над переменной среды.

-h
--host
Указывает имя хоста компьютера, на котором работает сервер. Если значение начинается со слэша, оно используется в качестве каталога для сокета домена Unix. Множественные имена хоста можно перечислить через запятую. Каждое из имен будет опробовано последовательно. Значение по умолчанию localhost.
Если установлена переменная среды QBACKUP_HOST, используется ее значение. Параметр, указанный в командной строке, имеет приоритет над переменной среды.

--db-name
Имя базы данных для подключения. По умолчанию соответствует имени пользователя.
Если установлена переменная среды QBACKUP_DBNAME, используется ее значение. Параметр, указанный в командной строке, имеет приоритет над переменной среды.

-p
--port
Порт для подключения к базе. Несколько портов можно перечислить через запятую.
Число указанных портов может быть равно 1, (в этом случае для всех хостов используется один и тот же порт), либо должно соответствовать указанному число хостов. Значение по умолчанию 5432.
Если установлена переменная среды QBACKUP_PORT, используется ее значение. Параметр, указанный в командной строке, имеет приоритет над переменной среды.

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

-w
--no-password
Никогда не входить в диалоговый режим для запроса пароля. Этот параметр может быть полезен в скриптах автоматизации.

Параметры подключения для удаленного восстановления

-C
--connection
Параметр подключения к удаленному хосту через ssh для восстановления из резервной копии.
Задается в формате -C user@ip:port при настроенном ssh-соединении между хостами. См. подраздел Настройка SSH для выполнения удаленного восстановления.

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

Для команды restore можно указать дополнительные параметры, регулирующие восстановление до определенной точки (PITR).

Используются только в команде restore.

--target-time=момент_времени
Восстановление до определенного момента времени в формате timestamp.
Значение этого параметра задается в том же формате, что принимается типом данных timestamp with time zone, за исключением того, что в нем нельзя использовать сокращенное название часового пояса. Поэтому рекомендуется задавать числовое смещение от UTC или записывать название часового пояса полностью, например, Europe/Helsinki (но не EEST).

--target-xid=xid_транзакции
Восстановление на определенный идентификатор транзакции.
Имейте в виду, что числовое значение идентификатора отражает последовательность именно старта транзакций, а фиксироваться они могут в ином порядке. Восстановлению будут подлежать все транзакции, которые были зафиксированы до указанной (и, возможно, включая ее, в зависимости от значения параметра --inclusive).

--target-lsn=[ latest | LSN ]
Восстановление на определенный LSN. Этот параметр принимает значение системного типа данных pg_lsn. С ключевым словом latest восстанавливаться будет до последнего LSN в архиве.

--target-name=имя_точки_восстановления
Восстановление на определенную именованную точку восстановления, созданную с помощью функции pg_create_restore_point().

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

--action=[ pause | promote | shutdown ]
Указывает, какое действие должен предпринять сервер после достижения цели восстановления. Вариант по умолчанию — pause, что означает приостановку восстановления. Второй вариант, promote, означает, что процесс восстановления завершится, и сервер начнет принимать подключения. Наконец, с вариантом shutdown сервер остановится, как только целевая точка восстановления будет достигнута.
Вариант pause позволяет выполнить запросы к базе данных и убедиться в том, что достигнутая цель оказалась желаемой точкой восстановления. Для снятия с паузы нужно вызвать функцию pg_wal_replay_resume(), что в итоге приведет к завершению восстановления. Если окажется, что желаемая точка восстановления еще не достигнута, нужно остановить сервер, установить более позднюю цель и перезапустить сервер для продолжения восстановления.
Вариант shutdown полезен для получения готового экземпляра сервера в желаемой точке. При этом данный экземпляр сможет воспроизводить дополнительные записи WAL (а при перезапуске ему придется воспроизводить записи WAL после последней контрольной точки).
Обратите внимание, что так как recovery.signal не переименовывается, когда в --action выбран вариант shutdown, при последующем запуске будет происходить немедленная остановка, пока вы не измените конфигурацию или не удалите файл recovery.signal вручную.
Этот параметр не действует, если целевая точка восстановления не установлена.

--timeline=[ current | latest | id_временной_шкалы ]
Указывает временную шкалу для восстановления. Значение может задаваться числовым идентификатором временной шкалы (id_временной_шкалы) или ключевым словом. С ключевым словом current восстанавливается та временная шкала, которая была активной при создании базовой резервной копии. С ключевым словом latest восстанавливаться будет последняя временная шкала, найденная в архиве, что полезно для резервного сервера. По умолчанию подразумевается latest.

--inclusive=[ on | off ]
Прекратить восстановление в момент достижения заданной точки (on) или непосредственно перед ее достижением (off). По умолчанию установлено on.

--wal-directory=каталог_архива_wal
Переопределить директорию с архивом WAL. Требуется при указании директории в archive_command, отличной от каталога_копий. По умолчанию параметр соответствует -B каталог_копий.

Дополнительные параметры копирования

-R
--write-recovery-conf
Записать строку подключения к основному серверу в qhb.auto.conf. Записывает параметры primary_slot_name и primary_conninfo. Это параметр по умолчанию; при ошибке подключения к основному серверу нужно отредактировать эти параметры вручную.

-r
--max-rate=максимальная_скорость
Ограничить скорость передачи файлов. Принимает суффиксы k — КБ и M - МБ. Принимает значения в пределах от 32 КБ/с до 1024 МБ/с.

-X
--wal-method=[ stream | fetch | none ]
Способ архивирования WAL-файлов во время репликации.
Здесь:

stream — архивировать WAL в отдельном потоке параллельно. Это значение по умолчанию. Файлы архивируются в $PGDATA/pg_wal/.
fetch — архивировать WAL вместе с файлами кластера. Они будут расположены внутри директории $PGDATA/pg_wal/.
none — не архивировать файлы WAL.

ВНИМАНИЕ!
При выборе метода none файлы WAL не будут архивироваться! Вам следует архивировать файлы WAL вручную, иначе резервная копия будет недействительна!

ВНИМАНИЕ!
При наличии шифрованных таблиц потоковый метод (wal-method=stream) использовать не рекомендуется.

-S
--slotname=имя_слота
Создать слот репликации для архивирования WAL-файлов. По умолчанию создается временный слот репликации, а данный параметр создает постоянный слот репликации. В случае, если слот имя_слота уже существует, то он будет использоваться для репликации, если же такого слота нет, то он будет создан.

Примечание
Имя слота репликации может включать в себя только английские буквы нижнего регистра (a-z), цифры (0-9) и символ нижнего подчеркивания (_).

-T
--tablespace-mapping старый_путь=новый_путь
Выполняет адресацию табличных пространств. Адресация — изменение оригинального пути директории табличного пространства на новый. Этот параметр можно указывать несколько раз.
Здесь:

старый_путь — оригинальный путь табличного пространства.
новый_путь — новый путь (путь адресации) табличного пространства.

Прочие параметры

Дополнительные параметры для команды backup

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

-c
--compress
Позволяет уменьшить размер резервной копии.

-f
--fast-checkpoint
Запрашивает выполнение быстрой контрольной точки вместо обычной. Применяется при резервном копировании с горячего сервера или при репликации.

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

-C
--comment
Позволяет добавить комментарий для резервной копии.

--no-checksum
Позволяет выключить подсчет контрольной суммы резервной копии. Применяйте, только если уверены, что осознаете все последствия.

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

Дополнительные параметры для команды remove

-y --yes
Позволяет удалить резервные копии без дополнительного предостережения.

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

--single
Позволяет удалить одну копию без удаления цепочки.

ВНИМАНИЕ!
После удаления резервной копии из цепочки все копии, сделанные позже нее, становятся недействительными!

Версионирование

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