qhb_dumpall

qhb_dumpall — выгрузить кластер баз данных QHB в файл скрипта

Синтаксис

qhb_dumpall [параметр-подключения...] [параметр...]

qhb_dumpall — это утилита для записи («выгрузки») всех баз данных кластера QHB в один файл скрипта. Этот файл содержит команды SQL, которые можно передать на вход psql для восстановления баз данных. Файл создается путем вызова qhb_dump для каждой базы данных в кластере. qhb_dumpall также выгружает глобальные объекты, общие для всех баз данных, то есть роли и табличные пространства. (Утилита qhb_dump не сохраняет эти объекты.)

Поскольку qhb_dumpall читает таблицы из всех баз данных, для получения полного дампа подключаться, скорее всего, придется от лица суперпользователя. Кроме того, права суперпользователя понадобятся при выполнении сохраненного скрипта, чтобы иметь возможность добавлять роли и создавать базы данных.

SQL-скрипт будет записан в стандартный вывод. Чтобы перенаправить его в файл, используйте параметр -f/--file или операторы оболочки,

qhb_dumpall нужно подключаться к серверу QHB несколько раз (по разу для каждой базы данных). Если вы используете аутентификацию по паролю, эта утилита каждый раз будет запрашивать пароль. В таких случаях удобно иметь файл ~/.pgpass. Дополнительную информацию см. в разделе Файл паролей.

Параметры

Следующие параметры командной строки управляют содержимым и форматом вывода.

-a
--data-only
Выгружать только данные, но не схемы (определения данных).

-c
--clean
Выводить команды SQL для удаления (DROP) всех баз данных, ролей и табличных пространств перед их воссозданием. Этот параметр полезен, когда при восстановлении нужно перезаписать существующий кластер. Если дополнительно не указать --if-exists, то при восстановлении в целевой кластер, где отсутствует какой-либо из этих объектов, будут выводиться безвредные сообщения об ошибке.

-E кодировка
--encoding=кодировка
Создать дамп в заданной кодировке набора символов. По умолчанию дамп создается в кодировке базы данных. (Тот же результат можно получить, задав желаемую кодировку дампа в переменной среды PGCLIENTENCODING.)

-f имя_файла
--file=имя_файла
Отправить вывод в указанный файл. Если этот параметр опущен, используется стандартный вывод.

-g
--globals-only
Выгружать только глобальные объекты (роли и табличные пространства), без баз данных.

-O
--no-owner
Не выводить команды для установки владельца объектов как в исходной базе данных. По умолчанию для назначения владельцев созданных элементов схемы qhb_dumpall выдает команды ALTER OWNER или SET SESSION AUTHORIZATION. Эти команды выполнятся успешно, только если скрипт будет запущен суперпользователем (или владельцем всех объектов в скрипте). Чтобы создать скрипт, который может быть восстановлен любым пользователем, и назначить этого пользователя владельцем всех объектов, укажите -O.

-r
--roles-only
Выгружать только роли, без баз данных или табличных пространств.

-s
--schema-only
Выгружать только определения объектов (схемы), но не сами данные.

-S имя_пользователя
--superuser=имя_пользователя
Задать имя суперпользователя, которое будет использоваться при выключении триггеров. Имеет значение только вместе с параметром --disable-triggers. (Обычно лучше вместо этого запускать итоговый скрипт от лица суперпользователя.)

-t
--tablespaces-only
Выгружать только табличные пространства, без баз данных или ролей.

-v
--verbose
Включает режим подробного вывода. qhb_dumpall будет выводить в стандартный поток ошибок время начала/окончания выгрузки в файл дампа и сообщения о прогрессе выполнения. Если повторить этот параметр, в стандартный поток ошибок будут выводиться дополнительные отладочные сообщения. Этот параметр также действует и на qhb_dump.

-V
--version
Вывести версию qhb_dumpall и завершиться.

-x
--no-privileges
--no-acl
Запретить выгрузку прав доступа (команды GRANT/REVOKE).

