qhb_basebackup
qhb_basebackup — создать базовую резервную копию кластера QHB
Синтаксис
qhb_basebackup [параметр...]
Описание
Утилита qhb_basebackup применяется для создания базовой резервной копии работающего кластера баз данных QHB. Создание копии не влияет на работу других клиентов базы данных, и эту копию можно использовать как для восстановления на момент времени (см. раздел Непрерывное архивирование и восстановление на момент времени (PITR)), так и в качестве отправной точки для резервного сервера при доставке журналов или потоковой репликации (см. раздел Доставка журналов на резервные серверы).
qhb_basebackup создает точную копию файлов кластера баз данных, при этом контролируя автоматическое переключение системы в режим резервного копирования и обратно. Резервные копии всегда создаются для кластера целиком; невозможно создание копии отдельных баз данных или их объектов. Для выборочного копирования следует использовать другие инструменты, к примеру утилиту qhb_dump.
Резервное копирование выполняется через обычное соединение QHB, использующее протокол репликации. Подключаться нужно от имени суперпользователя или пользователя с правом REPLICATION (см. раздел Атрибуты ролей), а файл qhb_hba.conf должен разрешать подключение для репликации. Кроме того, значение параметра max_wal_senders на сервере должно быть достаточно большим, чтобы как минимум один передатчик WAL был доступен для резервного копирования и еще один — для потоковой передачи WAL (если она используется).
Можно запустить несколько команд qhb_basebackup одновременно, но с точки зрения производительности лучше выполнить одно резервное копирование и скопировать полученный результат.
qhb_basebackup может сделать базовую копию не только с главного, но и с резервного сервера. Для этого нужно настроить резервный сервер, чтобы тот мог принимать подключения репликации (т. е. соответствующим образом настроить параметры max_wal_senders и hot_standby и конфигурацию qhb_hba.conf). Также нужно будет включить на главном сервере full_page_writes.
Обратите внимание, что при резервном копировании с резервного сервера есть некоторые ограничения:
-
Файл истории резервного копирования в целевом кластере баз данных не создается.
-
qhb_basebackup не может принудительно переключить резервный сервер на новый файл WAL в конце копирования. Если используется режим -X none и активность записи на основном сервере низкая, есть вероятность, что qhb_basebackup придется долго ждать переключения и архивирования последнего файла WAL, необходимого для полноты копии. В таком случае будет целесообразно запустить на основном сервере функцию pg_switch_wal для немедленного переключения файла WAL.
-
Если во время копирования резервный сервер становится главным, оно прерывается.
-
Все записи WAL, необходимые для резервного копирования, должны содержать достаточное количество полных страниц, для чего необходимо включить full_page_writes на главном сервере.
Когда qhb_basebackup создает базовую копию, в представлении pg_stat_progress_basebackup отображается состояние этого процесса. Подробную информацию см. в подразделе Отчет о ходе выполнения базового резервного копирования.
Параметры
Следующие параметры командной строки управляют расположением и форматом вывода:
-D каталог
--pgdata=каталог
Задает целевой каталог для записи резервной копии. Если его не существует,
qhb_basebackup создаст его (и все отсутствующие родительские каталоги).
Если каталог уже существует, он должен быть пустым.
Если резервная копия создается в формате tar, имя целевого каталога можно задать
как - (тире), и тогда tar-файл будет записан в stdout.
Этот параметр является обязательным.
-F формат
--format=формат
Выбирает формат вывода. формат может принимать одно из следующих значений:
- p
plain
Записать результат в виде простых файлов, сохраняя структуру текущего каталога хранения данных и табличных пространств. Если в кластере нет дополнительных табличных пространств, вся база данных будет помещена в целевой каталог. В ином случае основной каталог хранения данных будет помещен в целевой каталог, а все остальные табличные пространства — в те же абсолютные пути, что и на исходном сервере. (Чтобы изменить это, воспользуйтесь параметром --tablespace-mapping).
Это формат по умолчанию. - t
tar
Записать результат в целевой каталог в виде tar-файлов. Основной каталог хранения данных будет записан в файл с именем base.tar, а все остальные табличные пространства будут записаны в отдельные tar-файлы, названные в соответствии с OID этих табличных пространств.
Если в качестве имени целевого каталога задано - (тире), данные будут записаны в стандартный вывод, подходящий для передачи, например, в gzip. Это возможно только в том случае, если в кластере нет дополнительных табличных пространств и не используется потоковая передача WAL.
-R
--write-recovery-conf
Создает файл standby.signal и добавляет параметры
подключения в файл qhb.auto.conf в целевом каталоге (или в базовый архивный
файл, если используется формат tar). Это упрощает настройку резервного сервера с
помощью результатов резервного копирования.
В файл qhb.auto.conf будут записаны параметры подключения и, если указан
слот репликации, который использует qhb_basebackup, так что впоследствии
при потоковой репликации будут использованы те же параметры.
-t цель
--target=цель
Указывает серверу, куда поместить базовую резервную копию. Целью по умолчанию
является клиент, что означает, что резервная копия должна быть отправлена на
компьютер, где запущена утилита qhb_basebackup. Если вместо этого в
качестве цели задано server:/некоторый/путь, то резервная копия будет сохранена
на компьютере, где запущен сервер, в каталоге /некоторый/путь. Для сохранения
резервной копии на сервере требуются права суперпользователя или роли
pg_write_server_files. Если целью указано blackhole, то содержимое копии
отбрасывается и нигде не сохраняется. Это значение следует использовать только в
целях тестирования, поскольку фактически никакой резервной копии вы не получите.
Поскольку прием потока WAL реализуется qhb_basebackup, а не сервером, этот параметр нельзя использовать совместно с -X stream. Поскольку это режим по умолчанию, то при указании данного параметра следует также указать -X fetch или -X none.
-T старый_каталог=новый_каталог
--tablespace-mapping=старый_каталог=новый_каталог
Перемещает табличное пространство из старого_каталога в новый_каталог
в процессе копирования. Чтобы перемещение произошло, старый_каталог должен
точно соответствовать пути табличного пространства, как тот определен на исходном
сервере. (Однако если в старом_каталоге исходного сервера не окажется
табличного пространства, это не будет ошибкой.) В то же время новый_каталог
является каталогом в файловой системе получающего хоста. Как и основной целевой
каталог, новый_каталог может не существовать, но если он уже существует,
то должен быть пустым. И старый_каталог, и новый_каталог должны
задаваться абсолютными путями. Если путь содержит знак равенства (=), его нужно
экранировать обратным слэшем. Этот параметр можно указать несколько раз для
нескольких табличных пространств.
Если табличное пространство перемещается таким образом, символические ссылки внутри
основного каталога данных обновляются, чтобы указывать на новое местоположение.
Таким образом, для нового экземпляра сервера подготавливается новый каталог
хранения данных, где все табличные пространства находятся в новых расположениях.
В настоящее время этот параметр работает только с простым форматом вывода; если
выбран формат tar, параметр игнорируется.
--waldir=каталог_wal
Задает каталог для записи WAL (журнала упреждающей записи). По умолчанию файлы
WAL будут помещаться в подкаталог pg_wal целевого каталога, но с помощью
этого параметра их можно поместить в любое другое место. каталог_wal должен
задаваться абсолютным путем. Как и основной целевой каталог, каталог_wal
может не существовать, но если он уже существует, то должен быть пустым. Этот
параметр можно задать, только если копия создается в простом формате.
-X метод
--wal-method= метод
Включает в резервную копию все необходимые файлы WAL (журнала упреждающей записи).
Сюда войдут все журналы, сгенерированные в процессе резервного копирования. Если
только не выбран метод none, qhbmaster можно запускать непосредственно в
извлеченном каталоге без необходимости обращаться к архиву журналов; таким
образом будет получена полностью автономная резервная копия.
Поддерживаются следующие методы сбора журналов упреждающей записи:
- n
none
Не включать журнал упреждающей записи в резервную копию. - f
fetch
Файлы журнала упреждающей записи собираются в конце процесса резервного копирования. Поэтому необходимо задать достаточно большое значение параметра wal_keep_size на исходном сервере, чтобы журнал не удалялся до окончания резервного копирования. Если журнал был переработан до момента передачи, резервное копирование прервется, а копия будет непригодной к использованию.
При использовании формата tar файлы журнала упреждающей записи будут записываться в файл base.tar. - s
stream
Журнал упреждающей записи передается в процессе создания резервной копии. При этом открывается второе соединение с сервером, по которому происходит потоковая передача журнала упреждающей записи, одновременно с резервным копированием. Таким образом, для этого режима потребуется не одно, а два соединения репликации. Пока клиент успевает принимать передаваемые данные журнала упреждающей записи, в этом режиме исходному серверу не нужно сохранять дополнительные журналы.
При использовании формата tar файлы журнала упреждающей записи будут записываться в отдельный файл с именем pg_wal.tar.
Это значение по умолчанию.
-z
--gzip
Включает gzip-сжатие выводимого tar-файла с уровнем сжатия по умолчанию. Сжатие
поддерживается только для формата tar; при этом ко всем именам файлов tar будет
автоматически добавлен суффикс .gz.
-Z уровень
-Z [{client|server}-]метод[:подробная_информация]
--compress=уровень
--compress [{client|server}-]метод[:подробная_информация]
Запрашивает сжатие резервной копии. Если содержится указание client или
server, оно задает место, где должно выполняться сжатие. При сжатии на
сервере уменьшится объем передаваемых данных, но возрастет нагрузка на ЦП.
Значение по умолчанию — client, за исключением случаев, когда используется
параметр --target. В этом случае резервная копия не передается клиенту,
поэтому имеет смысл только сжатие на сервере. В режиме -X stream (по умолчанию)
сжатие на стороне сервера не применяется к WAL. Чтобы сжать WAL, воспользуйтесь
сжатием на стороне клиента или укажите -X fetch.
В качестве метода сжатия можно задать gzip, lz4, zstd или none (без
сжатия). Дополнительно можно указать строку с подробной информацией по сжатию.
Если в этой строке передается целое число, оно задает уровень сжатия. В противном
случае это должен быть список разделенных запятыми элементов в форме
ключевое_слово или ключевое_слово=значение. В настоящее время
поддерживаются ключевые слова level (уровень) и workers (рабочие процессы).
Если уровень сжатия не задан, будет использован уровень сжатия по умолчанию.
Если задан только уровень, но не алгоритм сжатия, будет использован метод сжатие
gzip, если уровень больше 0, а при уровне 0 сжатие не будет выполняться.
При использовании формата tar с методом gzip, lz4 или zstd, ко всем именам
файлов tar будет автоматически добавлен суффикс .gz, .lz4 или .zst
соответственно. При использовании простого формата сжатие на стороне клиента
выполнить нельзя, но запросить сжатие на стороне сервера по-прежнему возможно.
При этом сервер будет сжимать резервную копию для передачи, а клиент будет ее
распаковывать и извлекать данные.
Когда этот параметр используется вместе с -X stream, pg_wal.tar будет
сжат методом gzip, если выбрано сжатие gzip на стороне клиента, но не будет
сжат, если выбран любой другой алгоритм сжатия или сжатие на стороне сервера.
Следующие параметры командной строки управляют генерированием резервной копии и вызовом этой программы:
-c fast|spread
--checkpoint=fast|spread
Устанавливает для контрольных точек режим fast (быстрый) или spread
(протяженный, по умолчанию) (см. подраздел Создание базовой резервной копии с использованием API низкого уровня).
-C
--create-slot
Указывает, что до начала резервного копирования должен быть создан слот репликации
с именем, заданным в параметре --slot. Если такой слот уже существует,
возникает ошибка.
-l метка
--label=метка
Задает метку для резервной копии. Если ее не указывать, по умолчанию будет
использовано значение «qhb_basebackup base backup».
-n
--no-clean
По умолчанию, когда qhb_basebackup прерывается с ошибкой, она удаляет все
каталоги, которые могла создать, прежде чем обнаружила, что не может завершить
работу (например целевой каталог и каталог журнала упреждающей записи). Этот
параметр запрещает подобную очистку и поэтому полезен для отладки.
Обратите внимание, что каталоги табличных пространств не очищаются в любом случае.
-N
--no-sync
По умолчанию qhb_basebackup будет ждать, пока все файлы не будут
гарантированно записаны на диск. С данным параметром qhb_basebackup
возвращает результат немедленно, что делает ее быстрее, но означает, что при
последующем сбое операционной системы базовая резервная копия может оказаться
поврежденной. В целом, этот параметр полезен для тестирования, но не должен
применяться при создании эксплуатационной установки.
-P
--progress
Включает отчет о прогрессе. При установке этого параметра во время создания
резервной копии будет передаваться примерный процент выполнения. Поскольку в
процессе копирования база данных может изменяться, это значение будет всего лишь
приблизительным и может не достигать ровно 100%. В частности, когда в резервную
копию включается журнал WAL, общий размер данных невозможно рассчитать заранее, и
в этом случае предварительный целевой размер будет увеличиваться, как только
превысит предварительный общий размер без WAL.
-r скорость_передачи
--max-rate=скорость_передачи
Задает максимальную скорость передачи данных с сервера. Это может быть полезно
для ограничения воздействия qhb_basebackup на производительность сервера.
Значения задаются в килобайтах в секунду. Чтобы указать мегабайты в секунду, можно
использовать суффикс M. Также принимается суффикс k, но он не действует.
Допустимые значения находятся в пределах от 32 Кб/с до 1024 Мб/с.
Этот параметр всегда влияет на передачу каталога данных. На передачу файлов WAL
он влияет, только если выбран метода сбора данных fetch.
-S имя_слота
--slot=имя_слота
Этот параметр можно применять только вместе с -X stream. С ним для потоковой
передачи WAL используется указанный слот репликации. Если базовая резервная копия
предназначена для использования на резервном сервере с потоковой репликации через
слот репликации, это же имя слота должно задаваться на резервном сервере в качестве
primary_slot_name. Это гарантирует, что основной сервер не удалит никакие
необходимые данные WAL в интервале между окончанием создания базовой копии и
началом потоковой репликации на новом резервном сервере.
Если не используется параметр -C, указанный слот репликации уже должен
существовать.
Если этот параметр не задан и сервер поддерживает временные слоты репликации, то
для потоковой передачи WAL автоматически используется временный слот репликации.
-v
--verbose
Включить режим подробного вывода. Будут выводится некоторые дополнительные сведения
об этапах в начале и завершении, а также отображаться конкретные имена файлов,
которые обрабатываются в данный момент, если также включен отчет о прогрессе.
--manifest-checksums=алгоритм
Задает алгоритм контрольных сумм, который должен применяться к каждому файлу,
включенному в манифест резервной копии. В настоящее время доступны алгоритмы
NONE (отсутствует), CRC32C, SHA224, SHA256, SHA384 и SHA512. Значение
по умолчанию — CRC32C.
Если выбран вариант NONE, манифест резервной копии не будет содержать никаких
контрольных сумм. В ином случае он будет содержать контрольную сумму каждого файла
копии, рассчитанную по заданному алгоритму. Кроме того, манифест всегда будет
содержать контрольную сумму своего содержимого, рассчитанную по алгоритму SHA256.
Алгоритмы SHA требуют значительно больше ресурсов процессора, чем CRC32C,
поэтому выбор одного из них может увеличить время, требующееся для завершения
копирования.
Применение функций хеширования SHA обеспечивает криптографически защищенную
обработку каждого файла, если нужны гарантии того, что резервная копия не была
искажена, тогда как алгоритм CRC32C вычисляет контрольную сумму гораздо быстрее;
он подходит для выявления ошибок из-за случайных изменений, но неустойчив против
злонамеренных модификаций. Обратите внимание, что для защиты от злоумышленника,
имеющего доступ к резервной копии, манифест этой копии должен храниться отдельно
в надежном месте или еще как-то проверяться на предмет отсутствия модификаций с
момента создания копии.
Для проверки целостности копии по ее манифесту можно воспользоваться утилитой
qhb_verifybackup.
--manifest-force-encode
Принудительно включает шестнадцатеричное кодирование всех имен файлов в манифесте
резервной копии. Если этот параметр не задан, шестнадцатеричному кодированию
подвергаются только имена файлов в кодировке, отличной от UTF8. Этот параметр
предназначен в основном для проверки того, что инструменты, читающие файл манифеста
резервной копии, правильно воспринимают такие имена.
--no-estimate-size
Не позволяет серверу рассчитывать общий объем копируемых данных, который будет
передаваться, в результате чего столбец backup_total в представлении
pg_stat_progress_basebackup всегда будет равен NULL.
Без этого параметра копирование начнется с пересчитывания всех файлов в базе
данных, а затем вернется к отправке фактического содержимого. Это может увеличить
длительность процесса копирования, в частности пройдет больше времени до начала
отправки данных. Этот параметр помогает исключать подсчет объема, когда тот
оказывается слишком долгим.
Этот параметр нельзя использовать вместе с параметром --progress.
--no-manifest
Выключает создание манифеста резервной копии. Если этот параметр не задан, сервер
будет генерировать и передавать манифест резервной копии, который можно проверить
с помощью qhb_verifybackup. Манифест представляет собой список всех файлов,
находящихся в копии, за исключением файлов WAL, которые могут быть в нее добавлены.
Также в нем хранится размер, время последнего изменения и, возможно, контрольная
сумма каждого файла.
--no-slot
Препятствует созданию временного слота репликации для резервного копирования.
По умолчанию, если выбрана потоковая передача журнала, но в параметре -S не
задано имя слота, создается временный слот репликации (если это поддерживает
исходный сервер).
Основное предназначение этого параметра состоит в том, что он позволяет создать
базовую резервную копию, когда на сервере нет свободных слотов репликации.
Использование слота репликации почти всегда предпочтительнее, поскольку это
предотвращает удаление сервером необходимых файлов WAL во время резервного
копирования.
--no-verify-checksums
Отключает проверку контрольных сумм, если они включены на сервере, с которого
делается резервная копия.
По умолчанию контрольные суммы проверяются, и при наличии в них несоответствия
выдается ненулевой код завершения. Однако в этом случае базовая резервная копия
не удаляется, как если бы использовался параметр --no-clean. Несоответствия
контрольных сумм также будут отображаться в представлении pg_stat_database.
Следующие параметры командной строки управляют подключением к исходному серверу:
-d строка_подключения
--dbname=строка_подключения
Задает параметры, используемые для подключения к серверу, в виде строки подключения;
они будут переопределять любые конфликтующие параметры командной строки.
Этот параметр называется --dbname для согласованности с другими клиентскими
приложениями, но поскольку qhb_basebackup не подключается к какой-либо
конкретной базе данных кластера, любое имя базы данных будет проигнорировано.
-h хост
--host=хост
Задает имя хост-компьютера, на котором работает сервер. Если значение начинается
со слэша, оно используется в качестве каталога для сокета домена Unix. Значение по
умолчанию берется из переменной среды PGHOST, если она установлена; иначе
производится попытка подключения к сокету домена Unix.
-p порт
--port=порт
Указывает TCP-порт или расширение файла локального сокета домена Unix, через который
сервер принимает подключения. Значение по умолчанию определяется переменной среды
PGPORT, если она установлена, или значением, заданным при компиляции.
-s интервал
--status-interval=интервал
Задает интервал в секундах между сообщениями о состоянии, отсылаемыми исходному
серверу. Чем меньше это значение, тем тщательнее сервер будет мониторить ход
выполнения резервного копирования. Нулевое значение полностью выключает
периодическое обновление состояния, хотя сообщения все равно будут передаваться
по запросу сервера во избежание отключений по превышению времени ожидания.
Значение по умолчанию — 10 секунд.
-U имя_пользователя
--username=имя_пользователя
Задает имя пользователя, под которым производится подключение.
-w
--no-password
Предотвращает запрос на ввод пароля. Если серверу требуется аутентификация по
паролю, и пароль недоступен с помощью иных средств, таких как файл .pgpass,
попытка подключения завершится неудачно. Этот параметр может быть полезен в
пакетных заданиях и скриптах, где нет пользователя, чтобы ввести пароль.
-W
--password
Заставляет qhb_basebackup запрашивать пароль перед подключением к
исходному серверу.
Это несущественный параметр, так как qhb_basebackup автоматически запросит
пароль, если сервер требует аутентификацию по паролю. Однако чтобы выяснить это,
qhb_basebackup потребуется дополнительная попытка подключения к серверу. В
некоторых случаях имеет смысл ввести -W, чтобы исключить эту лишнюю попытку.
Также доступны и другие параметры:
-V
--version
Вывести версию qhb_basebackup и завершиться.
-?
--help
Показать справку об аргументах командной строки qhb_basebackup и завершиться.
Переменные среды
Эта утилита, как и большинство других утилит QHB, использует переменные среды, поддерживаемые libpq (см. раздел Переменные среды).
PG_COLOR
Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения:
always (всегда), auto (автоматически) и never (никогда).
Примечания
В начале резервного копирования на исходном сервере следует выполнить контрольную точку. Это может занять некоторое время (особенно если не установлен параметр --checkpoint=fast), в течение которого qhb_basebackup будет бездействовать.
Резервная копия будет включать в себя все файлы каталога хранения данных и табличных пространств, в том числе файлы конфигурации и все дополнительные файлы, помещенные в этот каталог третьими лицами, за исключением некоторых временных файлов, управляемых QHB. Однако копируются только обычные файлы и каталоги, а помимо этого сохраняются лишь символические ссылки на табличные пространства. Символические ссылки, указывающие на определенные каталоги, известные QHB, копируются как пустые каталоги. Другие символические ссылки и файлы специальных устройств пропускаются. Дополнительную информацию см. в разделе Протокол потоковой репликации.
Если не указан флаг --tablespace-mapping, по умолчанию табличные пространства в простом формате будут копироваться в тот же путь, что и на сервере. Без этого параметра при использовании табличных пространств создать копию базы в простом формате на том же сервере не получится, поскольку резервная копия должна быть записана в те же каталоги, что и исходные табличные пространства.
Когда используется формат tar, пользователь должен позаботиться о распаковке каждого tar-файла перед запуском сервера QHB, использующего эти данные. При наличии дополнительных табличных пространств их tar-файлы необходимо распаковать в правильные расположения. В таком случае сервером будут созданы символические ссылки на эти табличные пространства, в соответствии с содержимым файла tablespace_map, включенного в файл base.tar.
qhb_basebackup сохранит групповые разрешения для файлов данных, если те включены в исходном кластере.
Примеры
Создать базовую резервную копию сервера на mydbserver и сохранить ее в локальном каталоге /var/lib/qhb/data:
$ qhb_basebackup -h mydbserver -D /var/lib/qhb/data
Создать резервную копию локального сервера в отдельных файлах tar для каждого табличного пространства и сохранить ее в каталоге backup, отчитываясь о прогрессе во время выполнения:
$ qhb_basebackup -D backup -Ft -z -P
Создать резервную копию локальной базы данных с одним табличным пространством и сжать ее с помощью bzip2:
$ qhb_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2
(Эта команда не будет выполнена, если в базе данных есть несколько табличных пространств.)
Создать резервную копию локальной базы данных с перемещением табличного пространства из /opt/ts в ./backup/ts:
$ qhb_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts
Создать резервную копию локального сервера, в которой будет по одному tar-файлу для каждого табличного пространства (сжатие методом gzip с уровнем 9), и сохранить ее в каталоге backup:
$ qhb_basebackup -D backup -Ft --compress=gzip:9
См. также
qhb_dump, подраздел Отчет о ходе выполнения базового резервного копирования