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 на главном сервере и не использовать в
archive_commandутилиты вроде qhb_compresslog для удаления полностраничных записей из файлов WAL.
Когда 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 старый_каталог=новый_каталог
--tablespace-mapping=старый_каталог=новый_каталог
Перемещает табличное пространство из старого_каталога в новый_каталог
в процессе копирования. Чтобы перемещение произошло, старый_каталог должен
точно соответствовать пути табличного пространства, как тот определен на исходном
сервере. (Однако если в старом_каталоге исходного сервера не окажется
табличного пространства, это не будет ошибкой.) В то же время новый_каталог
является каталогом в файловой системе получающего хоста. Как и основной целевой
каталог, новый_каталог может не существовать, но если он уже существует,
то должен быть пустым. И старый_каталог, и новый_каталог должны
задаваться абсолютными путями. Если путь содержит знак равенства (=), его нужно
экранировать обратным слэшем. Этот параметр можно указать несколько раз для
нескольких табличных пространств.
Если табличное пространство перемещается таким образом, символические ссылки внутри
основного каталога данных обновляются, чтобы указывать на новое местоположение.
Таким образом, для нового экземпляра сервера подготавливается новый каталог
хранения данных, где все табличные пространства находятся в новых расположениях.
В настоящее время этот параметр работает только с простым форматом вывода; если
выбран формат tar, параметр игнорируется.
--waldir=каталог_wal
Задает каталог для записи WAL (журнала упреждающей записи). По умолчанию файлы
WAL будут помещаться в подкаталог pg_wal целевого каталога, но с помощью
этого параметра их можно поместить в любое другое место. каталог_wal должен
задаваться абсолютным путем. Как и основной целевой каталог, каталог_wal
может не существовать, но если он уже существует, то должен быть пустым. Этот
параметр можно задать, только если копия создается в простом формате.
-X метод
--wal-method= метод
Включает в резервную копию все необходимые файлы WAL (журнала упреждающей записи).
Сюда войдут все журналы, сгенерированные в процессе резервного копирования. Если
только не выбран метод none, главный процесс QHB можно
запускать непосредственно в извлеченном каталоге без необходимости обращаться к
архиву журналов; таким образом будет получена полностью автономная резервная
копия.
Поддерживаются следующие методы сбора журналов упреждающей записи:
- n
none
Не включать журнал упреждающей записи в резервную копию. - f
fetch
Файлы журнала упреждающей записи собираются в конце процесса резервного копирования. Поэтому необходимо задать достаточно большое значение параметра wal_keep_size, чтобы журнал не удалялся раньше времени. Если журнал был переработан до момента передачи, резервное копирование прервется, а копия будет непригодной к использованию.
При использовании формата tar файлы журнала упреждающей записи будут записываться в файл base.tar. - s
stream
Журнал упреждающей записи передается в процессе создания резервной копии. При этом открывается второе соединение с сервером, по которому происходит потоковая передача журнала упреждающей записи, одновременно с резервным копированием. Таким образом будут использоваться два подключения из заданных параметром max_wal_senders. Пока клиент может отслеживать передаваемый журнал упреждающей записи, в этом режиме главному серверу не нужно хранить дополнительные файлы журнала.
При использовании формата tar файлы журнала упреждающей записи будут записываться в отдельный файл с именем pg_wal.tar.
Это значение по умолчанию.
-z
--gzip
Включает gzip-сжатие выводимого tar-файла с уровнем сжатия по умолчанию. Сжатие
поддерживается только для формата tar; при этом ко всем именам файлов tar будет
автоматически добавлен суффикс .gz.
-Z уровень
--compress=уровень
Включает gzip-сжатие выводимого tar-файла и задает уровень сжатия от 0 (без сжатия)
до 9 (максимальное сжатие). Сжатие поддерживается только для формата tar; при
этом ко всем именам файлов tar будет автоматически добавлен суффикс .gz.
.
Следующие параметры командной строки управляют генерированием резервной копии и вызовом этой программы:
-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
См. также
qhb_dump, Отчет о ходе выполнения базового резервного копирования