--binary-upgrade
Этот параметр предназначен для использования утилитами обновления на месте. Применение в других целях не рекомендуется и не поддерживается. Поведение параметра может быть изменено в будущих версиях без предварительного уведомления.

--column-inserts
--attribute-inserts
Выгружать данные в виде команды INSERT с явными указанием имен столбцов (INSERT INTO таблица (столбец, ...) VALUES ...). Восстановление при этом будет происходить очень медленно; в основном этот вариант оправдан при создании дампов, которые можно загружать в СУБД, отличные от QHB.

--disable-dollar-quoting
Этот параметр выключает возможность заключать тела функций в долларовые кавычки, заставляя использовать кавычки из стандартного синтаксиса SQL.

--disable-triggers
Этот параметр актуален только при создании дампа, содержащего одни данные. Он предписывает qhb_dumpall включать в дамп команды для временного выключения триггеров на целевых таблицах во время восстановления данных. Применяется в ситуациях, когда существуют проверки ссылочной целостности или другие триггеры для таблиц, которые нежелательно вызывать во время восстановления данных.
В настоящее время команды, генерируемые для параметра --disable-triggers, должны выполняться суперпользователем. Следовательно, необходимо задать имя суперпользователя с помощью ключа -S или запустить полученный скрипт от лица суперпользователя.

--exclude-database=шаблон
Не выгружать базы данных, имена которых соответствуют шаблону. Задав ключ --exclude-database несколько раз, можно исключить имена по нескольким шаблонам. Параметр шаблон интерпретируется по тем же правилам, что и шаблон в командах \d утилиты psql (см. Шаблоны), поэтому несколько баз данных также можно исключить, вписав в шаблон подстановочные знаки. Используя такие знаки, не забывайте при необходимости заключать шаблон в кавычки, чтобы их не разворачивала оболочка системы.

--extra-float-digits=число_цифр
Выгружать числа с плавающей запятой не с максимальной доступной точностью, а с заданным значением extra_float_digits. При обычной выгрузке в целях резервного копирования этот параметр использовать не следует.

--if-exists
Использовать команды DROP ... IF EXISTS при удалении объектов в режиме --clean. Это подавляет ошибки «не существует», которые в противном случае могут выводиться. Этот параметр не работает без указания --clean.

--inserts
Выгрузить данные в виде команд INSERT (а не COPY). Восстановление при этом будет происходить очень медленно; в основном этот вариант оправдан при создании дампов, которые можно загружать в СУБД, отличные от QHB. Обратите внимание, что восстановление может полностью провалиться, если в таблицах был изменен порядок столбцов. Параметр --column-inserts безопаснее, но он работает еще медленнее.

--load-via-partition-root
При выгрузке данных партиции таблицы выводить команды COPY или INSERT, ссылающиеся на корневую таблицу в содержащей ее иерархии партиционирования, а не на саму эту партицию. В результате при загрузке данных для каждой строки будет заново выбираться подходящая партиция. Это может быть полезно при восстановлении данных, когда на целевом сервере строки не всегда попадают в те же партиции, в которых они были на исходном сервере. Это возможно, например, когда у столбца разбиения текстовый тип и в двух системах по-разному определено правило сортировки, по которому упорядочивается этот столбец.

--lock-wait-timeout=время_ожидания
Не ждать бесконечно получения совместных блокировок таблиц в начале выгрузки. Вместо этого выдать ошибку, если не удастся заблокировать таблицу за указанное время_ожидания. Время ожидания можно указать в любом из форматов, принимаемых командой SET statement_timeout.

--no-comments
Не выгружать комментарии.

--no-publications
Не выгружать публикации.

--no-role-passwords
Не выгружать пароли для ролей. После восстановления роли получат пароль NULL, и не смогут пройти аутентификацию по паролю, пока им не будут назначены пароли. Поскольку при указании этого параметра значения пароля не нужны, информация о роли читается из представления каталога pg_roles, а не pg_authid. Как следствие, этот параметр также полезен, если доступ к pg_authid ограничен какой-либо политикой безопасности.

--no-security-labels
Не выгружать метки безопасности.

--no-subscriptions
Не выгружать подписки.

