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

Синтаксис

qbackup version

qbackup help [команда]

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

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

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

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

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

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

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

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

Описание

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

Обзор

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

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

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

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

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

  • Расширенные возможности работы с удаленным резервным копированием.

  • Расширенные возможности валидации резервных копий и восстановленных кластеров.

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

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

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

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

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

Ограничения

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

  • qbackup работает с серверами QHB версии 1.5.0 и новее.

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

  • Невозможно создавать сжатые инкрементальные копии, а также инкрементальные копии при удаленном резервном копировании.

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

Термины

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

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

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

  • Версия каталога (qbackup_version) — версия структуры данных в файле каталога.

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

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

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

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

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

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

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

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

BEGIN;
CREATE ROLE backup WITH LOGIN;
GRANT USAGE ON SCHEMA pg_catalog 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;
COMMIT;

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

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

Модифицируйте файл конфигурации qhb.conf:

  • Установите параметр wal_level в значение выше minimal.

  • Установите параметр archive_mode в значение on или always.

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

    archive_command='путь_инсталляции/qbackup backup-wal
      -B каталог_копий -f %f -p %p'
    

    Здесь путь_инсталляции — путь к каталогу установленной версии qbackup, которую вы хотите использовать.

Установка archive_command необходима для резервного копирования работающего кластера. Для копирования остановленного кластера устанавливать этот параметр не требуется.

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

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

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

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

  1. Бинарное сканирование файлов
  2. CDC — захват изменения данных (Change Data Capture)

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

Пример:

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

Если вы используете qbackup через отдельного пользователя, не забудьте дать ему права в qhb_hba.conf.

Пример:

CREATE USER repluser REPLICATION PASSWORD 'repluser';
# qhb_hba.conf
host replication repluser master_ip md5
host replication repluser standby_ip md5
host all repluser master_ip md5
host all repluser standby_ip md5

Если вы используете qbackup вместе с QDL, то обратите внимание на пункт ВАЖНО в шаге 3 раздела Сценарий использования QDL.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Здесь:

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

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

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

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

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

