qhb_restore
qhb_restore
- восстанавливает базу данных QHB из файла архива, созданного qhb_dump
Описание
qhb_restore
- это утилита для восстановления базы данных QHB из
архива, созданного qhb_dump в одном из текстовых форматов. Он выдаст
команды, необходимые для восстановления базы данных до состояния, в
котором она находилась на момент сохранения. Архивные файлы также
позволяют qhb_restore
избирательно выбирать то, что восстанавливается,
или даже переупорядочивать элементы перед восстановлением. Архивные
файлы предназначены для переноса между архитектурами.
qhb_restore
может работать в двух режимах. Если указано имя базы данных,
qhb_restore
подключается к этой базе данных и восстанавливает содержимое
архива непосредственно в базу данных. В противном случае сценарий,
содержащий команды SQL, необходимые для перестройки базы данных,
создается и записывается в файл или стандартный вывод. Этот вывод
сценария эквивалентен формату вывода простого текста qhb_dump
. Поэтому
некоторые параметры, управляющие выводом, аналогичны параметрам qhb_dump
.
Очевидно, что qhb_restore
не может восстановить информацию, которой нет
в файле архива. Например, если архив был создан с использованием опции «
сбросить данные как команды INSERT »( qhb_dump --insert ),
qhb_restore
не сможет загружать данные с помощью операторов COPY.
Синтаксис
qhb_restore [connection-option...] [option...] [filename]
Параметры
qhb_restore
принимает следующие аргументы командной строки.
Обратите внимание на то что для многих параметров существуют особенности использования и ознакомьтесь с расширенной справкой в разделе Дополнительная информация по параметрам.
COMMON OPTIONS
Аргумент | Описание |
---|---|
-?, --help | Показать справку об аргументах командной строки и выйти. |
-V, --version | Вывести версию qhb_restore и выйти. |
-v, --verbose | Включить подробный режим. |
GENERAL OPTIONS
Аргумент | Описание |
---|---|
-f, --file=FILENAME | Укажите выходной файл для сгенерированного скрипта или для листинга (ключ -l ). Используйте - для стандартного вывода. |
-F, --format=c, d, t | Укажите формат архива. Обычно нет необходимости указывать формат, так как qhb_restore определит формат автоматически. См Форматы дампов |
-j, --jobs=NUM | Запустить восстановление дампа в NUM потоков. Подробнее. |
CONNECTION OPTIONS
Аргумент | Описание |
---|---|
-d, --dbname=DBNAME | Имя базы данных для подключения. qhb_restore не использует переменную PGDATABASE. |
-h, --host=HOSTNAME | Имя хоста, на котором работает сервер. Если значение начинается с косой черты, оно используется в качестве каталога для сокета домена Unix. Значение по умолчанию берется из переменной среды PGHOST , далее предпринимается попытка подключения через сокет домена Unix. |
-p, --port=PORT | TCP порт или расширение файла локального сокета домена Unix. По умолчанию берётся переменная среды PGPORT , или порт заданный при компиляции. |
-U, --username=USERNAME | Имя пользователя для подключения. |
-w, --no-password | Не запрашивать ввод пароля. Если серверу требуется аутентификация по паролю, а пароль недоступен другими способами, такими как файл .pgpass, попытка подключения завершится неудачно. Эта опция может быть полезна в пакетных заданиях и сценариях, где нет ни одного пользователя для ввода пароля. |
-W, --password | qhb_restore автоматически запросит пароль, если сервер требует аутентификацию по паролю. qhb_restore будет пытаться подключиться, для аутентификации. В некоторых случаях стоит ввести -W чтобы избежать дополнительной попытки подключения. |
--role=ROLENAME | Задает имя роли, которая будет использоваться для восстановления. Подробнее |
OPTIONS
Аргумент | Описание |
---|---|
-a, --data-only | Восстановить только данные, а не схему (определения данных). Данные таблицы, крупные объекты и значения последовательности восстанавливаются, если они присутствуют в архиве. Эта опция похожа, но по историческим причинам не идентична --section=data . |
-c, --clean | Очистить (DROP) объекты базы данных перед их воссозданием. (Если не используется --if-exists это может привести к сообщениям об ошибках, если какие-либо объекты не присутствуют в целевой базе данных.) |
-C, --create | Создать базу данных перед ее восстановлением. Подробнее |
-e, --exit-on-error | Выйти, если при отправке команд SQL в базу данных возникла ошибка. По умолчанию работа продолжается, а количество ошибок отображается в конце восстановления. |
-I index, --index=index | Восстановить определение только именованного индекса. Несколько индексов могут быть указаны с несколькими ключами -I . |
-l, --list | Создать оглавление архива Подробнее |
-L, --use-list=FILENAME | Восстановление по оглавлению Подробнее |
-n, --schema=SCHEMA | Восстановить объекты только из указанной схемы. Несколько схем могут быть указаны с несколькими ключами -n . Комбинируется с опцией -t чтобы восстановить только определенную таблицу. |
-N, --exclude-schema=SCHEMA | Не восстанавливать объекты из указанной схеме. Исключает несколько схем, с несколькими ключами -N . Ключ -N приоритетнее чем-n , при одновременном указании - схема исключается. |
-O, --no-owner | Не выполнять команды для установки владельца объектов в соответствии с исходной базой данных. Подробнее |
-P, --function=NAME(args) | Восстановить только указанную функцию. Указывайте имя функции и аргументы в точности, как они указаны в оглавлении файла дампа. Несколько функций могут быть указаны с несколькими ключами -P . |
-s, --schema-only | Восстановить только схему (определения данных), а не данные. Подробнее |
-S, --superuser=NAME | Имя суперпользователя, которое будет использоваться при отключении триггеров. Актуально, только для --disable-triggers . |
-t, --table=NAME | Восстановить определение и/или данные только указанной таблицы. Подробнее |
-T, --trigger=NAME | Восстановить только названый триггер. Несколько триггеров могут быть указаны с несколькими ключами -T . |
-x, --no-privileges | Пропустить восстановление прав доступа (команды GRANT / REVOKE). |
-1, --single-transaction | Выполнить восстановление как одну транзакцию (обернуть отправленные команды в BEGIN / COMMIT ). Гарантирует что все команды завершаться успешно, либо изменения не применяются. Эта опция подразумевает --exit-on-error . |
--disable-triggers | Отключение триггеров при восстановлении. Подробнее |
--enable-row-security | Восстанавливать данные из таблиц с защитой строк. Подробнее |
--if-exists | Использовать условные команды (добавить IF EXISTS ) при очистке объектов базы данных. Не работает без --clean . |
--no-comments | Не восстанавливать комментарии даже если архив содержит их. |
--no-publications | Не восстанавливать публикации даже если архив содержит их. |
--no-security-labels | Не восстанавливать защитные метки даже если архив содержит их. |
--no-subscriptions | Не восстанавливать подписки даже если архив содержит их. |
--no-tablespaces | Не восстанавливать табличные пространства. Все объекты будут восстановлены в табличном пространстве по умолчанию. |
--no-data-for-failed-tables | Не восстанавливать данные в таблицы которые не удалось создать Подробнее |
--section=SECTION | Восстановить только указанный раздел. Имя раздела может быть pre-data, data, post-data . Подробнее |
--strict-names | Требовать строго соответствия схем и таблиц таковым в файле резервной копии. Подробнее |
--use-set-session-authorization | Использовать стандартные SQL команды для назначения владельцев объектов. Подробнее |
Дополнительная информация по параметрам
ROLENAME
--role=rolename
Указывает имя роли, которое будет использоваться для восстановления.
Эта опция заставляет qhb_restore
выдавать команду SET ROLE rolename
после подключения к базе данных. Это полезно, когда
аутентифицированному пользователю (указанному -U
) не хватает
привилегий, необходимых для qhb_restore
, но он может переключиться
на роль с необходимыми правами. В некоторых установках есть
политика, запрещающая вход в систему непосредственно от имени
суперпользователя, и использование этого параметра позволяет
выполнять восстановление без нарушения политики.
create
-C, --create
Создать базу данных перед ее восстановлением. Если также указан
параметр --clean
удалить и заново создать целевую базу данных
перед подключением к ней.
С помощью qhb_restore --create
также восстанавливаются комментарий
базы данных, если он есть, и любые параметры переменной
конфигурации, специфичные для этой базы данных, то есть любые ALTER DATABASE ... SET ...
и ALTER ROLE ... IN DATABASE ... SET ...
команды, которые упоминают эту базу данных. Права доступа к самой
базе данных также восстанавливаются, если не указан параметр
--no-acl
.
Когда используется эта опция, база данных с именем -d
используется
только для выдачи начальных команд DROP DATABASE
и CREATE DATABASE
.
Все данные восстанавливаются в базу данных по имени которое указано
в архиве.
Параллельное восстановление
-j NUM, --jobs=NUM
Запускайте самые трудоемкие части qhb_restore
- те, которые
загружают данные, создают индексы или создают ограничения -
используя несколько одновременных заданий. Эта опция может
значительно сократить время восстановления большой базы данных на
сервере, работающем на многопроцессорной машине.
Каждое задание представляет собой один процесс или один поток, в зависимости от операционной системы, и использует отдельное соединение с сервером.
Оптимальное значение для этого параметра зависит от аппаратной настройки сервера, клиента и сети. Факторы включают количество ядер ЦП и настройку диска. Как правило, можно установить параметр равным количеству ядер ЦП на сервере, но значения, превышающие это, во многих случаях также могут привести к более быстрому восстановлению. Конечно, слишком высокие значения приведут к снижению производительности из-за перегрузки.
Эта опция поддерживает только пользовательские форматы и форматы
каталогов. Входными данными должен быть обычный файл или каталог
(не, например, канал). Этот параметр игнорируется при создании
сценария, а не при подключении напрямую к серверу базы данных. Кроме
того, несколько заданий нельзя использовать вместе с опцией --single-transaction
.
Оглавление архива
-l, --list
Вывести оглавление архива. Выходные данные этой операции могут
использоваться как входные данные для опции -L
. Обратите внимание,
что если с -l
используются переключатели фильтрации, такие как -n
или -t
, они ограничат перечисленные элементы.
-L FILENAME, --use-list=FILENAME
Восстановите только те элементы архива, которые перечислены в
FILENAME
, и восстановите их в порядке их появления в файле.
Обратите внимание, что если с -L
используются переключатели
фильтрации, такие как -n
или -t
, они еще больше ограничат
восстановленные элементы.
Входной файл обычно создается путем редактирования вывода предыдущей
операции -l
. Строки можно перемещать или удалять, а также
закомментировать, поместив точку с запятой ( ;
) в начале строки.
Смотрите ниже примеры.
no owner
-O, --no-owner
Не выполнять команды для установки владельца объектов в соответствии
с исходной базой данных. По умолчанию qhb_restore
выдает операторы
ALTER OWNER
или SET SESSION AUTHORIZATION
чтобы установить владельца
созданных элементов схемы. Эти операторы потерпят неудачу, если
исходное соединение с базой данных установлено не суперпользователем
(или пользователем, которому принадлежат все объекты в сценарии).
С ключом -O
любой пользователь может использоваться для
начального соединения, и этот пользователь будет владеть всеми
созданными объектами.
schema only
-s, --schema-only
Восстановить только схему (определения данных), а не данные, в той степени, в которой записи схемы присутствуют в архиве.
Эта опция является обратной к --data-only
. Это похоже на, но по
историческим причинам не идентично указанию --section=pre-data
--section=post-data
.
(Не путайте это с параметром --schema
, который использует слово «
схема » в другом значении.)
table
-t table, --table= table
Восстановить определение и / или данные только указанной таблицы.
В этом случае «таблица» включает в себя представления,
материализованные представления, последовательности и сторонние
таблицы. Несколько таблиц можно выбрать, написав несколько ключей -t
.
Эта опция может быть объединена с опцией -n
для указания таблиц в
конкретной схеме.
Заметка
Если указан параметр-t
,qhb_restore
не пытается восстановить какие-либо другие объекты базы данных, от которых могут зависеть выбранные таблицы. Следовательно, нет гарантии, что восстановление определенной таблицы в чистую базу данных будет успешным.
Заметка
Этот флаг не ведет себя идентично флагу -tqhb_dump
. В настоящее время вqhb_restore
нет условий для подстановочных знаков, и вы не можете включить имя схемы в его -t. И хотя флаг -tqhb_dump
также будет выгружать вспомогательные объекты (например, индексы) выбранных таблиц, флаг-t
qhb_restore
не включает такие вспомогательные объекты.
Отключение триггеров
--disable-triggers
Эта опция актуальна только при выполнении восстановления только
данных. Опция инструктирует qhb_restore
выполнять команды для
временного отключения триггеров на целевых таблицах во время
загрузки данных. Используйте, если есть проверки ссылочной целостности или
другие триггеры для таблиц, которые не нужно вызывать во время
восстановления данных.
В настоящее время команды, отправляемые для --disable-triggers
должны выполняться как суперпользователь. Поэтому вы должны также
указать имя суперпользователя с помощью -S
или, предпочтительно,
запустить qhb_restore
как суперпользователь.
Защита строк
--enable-row-security
Эта опция актуальна только при восстановлении содержимого таблицы с
защитой строк. По умолчанию qhb_restore
выключит row_security
,
чтобы все данные были восстановлены в таблице. Если у пользователя
недостаточно прав для обхода защиты строк, выдается ошибка. Этот
параметр указывает qhb_restore
включить вместо row_security
значение, позволяющее пользователю попытаться восстановить
содержимое таблицы с включенной защитой строк. Это может по-прежнему
не работать, если пользователь не имеет права вставлять строки из
дампа в таблицу.
Обратите внимание, что этот параметр также требует, чтобы дамп был в формате INSERT, так как COPY FROM не поддерживает безопасность строк.
no-data-for-failed-tables
--no-data-for-failed-tables
По умолчанию данные таблицы восстанавливаются, даже если команда создания таблицы не выполнена (например, потому что она уже существует). С этой опцией данные для такой таблицы пропускаются. Это поведение полезно, если целевая база данных уже содержит требуемое содержимое таблицы. Например, вспомогательные таблицы для расширений QHB, таких, как PostGIS, могут быть уже загружены в целевую базу данных; указание этого параметра предотвращает загрузку в них дубликатов или устаревших данных.
Этот параметр действует только при восстановлении непосредственно в базу данных, но не при выводе сценария SQL.
Section
--section=SECTION
Восстановить только указанный раздел. Имя раздела может быть
pre-data, data, post-data
. Эта опция может быть указана более
одного раза, чтобы выбрать несколько разделов. По умолчанию
восстанавливается все разделы.
Раздел данных содержит фактические данные таблиц, а также определения крупных объектов. Элементы после данных состоят из определений индексов, триггеров, правил и ограничений, отличных от проверенных проверочных ограничений. Элементы предварительных данных состоят из всех других элементов определения данных.
strict-names
--strict-names
Проверять в обязательном порядке, чтобы каждая схема ( -n / --schema
)
и --schema
таблицы (-t / --table
) соответствовали
хотя бы одной схеме / таблице в файле резервной копии.
use-set-session-authorization
--use-set-session-authorization
Использовать стандартные команды SQL SET SESSION AUTHORIZATION
вместо
команд ALTER OWNER
для назначения принадлежности объектов.
Это делает скрипт более совместимым со стандартами, но в зависимости от
истории объектов в дампе, восстановление может произойти не должным образом.
Окружение
qhb_restore
не использует переменную PGDATABASE, если имя базы данных не указано.
PGHOST
PGOPTIONS
PGPORT
PGUSER
- Параметры подключения по умолчанию
PG_COLOR
- Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения always, auto, never .
Эта утилита, как и большинство других утилит QHB, также использует переменные среды, поддерживаемые libpq.
Диагностика
Когда прямое соединение с базой данных указывается с помощью опции -d
,
qhb_restore
внутренне выполняет операторы SQL. Если у вас возникли
проблемы с запуском qhb_restore
, убедитесь, что вы можете выбирать
информацию из базы данных, используя, например, qsql. Кроме того, будут
применяться любые параметры подключения по умолчанию и переменные среды,
используемые интерфейсной библиотекой libpq .
Примечания
Если в вашей установке есть какие-либо локальные дополнения к базе
данных template1, будьте осторожны, чтобы загрузить вывод qhb_restore
в
действительно пустую базу данных; в противном случае вы можете получить
ошибки из-за дублирования определений добавленных объектов. Чтобы
создать пустую базу данных без каких-либо локальных дополнений,
скопируйте из template0 не из template1, например:
CREATE DATABASE foo WITH TEMPLATE template0;
Ограничения
Ограничения qhb_restore
подробно описаны ниже.
При восстановлении данных в существующей таблице и использовании
опции --disable-triggers
, утилита qhb_restore
генерирует команды для
отключения триггеров в пользовательских таблицах перед вставкой
данных, а затем выполняет команды для их повторного включения после
вставки данных. Если восстановление остановлено в середине,
системные каталоги могут остаться в неправильном состоянии.
qhb_restore
не может выборочно восстанавливать большие объекты;
например, только для определенной таблицы. Если в архиве содержатся
большие объекты, то все большие объекты будут восстановлены, или ни
один из них, если они исключены с помощью -L
, -t
или других
параметров.
Смотрите также документацию по qhb_dump для подробностей об ограничениях
qhb_dump
.
Файл дампа, созданный qhb_dump
, не содержит статистику, используемую
оптимизатором для принятия решений по планированию запросов. Поэтому
целесообразно запускать ANALYZE
после восстановления из дампа,
чтобы обеспечить оптимальную производительность;
см. раздел Обновление статистики планировщика и
раздел Процесс «Автовакуум» для получения дополнительной информации.
Примеры
Предположим, мы сделали дамп базы данных mydb
в пользовательском формате:
$ qhb_dump -Fc mydb > db.dump
Чтобы удалить базу данных и воссоздать ее из дампа:
$ dropdb mydb
$ qhb_restore -C -d qhb db.dump
База данных, указанная в -d
может быть любой базой данных, существующей
в кластере; qhb_restore
использует его только для выдачи команды CREATE DATABASE
для mydb
. С ключом -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