--no-sync
По умолчанию qhb_dumpall будет ждать, пока все файлы не будут надежно записаны на диск. Этот параметр заставляет qhb_dumpall завершаться без ожидания, т. е. выполняться быстрее, но впоследствии при неожиданном сбое операционной системы дамп может оказаться поврежден. В целом, этот параметр предназначен для тестирования, и его не следует использовать при выгрузке данных из производственной установки.

--no-table-access-method
Не выводить команды для выбора табличных методов доступа. При указании этого параметра все объекты будут создаваться с тем табличным методом доступа, который устанавливается по умолчанию во время восстановления.

--no-tablespaces
Не выводить команды, создающие или выбирающие табличные пространства для объектов. При указании этого параметра все объекты будут создаваться в том табличном пространстве, которое устанавливается по умолчанию во время восстановления.

--no-toast-compression
Не формировать команды, задающие методы сжатия TOAST. При указании этого параметра все столбцы будут восстановлены с методом сжатия, выбранным по умолчанию.

--no-unlogged-table-data
Не выгружать содержимое нежурналируемых таблиц. Этот параметр не влияет на выгрузку определений (схем) таблиц; он лишь подавляет выгрузку данных из таблиц.

--on-conflict-do-nothing
Добавить предложения ON CONFLICT DO NOTHING в команды INSERT. Этот параметр недопустим, если также не указан --inserts или --column-insert.

--quote-all-identifiers
Принудительно заключить в кавычки все идентификаторы. Этот параметр рекомендуется при выгрузке базы данных с сервера QHB, основная версия которого отличается от версии qhb_dumpall, или когда дамп предназначен для загрузки на сервер с другой основной версией. По умолчанию qhb_dumpall заключает в кавычки только те идентификаторы, которые являются зарезервированными словами в ее собственной основной версии. Иногда это приводит к проблемам совместимости при работе с серверами других версий, в которых наборы зарезервированных слов могут немного отличаться. Использование параметра --quote-all-identifiers предотвращает подобные проблемы ценой ухудшения читаемости скрипта с дампом.

--rows-per-insert=число_строк
Выгружать данные в виде команд INSERT (вместо COPY). Этот параметр определяет максимальное число строк в одной команде INSERT. Указанное значение должно быть больше нуля. Любая ошибка во время восстановления приведет к потере только тех строк INSERT, в которых возникли ошибки, а не всего содержимого таблицы.

--use-set-session-authorization
Выводить команды SET SESSION AUTHORIZATION, соответствующие стандарту SQL, вместо команд ALTER OWNER, чтобы назначить владельцев объекта. В итоге дамп будет более стандартизированным, но, в зависимости от истории объектов, может не восстановиться должным образом.

-?
--help
Показать справку об аргументах командной строки qhb_dumpall и завершиться.

Далее описаны аргументы командной строки, управляющие подключением к базе данных.

-d строка_подключения
--dbname=строка_подключения
Задает параметры, используемые для подключения к серверу, в виде строки подключения; они будут переопределять любые конфликтующие параметры командной строки.
Этот параметр называется --dbname для согласованности с другими клиентскими приложениями, но поскольку qhb_dumpall необходимо подключаться ко многим базам данных, имя базы в строке подключения будет игнорироваться. Чтобы указать имя базы данных для начального подключения, которое будет использоваться при выгрузке глобальных объектов и выявлении других баз, которые необходимо выгрузить, воспользуйтесь параметром -l.

-h хост
--host=хост
Задает имя хост-компьютера, на котором работает сервер. Если значение начинается со слэша, оно используется в качестве каталога для сокета домена Unix. Значение по умолчанию берется из переменной среды PGHOST, если она установлена. В противном случае производится попытка подключения к сокету домена Unix.

-l имя_бд
--database=имя_бд
Задает имя базы данных, через подключение к которой будет производиться выгрузка глобальных объектов и выявление других баз, которые необходимо выгрузить. Если имя не указано, будет использоваться база данных qhb, а если ее не существует — template1.

