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

• Синтаксис
• Описание
• Обзор
• Ограничения
• Установка и подготовка
  • Создание каталога копий
  • Настройка кластера баз данных
• Использование
  • Создание резервной копии
  • Восстановление кластера
  • Выполнение восстановления на момент времени (PITR)
  • Запуск qbackup в параллельных потоках
  • Управление каталогом резервных копий
    • Просмотр информации о резервных копиях
    • Удаление резервных копий
• Справка по командной строке
  • Команды
    • version
    • help
    • list
    • backup
    • restore
    • remove
    • backup-wal
  • Параметры
    • Общие параметры
    • Параметры подключения
    • Параметры точки восстановления
• Версионирование

Синтаксис

qbackup version

qbackup help [команда]

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

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

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

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

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

Описание

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

Обзор

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

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

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

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

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

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

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

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

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

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

Ограничения

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

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

• Поддержка табличных пространств ограничена.

• Поддержка линий времени ограничена.

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

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

Установив 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'

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

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

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

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

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

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

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

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

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

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

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

Здесь:

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

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

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

После окончания работы команды 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 могут указываться в дополнение к параметрам, устанавливающим точку восстановления. Обратитесь к соответствующим пунктам документации за подробностями.

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

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

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

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

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

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

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

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

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

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

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

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

+--------+--------+---------+-----------------+-------------+-------------+-----------+--------+---------------------+---------------------+
|   ID   | status |  size   | compressed size |    kind     | is archived | start lsn | parent |     start time      |      end time       |
+--------+--------+---------+-----------------+-------------+-------------+-----------+--------+---------------------+---------------------+
| QH05YZ |  Done  | 30.02MB |     4.54MB      |    Full     |    true     |     —     |   —    | 2020-09-21 09:49:47 | 2020-09-21 09:49:48 |
+--------+--------+---------+-----------------+-------------+-------------+-----------+--------+---------------------+---------------------+
| QH05ZK |  Done  | 68.64KB |        —        | Incremental |    false    |     —     | QH05YZ | 2020-09-21 09:50:08 | 2020-09-21 09:50:11 |
+--------+--------+---------+-----------------+-------------+-------------+-----------+--------+---------------------+---------------------+

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

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

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

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

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

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

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

  • Full - полная резервная копия.
  • Incremental - инкрементальная резервная копия.

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

• start lsn - LSN (Line Sequence Number) в момент начала копирования. Отсутствует для копий остановленного кластера.

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

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

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

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

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

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

[
  {
    "identifier": "QH05YZ",
    "status": "Ok",
    "size": 31478420,
    "compressed_size": 4764910,
    "compressed": true,
    "kind": "Full",
    "start_lsn": null,
    "start_time": "2020-09-21T09:49:47.333017715Z",
    "end_time": "2020-09-21T09:49:48.475500730Z",
    "parent": null
  },
  {
    "identifier": "QH05ZK",
    "status": "Ok",
    "size": 70292,
    "compressed_size": null,
    "compressed": false,
    "kind": "Incremental",
    "start_lsn": null,
    "start_time": "2020-09-21T09:50:08.233053635Z",
    "end_time": "2020-09-21T09:50:11.105948603Z",
    "parent": "QH05YZ"
  }
]

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

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

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

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

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

Команды

В этом подразделе описываются команды 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]

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

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

restore

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

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

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

remove

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

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

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

backup-wal

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

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

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

Параметры

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

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

-j --threads

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

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

-P --progress

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

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

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

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

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

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

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

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

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

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

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

--target-lsn = LSN

Восстановление на определенный LSN (Line Sequence Number). Этот параметр принимает значение системного типа данных 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.

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

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