Выполнение восстановления на момент времени (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-name. Например:

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

    qbackup restore -B каталог_копий -D каталог_данных
      -i идентификатор_копии --immediate
    

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

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

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

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

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

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

QhbChecksum

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

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 # Проверка типа QhbChecksum

$ 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, позволяющий автоматически согласится на восстановление

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

  1. Повреждены одинаковые файлы внутри резервной копии и внутри кластера
  2. Файл были изменён с помощью СУБД
  3. Файл был полностью удалён
  4. В файле повреждён заголовок (информация о последнем изменении)

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

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

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

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

qbackup backup -B каталог_копий -D каталог_данных [--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 |
+--------+--------+----------+-----------------+------------------------+-----------+--------+---------------------+---------------------+---------+
| QYAEEO |  Done  | 30.87MiB |        —        |    Full (Physical)     | 0/2000028 |   —    | 2021-08-23 09:59:12 | 2021-08-23 09:59:12 | Planned |
+--------+--------+----------+-----------------+------------------------+-----------+--------+---------------------+---------------------+---------+
| QYAEFN |  Done  | 73.64KiB |        —        | Incremental (Physical) | 0/4000028 | QYAEEO | 2021-08-23 09:59:47 | 2021-08-23 09:59:47 |    —    |
+--------+--------+----------+-----------------+------------------------+-----------+--------+---------------------+---------------------+---------+
| QYAEGO |  Done  | 30.87MiB |     4.68MiB     |    Full (Physical)     | 0/6000028 |   —    | 2021-08-23 10:00:24 | 2021-08-23 10:00:24 |    —    |
+--------+--------+----------+-----------------+------------------------+-----------+--------+---------------------+---------------------+---------+
| QYAEM1 | Error  |    0B    |        —        |     Full (Remote)      |     —     |   —    | 2021-08-23 10:03:37 | 2021-08-23 10:03:37 |    —    |
+--------+--------+----------+-----------------+------------------------+-----------+--------+---------------------+---------------------+---------+

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

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

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

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

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

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

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

  • Full (Physical) — полная физическая резервная копия;
  • Incremental (Physical) — инкрементальная физическая резервная копия;
  • Full (Remote) — полная удаленная резервная копия;
  • Incremental (Remote) — инкрементальная удаленная резервная копия.

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

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

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

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

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

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

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

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

[
    {
        "identifier": "QSZR4B",
        "status": "Ok",
        "size": 32138205,
        "compressed_size": 4793242,
        "compressed": true,
        "kind": {
            "Full": "Remote"
        },
        "start_lsn": "0/6000028",
        "start_time": "2021-05-12T11:12:11.215543311Z",
        "end_time": "2021-05-12T11:12:11.634187960Z",
        "parent": null
    },
    {
        "identifier": "QSZRC1",
        "status": {
            "Error": "The database is in active state but connection parameters were not supplied"
        },
        "size": 0,
        "compressed_size": null,
        "compressed": false,
        "kind": {
            "Full": "Physical"
        },
        "start_lsn": null,
        "start_time": "2021-05-12T11:16:49.101115677Z",
        "end_time": "2021-05-12T11:16:49.108127415Z",
        "parent": null
    }
]

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

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

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

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

Подробнее о расширенных параметрах можно прочитать в дополнительные параметры

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

Команды

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

version

qbackup version

Выводит версию qbackup.

help

qbackup help [команда]

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

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

list

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

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

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

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

backup

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

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

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

Подробнее о расширенных параметрах можно прочитать в дополнительные параметры

restore

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

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

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

replica

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

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

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

remove

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

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

Подробнее о расширенных параметрах можно прочитать в дополнительные параметры

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

validate

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

Проверяет корректность резервной копии с идентификатором (идентификатор_копии). Существует три типа проверки: Checksum, QhbChecksum, Database, читайте подробнее в Валидирование резервных копий

backup-wal

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

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

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

restore-wal

qbackup restore-wal -B каталог_копий --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 -B /tmp/catalog'

Параметры

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

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

-j
--threads

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

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

-P
--progress

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

-v
--verbose

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

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

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

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

-u
--user

Имя пользователя базы, от имени которого выполняется копирование.

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

-h
--host

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

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

--db-name

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

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

-p
--port

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

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

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

--password

Пароль пользователя для подключения к базе.

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

-w
--no-password

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

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

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

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

--target-time=момент_времени

Восстановление до определенного момента времени в формате timestamp.

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

--target-xid=xid_транзакции

Восстановление на определенный идентификатор транзакции.

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

--target-lsn=LSN

Восстановление на определенный LSN. Этот параметр принимает значение системного типа данных pg_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 | timeline_id ]

Указывает линию времени для восстановления. Значение может задаваться числовым идентификатором линии времени или ключевым словом (timeline_id). С ключевым словом current восстанавливается та линия времени, которая была активной при создании базовой резервной копии. С ключевым словом latest восстанавливаться будет последняя линия времени, найденная в архиве, что полезно для ведомого сервера. По умолчанию подразумевается latest.

--inclusive=[ on | off ]

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

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

-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 в отдельном потоке параллельно. Это опция по умолчанию. Файлы архивируются в путь_каталога/wal/.
  • fetch — архивировать WAL вместе с файлами кластера. Они будут расположены внутри директории $PGDATA/pg_wal/.
  • none — не архивировать файлы WAL.

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

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

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

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

--no-slot

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

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

-T
--tablespace-mapping=старый_путь=новый_путь

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

Здесь:

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

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

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

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

-f
--fast-checkpoint

Этот флаг запрашивает выполнение быстрой контрольной точки вместо обычной. Применяется при резервном копировании с горячего сервера или при репликации.

--skip-broken

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

-C --comment

Эта опция позволяет добавить комментарий для резервной копии.

--no-checksum

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

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

-y --yes

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

--prune

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

--single

Флаг, позволяющий удалить одну копию без удаления цепочки.

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

-K
--keep-wal-files

Этот флаг позволяет удалить резервную копию из каталога без удаления связанных с ней WAL-файлов (если таковые найдутся). Это может быть полезно, если вы хотите использовать файлы журналов для Выполнение восстановления на момент времени (PITR).

Обратите внимание, что автоматическая очистка WAL-файлов возможно только для резервных копий, сделанных qbackup версии 1.5.0 и выше.

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

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