-p порт
--port=порт
Указывает TCP-порт или расширение файла локального сокета домена Unix, через который сервер принимает подключения. Значение по умолчанию определяется переменной среды PGPORT, если она установлена, или значением по умолчанию, заданным при компиляции.

-U имя_пользователя
--username=имя_пользователя
Имя пользователя, под которым производится подключение.

-w
--no-password
Никогда не запрашивать ввод пароля. Если серверу требуется аутентификация по паролю, и пароль недоступен с помощью иных средств, таких как файл .pgpass, попытка подключения завершится неудачно. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, чтобы ввести пароль.

-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как qhb_dumpall автоматически запросит пароль, если сервер требует аутентификацию по паролю. Однако чтобы выяснить это, qhb_dumpall потребуется дополнительная попытка подключения к серверу. В некоторых случаях имеет смысл ввести -W, чтобы исключить эту лишнюю попытку.
Обратите внимание, что пароль будет запрашиваться для каждой выгружаемой базы данных. Обычно лучше настроить файл ~/.pgpass, чем полагаться на ввод пароля вручную.

--role=имя_роли
Задает имя роли, которая будет использоваться для создания дампа. При указании этого параметра qhb_dumpall выполнит команду SET ROLE имя_роли после подключения к базе данных. Это полезно, когда проходящий проверку пользователь (указанный ключом -U) не имеет прав, требуемых qhb_dumpall, но может переключиться на роль, наделенную этими правами. В некоторых установках имеется политика, запрещающая подключаться к серверу непосредственно от имени суперпользователя, и этот параметр позволяет создавать дампы, не нарушая ее.

Переменные среды

PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию.

PG_COLOR
Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения: always (всегда), auto (автоматически) и never (никогда).

Кроме того, эта утилита, как и большинство других утилит QHB, использует переменные среды, поддерживаемые libpq (см. раздел Переменные среды).

Примечания

Поскольку qhb_dumpall внутри себя вызывает qhb_dump, некоторые диагностические сообщения будут относиться к qhb_dump.

Параметр --clean может быть полезен, даже если вы собираетесь восстановить дамп из скрипта в новом кластере. Использование --clean позволяет скрипту удалять и пересоздавать встроенные базы данных qhb и template1, добиваясь того, чтобы эти базы сохранили свойства (например, локаль и кодировку), которые имели в исходном кластере. Без данного параметра эти базы сохранят свои существующие свойства уровня базы данных, а также все уже существующее содержимое.

После восстановления рекомендуется запускать ANALYZE для каждой базы данных, чтобы оптимизатор получил актуальную статистику. Также можно запустить vacuumdb -a -z для анализа всех баз данных.

Не следует ожидать, что скрипт дампа будет выполняться совсем без ошибок. В частности, поскольку скрипт будет содержать команду CREATE ROLE для каждой роли, существующей в исходном кластере, при попытке создать суперпользователя для начальной загрузки он обязательно получит ошибку «role already exists» (роль уже существует), если только целевой кластер не был инициализирован с другим начальным именем суперпользователя. Эта ошибка безвредна и ее следует игнорировать. Использование параметра --clean, скорее всего, вызовет появления ряда дополнительных безвредных сообщений об ошибках, связанных с несуществующими объектами; их число можно уменьшить, добавив параметр --if-exists.

qhb_dumpall требует, чтобы все необходимые каталоги табличных пространств существовали до восстановления; в противном случае создание базы данных в нестандартном размещении завершится ошибкой.

Примеры

Выгрузка всех баз данных:

$ qhb_dumpall > db.out

Восстановить базу(ы) данных из этого файла можно вот так:

$ psql -f db.out qhb

Неважно, к какой базе данных вы здесь подключаетесь, поскольку файл скрипта, созданный qhb_dumpall, будет содержать соответствующие команды для создания и подключения к сохраненным базам данных. Исключением является случай, если вы указали ключ --clean, — тогда следует сначала подключиться к базе данных qhb; скрипт попытается немедленно удалить другие базы данных, но не сможет удалить базу, к которой вы подключены.

См. также

Подробную информацию об условиях, при которых могут возникнуть ошибки, см. на справочной странице утилиты qhb_dump.