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

См. также

qhb_dump, qhb_dumpall, psql