qhb_restore
qhb_restore — восстановить базу данных QHB из архивного файла, созданного qhb_dump
Синтаксис
qhb_restore [параметр-подключения...] [параметр...] [имя_файла]
Описание
qhb_restore — это утилита для восстановления базы данных QHB из архива, созданного qhb_dump в одном из нетекстовых форматов. Она выдает команды, необходимые для воссоздания базы данных до состояния, в котором та находилась на момент сохранения. Архивные файлы также позволяют qhb_restore выбирать объекты для восстановления или даже переупорядочивать элементы перед восстановлением. Архивные файлы предназначены для переноса между архитектурами.
Утилита qhb_restore может работать в двух режимах. Если указано имя базы данных, qhb_restore подключается к ней и восстанавливает содержимое архива непосредственно в эту базу. В противном случае создается скрипт, содержащий команды SQL, необходимые для перестройки базы данных, который записывается в файл или стандартный вывод. Этот вывод скрипта равнозначен простому текстовому формату вывода qhb_dump. Поэтому некоторые параметры qhb_restore, управляющие выводом, аналогичны параметрам qhb_dump.
Очевидно, что qhb_restore не может восстановить информацию, которой нет
в файле архива. Например, если архив был создан с использованием параметра
«выгрузить данные в виде команд INSERT», qhb_restore не сможет загружать
данные с помощью операторов COPY.
Параметры
Утилита qhb_restore принимает следующие аргументы командной строки.
имя_файла
Задает расположение восстанавливаемого архивного файла (или каталог, для архива
в формате каталога). Если этот параметр не указан, используется стандартный ввод.
-a
--data-only
Восстановить только данные, но не схему (DDL, определения данных). Если в архиве
имеются данные таблиц, большие объекты и значения последовательности, они тоже
восстанавливаются.
Этот параметр похож, но по историческим причинам не идентичен указанию параметра
--section=data.
-c
--clean
Очистить (DROP) объекты базы данных перед их воссозданием. (Если не используется
--if-exists и какие-либо объекты не присутствуют в целевой базе данных, могут
генерироваться безвредные сообщения об ошибке.)
-C
--create
Создать базу данных перед восстановлением в нее данных. Если также указан параметр
--clean, удалить и заново создать целевую базу данных перед подключением к ней.
Кроме того, с помощью --create qhb_restore восстанавливает комментарий
к базе данных (если таковой имеется) и все значения переменных конфигурации,
специфичные для этой базы данных, то есть любые команды ALTER DATABASE ... SET ...
и ALTER ROLE ... IN DATABASE ... SET ..., в которых упоминается эта база данных.
Права доступа к самой базе данных тоже восстанавливаются, если не указан параметр
--no-acl.
При использовании этого параметра база данных, названная параметром -d,
применяется только для выполнения начальных команд DROP DATABASE и CREATE DATABASE. Все данные восстанавливаются в базу данных с именем, указанным в архиве.
-d имя_бд
--dbname=имя_бд
Подключиться к базе данных имя_бд и восстановить данные непосредственно в
эту базу. В имени_бд может задаваться строка подключения.
В этом случае параметры в строке подключения переопределяют любые конфликтующие
параметры в командной строке.
-e
--exit-on-error
Завершиться, если при отправке команд SQL в базу данных возникла ошибка. По
умолчанию операция продолжается, а количество ошибок отображается в конце
восстановления.
-f имя_файла
--file=имя_файла \
Задать выходной файл для сгенерированного скрипта или для оглавления (если
используется вместе с ключом -l). Для вывода в stdout напишите - (минус).
-F формат
--format=формат
Указать формат архива. В этом нет необходимости, поскольку qhb_restore
определит формат автоматически. Если этот параметр задается, допускается один из
следующих вариантов:
- c
custom
Архив сохранен в специальном формате pg_dump. - d
directory
Архив сохранен в каталоге. - t
tar
Архив сохранен в формате tar.
-I индекс
--index=индекс
Восстановить определение только именованного индекса. Задав ключ -I несколько
раз, можно указать несколько индексов.
-j количество_заданий
--jobs=количество_заданий
Выполнять самые трудоемкие этапы qhb_restore — те, где загружаются данные,
создаются индексы или ограничения, — одновременно, используя параллельные сеансы
числом до количества_заданий. С этим параметром можно значительно сократить
время восстановления большой базы данных на сервере, работающем на многопроцессорной
машине. Когда вместо прямого подключения к серверу баз данных генерируется скрипт,
этот параметр игнорируется.
Каждое задание представляет собой один процесс или один поток, в зависимости от
операционной системы, и использует отдельное подключение к серверу.
Оптимальное значение для этого параметра зависит от аппаратной настройки сервера,
клиента и сети. Факторы включают количество ядер ЦП и настройку диска. Хорошей
отправной точкой является количество ядер ЦП на сервере, но более высокие значения
во многих случаях тоже могут привести к ускоренному восстановлению. Конечно,
слишком высокие значения приведут к снижению производительности из-за перегрузки.
Этот параметр поддерживается только со специальными форматами и форматами каталогов.
На вход должен передаваться обычный файл или каталог (а не, например, канал или
стандартный ввод). Кроме того, несколько заданий нельзя выполнять, если указан
параметр --single-transaction.
-l
--list
Вывести оглавление архива. Выходные данные этой операции можно использовать как
входные данные для параметра -L. Обратите внимание, что если с -l
используются ключи фильтрации, например -n или -t, они сократят список
элементов.
-L файл-список
--use-list=файл-список
Восстановить только те элементы архива, которые перечислены в файле-списке,
причем сделать это в порядке их перечисления. Обратите внимание, что если с -L
используются ключи фильтрации, например -n или -t, они дополнительно
сократят список элементов.
Обычно файл-список создается путем редактирования вывода предыдущей операции
-l. Строки можно перемещать или удалять, а также закомментировать, поместив
в начале строки точку с запятой (;). Примеры см. ниже.
-n схема
--schema=схема
Восстановить объекты только из именованной схемы. Задав ключ -n несколько
раз, можно указать несколько схем. Этот параметр можно скомбинировать с параметром
-t, чтобы восстановить только определенную таблицу.
-N схема
--exclude-schema=схема
Не восстанавливать объекты из именованной схемы. Задав ключ -N несколько
раз, можно исключить несколько схем.
Если в ключах -n and -N задается одинаковое имя схемы, ключ -N побеждает,
и схема исключается.
-O
--no-owner
Не генерировать команды для установки владельца объектов в соответствии с исходной
базой данных. По умолчанию для установки владельца созданных элементов схемы
qhb_restore выполняет операторы ALTER OWNER или SET SESSION AUTHORIZATION.
Эти операторы выполнятся, только если исходное соединение с базой данных установлено
суперпользователем (или пользователем, которому принадлежат все объекты в скрипте).
С ключом -O начальное подключение может произвести любой пользователь, и он
же станет владельцем всех созданных объектов.
-P имя-функции(тип-аргумента[, ...])
--function=имя-функции(тип-аргумента[, ...])
Восстановить только именованную функцию. Следите за тем, чтобы писать имя функции
и аргументы в точности так, как они фигурируют в оглавлении файла дампа. Задав
ключ -P несколько раз, можно указать несколько функций.
-R
--no-reconnect
Этот параметр устарел, но все еще принимается для обратной совместимости.
-s
--schema-only
Восстановить только схему (DDL, определения данных), а не данные, и в том объеме,
в котором записи схемы присутствуют в архиве.
Этот параметр является обратным параметру --data-only. Он похож, но по
историческим причинам не идентичен указанию --section=pre-data --section=post-data.
(Не путайте этот параметр с параметром --schema, где слово «схема» применяется
в другом значении.)
-S имя_пользователя
--superuser=имя_пользователя
Задать имя суперпользователя, которое будет использоваться при выключении
триггеров. Имеет значение только вместе с параметром --disable-triggers.
-t таблица
--table=таблица
Восстановить определение и/или данные только именованной таблицы. В этом случае
слово «таблица» включает в себя представления, материализованные представления,
последовательности и сторонние таблицы. Задав ключ -t несколько раз, можно
указать несколько таблиц. Этот параметр можно скомбинировать с параметром
-n, чтобы указать таблицу(ы) в конкретной схеме.
Примечание
При указании -t утилита qhb_restore не пытается восстановить прочие объекты базы данных, от которых могут зависеть выбранные таблицы. Таким образом, нет гарантии, что конкретные таблицы будут успешно восстановлены в чистой базе данных.
Примечание
Этот флаг не ведет себя идентично флагу -t утилиты qhb_dump. В настоящее время qhb_restore не поддерживает подбор соответствий по подстановочным знакам, а кроме того, нельзя включить в -t имя схемы. И хотя с флагом -t утилиты qhb_dump также будут выгружаться вспомогательные объекты (например индексы) выбранных таблиц, с флагом -t утилиты qhb_restore такие вспомогательные объекты не включаются.
-T триггер
--trigger=триггер
Восстановить только именованный триггер. Задав ключ -T несколько раз, можно
указать несколько триггеров.
-v
--verbose
Задает режим подробных сообщений. qhb_restore будет выводить в стандартный
поток ошибок подробные комментарии к объектам и время начала/окончания восстановления
из файла вывода, а также сообщения о прогрессе выполнения. Если повторить этот
параметр, в стандартный поток ошибок будут выводиться дополнительные отладочные
сообщения.
-V
--version
Вывести версию qhb_restore и завершиться.
-x
--no-privileges
--no-acl
Не допустить восстановления прав доступа (команды GRANT/REVOKE).
-1
--single-transaction
Выполнить восстановление как одну транзакцию (обернуть сгенерированные команды в
BEGIN/COMMIT). Это гарантирует что либо все команды завершаются успешно, либо
изменения не применяются. Этот параметр подразумевает --exit-on-error.
--disable-triggers
Этот параметр актуален только при выполнении восстановления одних данных. Он
предписывает qhb_restore выполнять команды для временного выключения
триггеров на целевых таблицах во время восстановления данных. Применяется в
ситуациях, когда существуют проверки ссылочной целостности или другие триггеры
для таблиц, которые нежелательно вызывать во время восстановления данных.
В настоящее время команды, генерируемые для --disable-triggers, должны
выполняться суперпользователем. Следовательно, необходимо задать имя
суперпользователя с помощью ключа -S или, что предпочтительно, запустить
qhb_restore как суперпользователь QHB.
--enable-row-security
Этот параметр актуален только при восстановлении содержимого таблицы с защитой
строк. По умолчанию qhb_restore устанавливает в row_security off
(выключен), чтобы в таблице гарантированно были восстановлены все данные. Если
у пользователя недостаточно прав для обхода защиты строк, возникает ошибка. Этот
параметр предписывает qhb_restore установить в row_security
on (включен), позволяя пользователю попытаться восстановить содержимое таблицы
с включенной защитой строк. Это все равно может не сработать, если у пользователя
нет права добавлять в таблицу строки из дампа.
Обратите внимание, что в настоящее время при использовании этого параметра также
необходимо, чтобы дамп был в формате INSERT, так как команда COPY FROM не
поддерживает защиту строк.
--if-exists
Использовать условные команды (т. е. добавлять предложение IF EXISTS) при
удалении объектов базы данных. Этот параметр не работает без указания --clean.
--no-comments
Не генерировать команды для восстановления комментариев, даже если архив содержит
их.
--no-data-for-failed-tables
По умолчанию данные таблицы восстанавливаются, даже если команда создания таблицы
не выполнена (например, потому что таблица уже существует). С этим параметром данные
для такой таблицы пропускаются. Это поведение полезно, если целевая база данных
уже содержит желаемое содержимое таблицы. Например, вспомогательные таблицы для
расширений QHB, в частности, PostGIS, могут быть уже загружены в
целевую базу данных; указание этого параметра предотвращает загрузку в них дубликатов
или устаревших данных.
Этот параметр действует только при восстановлении непосредственно в базу данных,
но не при создании скрипта SQL.
--no-publications
Не генерировать команды для восстановления публикаций, даже если архив содержит
их.
--no-security-labels
Не генерировать команды для восстановления меток безопасности, даже если архив
содержит их.
--no-subscriptions
Не генерировать команды для восстановления подписок, даже если архив содержит
их.
--no-tablespaces
Не генерировать команды для выбора табличных пространств. С этим параметром все
объекты будут восстановлены в табличном пространстве по умолчанию (на момент
восстановления).
--section=имя_партиции
Восстановить только заданный раздел. Именем раздела может быть pre-data, data
или post-data. Для выбора нескольких разделов этот параметр можно указать более
одного раза. По умолчанию восстанавливаются все разделы.
Раздел data содержит фактические данные таблиц, содержимое больших объектов и
значения последовательности. Раздел post-data содержит определения индексов,
триггеров, правил и ограничений (кроме ограничений проверки, созданных без
NOT VALID). Раздел pre-data содержит все остальные элементы определений
данных.
--strict-names
Требовать, чтобы каждому квалификатору схемы (-n/--schema) и таблицы
(-t/--table) соответствовал как минимум один объект схема/таблица в файле
резервной копии.
--use-set-session-authorization
Выводить команды SET SESSION AUTHORIZATION, соответствующие стандарту SQL,
вместо команд ALTER OWNER, чтобы определить владельца объекта. В итоге дамп будет
более стандартизированным, но, в зависимости от истории объектов, может не
восстановиться должным образом.
-?
--help
Показать справку об аргументах командной строки qhb_restore и завершиться.
.
Кроме того, в качестве параметров подключения qhb_restore принимает следующие аргументы командной строки:
-h хост
--host=хост
Задает имя хост-компьютера, на котором работает сервер. Если значение начинается
со слэша, оно используется в качестве каталога для сокета домена Unix. Значение по
умолчанию определяется переменной среды PGHOST, если она установлена. В
противном случае производится попытка подключения к сокету домена Unix.
-p порт
--port=порт
Указывает TCP-порт или расширение файла локального сокета домена Unix, через который
сервер принимает подключения. Значение по умолчанию определяется переменной
среды PGPORT, если она установлена, или значением по умолчанию, заданным при
компиляции.
-U имя_пользователя
--username=имя_пользователя
Имя пользователя, под которым производится подключение.
-w
--no-password
Никогда не запрашивать ввод пароля. Если серверу требуется аутентификация по
паролю, и пароль недоступен с помощью иных средств, таких как файл .pgpass,
попытка подключения завершится неудачно. Этот параметр может быть полезен в
пакетных заданиях и скриптах, где нет пользователя, чтобы ввести пароль.
-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как qhb_restore автоматически запросит
пароль, если сервер требует аутентификацию по паролю. Однако чтобы выяснить это,
qhb_restore потребуется дополнительная попытка подключения к серверу. В
некоторых случаях имеет смысл ввести -W, чтобы исключить эту лишнюю попытку.
--role=имя_роли
Задает имя роли, которая будет использоваться для проведения восстановления. При
указании этого параметра qhb_restore выполнит команду SET ROLE имя_роли
после подключения к базе данных. Это полезно, когда проходящий проверку пользователь
(заданный ключом -U) не имеет прав, требуемых qhb_restore, но может
переключиться на роль, наделенную этими правами. В некоторых установках имеется
политика, запрещающая подключаться к серверу непосредственно от имени
суперпользователя, и этот параметр позволяет проводить восстановления, не нарушая ее.
Переменные среды
PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию.
PG_COLOR
Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения:
always (всегда), auto (автоматически) и never (никогда).
Кроме того, эта утилита, как и большинство других утилит QHB, использует переменные среды, поддерживаемые libpq (см. раздел Переменные среды).
Диагностика
Когда прямое подключение к базе данных задается с помощью параметра -d,
qhb_restore внутренне выполняет операторы SQL. При возникновении проблем
с запуском qhb_restore убедитесь, что можете выбирать информацию из базы
данных, например с помощью psql. Кроме того, будут применяться параметры
подключения и переменные среды, которые по умолчанию используются библиотекой
libpq на стороне клиента.
Примечания
Если в базу данных template1 в кластере баз были локально установлены какие-либо дополнительные объекты, необходимо проследить за тем, чтобы вывод qhb_dump выгружался в действительно пустую базу данных; в противном случае есть вероятность возникновения ошибок из-за дублирования определений добавленных объектов. Чтобы создать пустую базу данных без каких-либо локальных дополнений, копируйте ее из шаблона template0, а не template1, например:
CREATE DATABASE foo WITH TEMPLATE template0;
Ограничения qhb_restore подробно описаны ниже.
-
При восстановлении данных в существующей таблице и использовании параметра --disable-triggers утилита qhb_restore генерирует команды для выключения триггеров в пользовательских таблицах перед добавлением данных, а затем генерирует команды для их повторного включения после добавления данных. Если восстановление прерывается в середине процесса, системные каталоги могут остаться в неправильном состоянии.
-
qhb_restore не может выборочно восстанавливать большие объекты; например, только для определенной таблицы. Если в архиве содержатся большие объекты, то либо все они будут восстановлены, либо ни один из них, (если они исключены посредством -L, -t или других параметров).
Подробную информацию об ограничениях qhb_dump см. на справочной странице этой утилиты.
После восстановления целесообразно запускать ANALYZE для всех восстановленных
таблиц, чтобы оптимизатор имел полезную статистику; дополнительную информацию см.
в подразделах Обновление статистики планировщика и Процесс «Автовакуум».
Примеры
Предположим, мы выгрузили базу данных mydb в файл специального формата:
$ qhb_dump -Fc mydb > db.dump
Удаление этой базы данных и воссоздание ее из дампа:
$ dropdb mydb
$ qhb_restore -C -d qhb db.dump
База данных, указанная в ключе -d, может быть любой базой данных, существующей
в кластере; qhb_restore использует ее только для выполнения для mydb
команды CREATE DATABASE. С ключом -C данные всегда восстанавливаются в базу
данных с именем, которое фигурирует в файле дампа.
Восстановление данных из дампа в новую базу данных с именем newdb:
$ createdb -T template0 newdb
$ qhb_restore -d newdb db.dump
Обратите внимание, что мы не используем -C, а вместо этого напрямую подключаемся к базе данных, в которую нужно провести восстановление. Также обратите внимание, что мы клонируем новую базу данных из template0, а не template1, чтобы она гарантированно была изначально пуста.
Чтобы изменить порядок элементов базы данных, сначала необходимо выгрузить оглавление архива:
$ qhb_restore -l db.dump > db.list
Файл-список содержит заголовок и по одной строке для каждого элемента, например:
;
; Archive created at Mon Sep 14 13:55:39 2019
; dbname: DBDEMOS
; TOC Entries: 81
; Compression: 9
; Dump Version: 1.10-0
; Format: CUSTOM
; Integer: 4 bytes
; Offset: 8 bytes
; Dumped from database version: 8.3.5
; Dumped by qhb_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA - public pasha
1861; 0 0 COMMENT - SCHEMA public pasha
1862; 0 0 ACL - public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha
Точки с запятой обозначают начало комментария, а цифры в начале строк ссылаются на внутренний идентификатор архива, назначенный каждому элементу.
Строки в этом файле могут быть закомментированы, удалены и переупорядочены. Например:
10; 145433 TABLE map_resolutions qhb
;2; 145344 TABLE species qhb
;4; 145359 TABLE nt_header qhb
6; 145402 TABLE species_records qhb
;8; 145416 TABLE ss_old qhb
может использоваться в качестве входных данных для qhb_restore и восстановит только элементы 10 и 6 в следующем порядке:
qhb_restore -L db.list db.dump