qhb_dump
qhb_dump — выгрузить базу данных QHB в файл скрипта или другой архивный файл
Синтаксис
qhb_dump [параметр-подключения...] [параметр...] [имя_бд]
Описание
qhb_dump — это утилита для резервного копирования базы данных QHB. Она создает согласованные резервные копии, даже если база данных параллельно используется. qhb_dump не блокирует доступ к базе данных другим пользователям (ни для чтения, ни для записи).
Утилита qhb_dump выгружает только одну базу данных. Для резервного копирования всего кластера или глобальных объектов, общих для всех баз данных в кластере (например, ролей и табличных пространств), следует применять программу qhb_dumpall.
Дампы можно создавать в форматах скрипта или архивного файла. Дампы в скриптах представляют собой текстовые файлы, содержащие команды SQL, необходимые для восстановления базы данных до состояния, в котором она находилась на момент сохранения. Для восстановления из такого скрипта нужно передать его psql. Файлы скрипта можно использовать для восстановления базы данных на других компьютерах и в других архитектурах, а с некоторыми модификациями — даже в других SQL-совместимых СУБД.
Для восстановления базы данных из альтернативных архивных форматов следует применять утилиту qhb_restore. Эти форматы позволяют qhb_restore избирательно восстанавливать данные или даже изменять порядок восстанавливаемых элементов. Архивные форматы предназначены для переноса на платформы с иной архитектурой.
Применение архивных форматов и сочетание утилит qhb_restore и qhb_dump обеспечивает гибкий механизм архивирования и переноса данных. qhb_dump можно использовать для резервного копирования всей базы данных, затем с помощью qhb_restore проверить архив и/или выбрать, какие части базы данных нужно восстановить. Наиболее гибкими форматами выходных файлов являются «custom» (-Fc) и «directory» (-Fd). Они позволяют выбирать и переупорядочивать все заархивированные элементы, поддерживают многопоточное восстановление, а также сжимаются по умолчанию. При этом только формат «directory» поддерживает многопоточную выгрузку.
Во время работы qhb_dump необходимо проверять выходные данные на наличие предупреждений (они выводятся в стандартный поток ошибок), особенно в свете перечисленных ниже ограничений.
Параметры
Следующие параметры командной строки управляют содержимым и форматом вывода.
имя_бд
Задает имя базы данных, из которой будет выгружаться дамп. Если имя не задано,
используется значение переменной среды PGDATABASE. Если и переменная не
задана, используется имя пользователя, под которым производится подключение.
-a
--data-only
Выгружать только данные, но не схемы (определения данных). Будут выгружены
данные таблиц, большие объекты и значения последовательностей.
Этот параметр схож с указанием --section=data, но по историческим причинам не
идентичен.
-b
--blobs
Включить в дамп большие объекты. Это поведение по умолчанию, если только не
указаны --schema, --table или --schema-only. Поэтому ключ -b
полезен только для добавления больших объектов в дампы, где требовалась конкретная
схема или таблица. Обратите внимание, что большие бинарные объекты относятся к
данным и поэтому будут включены при использовании --data-only, но не
--schema-only.
-B
--no-blobs
Исключить большие объекты из дампа.
Когда заданы и -b, и -B, большие объекты при выгрузке данных будут
выводиться (см. описание -b).
-c
--clean
Включить в выходной файл команды удаления (DROP) всех выгружаемых объектов базы
данных перед командами создания этих объектов. Этот параметр полезен, когда при
восстановлении нужно переписать существующую базу данных. Если дополнительно не
указать --if-exists, то при восстановлении в целевую базу данных, где
отсутствует какой-либо из этих объектов, будут выводиться безвредные сообщения
об ошибке.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для таких архивных форматов этот параметр можно указать при вызове
qhb_restore.
-C
--create
Начать вывод с команды для создания базы данных и последующего подключения к ней.
(При такой форме скрипта не важно, к какой базе из целевой установки было
произведено подключение перед выполнением этого скрипта.) Если дополнительно
указано --clean, то скрипт удаляет и пересоздает целевую базу данных перед
повторным подключением к ней.
С --create в вывод также включается комментарий к базе данных (если таковой
имеется) и все параметры переменных конфигурации, специфичные для этой базы
данных, то есть все команды ALTER DATABASE ... SET ... и ALTER ROLE ... IN DATABASE ... SET ..., где упоминается эта база. Также выгружаются права
доступа к самой базе данных, если не указано --no-acl.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для таких архивных форматов этот параметр можно указать при вызове
qhb_restore.
-e шаблон
--extension=шаблон
Выгрузить только расширения, соответствующие шаблону. Когда этот параметр
не задан, будут выгружены все несистемные расширения в целевой базе данных. Задав
ключ -e несколько раз, можно выбрать несколько расширений. Параметр шаблон
интерпретируется по тем же правилам, что и шаблон в командах \d утилиты
psql (см. Шаблоны), поэтому несколько расширений также можно выбрать,
вписав в шаблон подстановочные знаки. Используя такие знаки, не забывайте при
необходимости заключать шаблон в кавычки, чтобы их не разворачивала оболочка
системы.
Если расширение указано в --extension, в дамп включаются все его
конфигурационные отношения, зарегистрированные функцией pg_extension_config_dump.
Примечание
При указании -e утилита qhb_dump не пытается выгружать прочие объекты базы данных, от которых могут зависеть выбранные расширения. Таким образом, нет гарантии, что эти расширения будут успешно восстановлены в чистой базе данных.
-E кодировка
--encoding=кодировка
Создать дамп в заданной кодировке набора символов. По умолчанию дамп создается в
кодировке базы данных. (Тот же результат можно получить, задав желаемую кодировку
в переменной среды PGCLIENTENCODING.) Поддерживаемые кодировки описаны в
подразделе Поддерживаемые кодировки.
-f файл
--file=файл
Отправить вывод в заданный файл. Этот параметр можно опустить для форматов
с выводом в файл, поскольку в этом случае используется стандартный вывод.
Однако его обязательно следует задавать для формата с выводом в каталог, где
этот параметр задает путь не к файлу, а к целевому каталогу. В этом случае каталог
создается qhb_dump и не должен существовать заранее.
-F формат
--format=формат
Задает формат вывода дампа. формат может принимать следующие значения:
- p
plain
Вывести простой текстовый SQL-скрипт (поведение по умолчанию). - c
custom
Вывести данные в специальном архивном формате, пригодном для использования утилитой qhb_restore. Вместе с форматом каталога это наиболее гибкий формат вывода, поскольку он позволяет вручную выбирать и переупорядочивать заархивированные элементы во время восстановления. Кроме того, вывод в этом формате по умолчанию сжимается. - d
directory
Вывести данные в архиве в формате каталога, пригодном для использования утилитой qhb_restore. При этом будет создан каталог, в котором у каждой выгруженной таблицы и большого объекта будет отдельный файл, а также будет создан так называемый файл-оглавление, описывающий выгруженные объекты в машиночитаемом формате, понятном qhb_restore. С архивом в формате каталога можно работать стандартными средствами Unix; например, файлы в несжатом архиве можно сжать с помощью gzip. Этот формат по умолчанию сжимается, а также поддерживает многопоточную выгрузку. - t
tar
Вывести данные в архиве в формате tar, пригодном для использования утилитой qhb_restore. Он совместим с форматом каталога: при распаковке архива в формате tar создается корректная копия в формате каталога. Однако этот формат не поддерживает сжатие. Кроме того, при использовании формата tar нельзя изменить относительный порядок элементов данных в таблице во время восстановления.
-j число_заданий
--jobs= число_заданий
Запустить многопоточную выгрузку, обрабатывая одновременно несколько таблиц (в
количестве число_заданий). Это может сократить время создания дампа, но
при этом увеличивает нагрузку на сервер баз данных. Этот параметр можно
использовать только с форматом вывода в каталог, так как это единственный формат,
в котором несколько процессов могут записывать данные одновременно.
qhb_dump откроет число_заданий + 1 соединений с базой данных, поэтому
необходимо установить такое значение параметра max_connections, которое бы
покрыло все эти соединения.
Если при многопоточной выгрузке будут запрашиваться эксклюзивные блокировки на
объекты базы данных, может произойти сбой. Причина этого в том, что главный
процесс qhb_dump запрашивает совместные блокировки (ACCESS SHARE) для
объектов, которые позже будут выгружать рабочие процессы, чтобы никто не удалил
их во время создания дампа. Если после этого другой клиент запросит эксклюзивную
блокировку таблицы, этот запрос будет поставлен в очередь в ожидании снятия совместной
блокировки главного процесса. В последующем любая попытка доступа к таблице также
будет поставлена в очередь после запроса на эксклюзивную блокировку. В том числе в
очередь попадет и рабочий процесс, пытающийся выгрузить таблицу. Если не принять
никаких мер предосторожности, получится классическая взаимоблокировка. Для выявления
таких конфликтов рабочий процесс qhb_dump запрашивает еще одну совместную
блокировку, используя параметр NOWAIT. И если она не получит эту блокировку,
значит, кто-то еще запросил эксклюзивную блокировку и нет возможности продолжить
выгрузку, поэтому qhb_dump придется ее прервать.
Для получения согласованной резервной копии сервер баз данных должен поддерживать
возможность синхронизированных снимков. Благодаря этой функциональности клиенты базы
данных могут быть уверены, что видят одну и ту же версию данных, несмотря на
использование разных подключений. qhb_dump -j использует множественные
подключения к базе данных; первое подключение происходит с главным процессом, а
последующие — с рабочими процессами. Без возможности синхронизированных снимков
нет гарантии, что разные рабочие процессы в каждом подключении увидят одни и те же
данные, что может привести к несогласованности данных резервной копии.
-n шаблон
--schema= шаблон
Выгрузить только схемы, соответствующие шаблону; вместе со схемами будут
выгружены и все содержащиеся в них объекты. Если этот параметр не задан, будут
выгружены все несистемные схемы в целевой базе данных. Задав ключ -n несколько
раз, можно выбрать несколько схем. Значение шаблон интерпретируется по тем
же правилам, что и шаблон в командах \d утилиты psql (см. Шаблоны),
поэтому несколько схем также можно выбрать, вписав в шаблон подстановочные знаки.
Используя такие знаки, не забывайте при необходимости заключать шаблон в кавычки,
чтобы их не разворачивала оболочка системы; см. Примеры ниже.
Примечание
При указании -n утилита qhb_dump не пытается выгружать прочие объекты базы данных, от которых могут зависеть выбранные схемы. Таким образом, нет гарантии, что эти схемы будут успешно восстановлены в чистой базе данных.
Примечание
Объекты, не принадлежащие схемам, например, большие бинарные объекты, при указании -n не выводятся. Однако их можно добавить в дамп с помощью ключа --blobs.
-N шаблон
--exclude-schema=шаблон
Не выгружать схемы, соответствующие шаблону. Шаблон интерпретируется по тем
же правилам, что и для -n. Задав ключ -N несколько раз, можно исключить
схемы, соответствующие любому из нескольких шаблонов.
Когда заданы и -n, и -N, в дамп включаются схемы, соответствующие как
минимум одному ключу -n и не совпадающие ни с одним из ключей -N.
Если ключ -N задается один, то соответствующие ему схемы исключаются из
в остальном обычного дампа.
-O
--no-owner
Не формировать команды для установки владельца объектов как в исходной
базе данных. По умолчанию для назначения владельцев созданных объектов базы данных
qhb_dump создает команды ALTER OWNER или SET SESSION AUTHORIZATION.
Эти команды выполнятся успешно, только если скрипт будет запущен суперпользователем
(или владельцем всех объектов в скрипте). Чтобы создать скрипт, который может быть
восстановлен любым пользователем, и назначить этого пользователя владельцем всех
объектов, укажите -O.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для архивных форматов этот параметр можно указать при вызове
qhb_restore.
-R
--no-reconnect
Этот параметр устарел, но все еще принимается в целях обратной совместимости.
-s
--schema-only
Выгрузить только определения объектов (схемы), но не сами данные.
Этот параметр действует противоположно --data-only. Он похож на указание
--section=pre-data --section=post-data, но по историческим причинам не
идентичен ему.
(Не путайте его с параметром --schema, который использует термин «схема» в
другом значении.)
Чтобы исключить данные таблицы только для подмножества таблиц в базе данных,
используйте параметр --exclude-table-data.
-S имя_пользователя
--superuser=имя_пользователя
Задать имя суперпользователя, которое будет использоваться при выключении
триггеров. Имеет значение только вместе с параметром --disable-triggers.
(Обычно лучше вместо этого запускать полученный скрипт от лица суперпользователя.)
-t шаблон
--table=шаблон
Выгрузить только таблицы, соответствующие шаблону. Задав ключ -t
несколько раз, можно выбрать несколько таблиц. Параметр шаблон
интерпретируется по тем же правилам, что и шаблон в командах \d утилиты
psql (см. Шаблоны), поэтому несколько таблиц также можно выбрать,
вписав в шаблон подстановочные знаки. Используя такие знаки, не забывайте при
необходимости заключать шаблон в кавычки, чтобы их не разворачивала оболочка
системы; см. Примеры ниже.
Помимо таблиц с этим параметром можно выгрузить определения соответствующих
шаблону представлений, материализованных представлений, сторонних таблиц и
последовательностей. При этом содержимое представлений и материализованных
представлений выгружаться не будет, а содержимое сторонних таблиц будет выгружено,
только если в параметре --include-foreign-data задан соответствующий сторонний
сервер.
При использовании -t не действуют ключи -n и -N, так как выбранные с
его помощью таблицы все равно будут выгружаться, а нетабличные объекты выгружаться
не будут.
Примечание
При указании -t утилита qhb_dump не пытается выгружать прочие объекты базы данных, от которых могут зависеть выбранные таблицы. Таким образом, нет гарантии, что эти таблицы будут успешно восстановлены в чистой базе данных.
-T шаблон
--exclude-table=шаблон
Не выгружать таблицы, соответствующие шаблону. Шаблон интерпретируется по
тем же правилам, что и для -t. Задав ключ -T несколько раз, можно исключить
таблицы, соответствующие любому из нескольких шаблонов.
Когда заданы и -t, и -T, в дамп включаются таблицы, соответствующие как
минимум одному ключу -t и не совпадающие ни с одним из ключей -N.
Если ключ -T задается один, то соответствующие ему таблицы исключаются из
обычного дампа.
-v
--verbose
Включить режим подробного вывода. qhb_dump будет выводить в стандартный
поток ошибок подробные комментарии к объектам и время начала/окончания выгрузки в
файл дампа, а также сообщения о прогрессе выполнения. Если повторить этот параметр,
в стандартный поток ошибок будут выводиться дополнительные отладочные сообщения.
-V
--version
Вывести версию qhb_dump и завершиться.
-x
--no-privileges
--no-acl
Запретить выгрузку прав доступа (команды GRANT/REVOKE).
-Z 0-9
--compress=0-9
Задать уровень сжатия данных. При нулевом значении сжатие отсутствует. Для архивов
специального формата и формата каталога будут сжиматься отдельные сегменты
табличных данных, и по умолчанию используется умеренный уровень сжатия. Если
указать ненулевой уровень сжатия для простого текстового формата, сжиматься будет
весь выходной файл, как если бы он был передан через gzip; по умолчанию простой
формат не сжимается. Формат архива tar в настоящее время сжатие не поддерживает.
--binary-upgrade
Этот параметр предназначен для использования утилитами обновления на месте.
Применение в других целях не рекомендуется и не поддерживается. Поведение
параметра может быть изменено в будущих версиях без предварительного уведомления.
--column-inserts
--attribute-inserts
Выгружать данные в виде команды INSERT с явными указанием имен столбцов
(INSERT INTO таблица (столбец, ...) VALUES ...). Восстановление при этом будет
происходить очень медленно; в основном этот вариант оправдан при создании дампов,
которые можно загружать в СУБД, отличные от QHB. Любая ошибка во
время восстановления приведет к потере только тех строк INSERT, в которых возникли
ошибки, а не всего содержимого таблицы.
--disable-dollar-quoting
Этот параметр выключает возможность заключать тела функций в долларовые кавычки,
заставляя использовать кавычки из стандартного синтаксиса SQL.
--disable-triggers
Этот параметр актуален только при создании дампа, содержащего одни данные. Он
предписывает qhb_dump включать в дамп команды для временного выключения
триггеров на целевых таблицах во время восстановления данных. Применяется в
ситуациях, когда существуют проверки ссылочной целостности или другие триггеры
для таблиц, которые нежелательно вызывать во время восстановления данных.
В настоящее время команды, генерируемые для --disable-triggers, должны
выполняться суперпользователем. Следовательно, необходимо задать имя
суперпользователя с помощью ключа -S или запустить полученный скрипт от лица
суперпользователя.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для архивных форматов этот параметр можно указать при вызове
qhb_restore.
--enable-row-security
Этот параметр представляет интерес только при выгрузке содержимого таблиц, в
которых есть защита строк. По умолчанию qhb_dump устанавливает в
row_security значение off (выключен), чтобы из таблицы были гарантированно
выгружены все данные. Если у пользователя недостаточно прав для обхода защиты
строк, возникает ошибка. Этот параметр предписывает qhb_dump установить в
row_security значение on (включен), позволяя пользователю выгрузить части
содержимого таблицы, к которым у него есть доступ.
Обратите внимание, что в настоящее время при использовании этого параметра
желательно, чтобы дамп был в формате INSERT, так как команда COPY FROM в
процессе восстановления не поддерживает защиту строк.
--exclude-table-data=шаблон
Не выгружать данные из таблиц, соответствующих шаблону. Шаблон
интерпретируется по тем же правилам, что и для -t. Задав ключ
--exclude-table-data несколько раз, можно исключить таблицы, соответствующие
любому из нескольких шаблонов. Этот параметр полезен, когда необходимо получить
определение конкретной таблицы, но содержащиеся в ней данные не нужны.
Чтобы не выгружать данные из всех таблиц базы, воспользуйтесь --schema-only.
--extra-float-digits=число_цифр
Выгружать числа с плавающей запятой не с максимальной доступной точностью, а с
заданным значением extra_float_digits. При обычной выгрузке в целях
резервного копирования этот параметр использовать не следует.
--if-exists
Использовать команды DROP ... IF EXISTS при удалении объектов в режиме
--clean. Это подавляет ошибки «не существует», которые в противном случае
могут выводиться. Этот параметр не работает без указания --clean.
--include-foreign-data=сторонний_сервер
Выгрузить данные всех сторонних таблиц со стороннего сервера, имя которого
соответствует шаблону сторонний_сервер. Задав ключ --include-foreign-data
несколько раз, можно выбрать несколько сторонних серверов. Кроме того, параметр
сторонний_сервер интерпретируется по тем же правилам, что и шаблон в
командах \d утилиты psql (см. Шаблоны), поэтому несколько сторонних
серверов также можно выбрать, вписав в шаблон подстановочные знаки. Используя
такие знаки, не забывайте при необходимости заключать шаблон в кавычки, чтобы их
не разворачивала оболочка системы; см. Примеры ниже. Единственное отличие от
этих правил в том, что шаблон не может быть пустым.
Примечание
При указании --include-foreign-data утилита qhb_dump не проверяет возможность записи в стороннюю таблицу. Таким образом, нет гарантии, что выгруженная сторонняя таблица может быть успешно восстановлена.
--inserts
Выгрузить данные в виде команд INSERT (а не COPY). Восстановление при этом
будет происходить очень медленно; в основном этот вариант оправдан при создании
дампов, которые можно загружать в СУБД, отличные от QHB. Любая
ошибка во время восстановления приведет к потере только тех строк INSERT, в
которых возникли ошибки, а не всего содержимого таблицы. Обратите внимание, что
восстановление может полностью провалиться, если у таблицы был изменен порядок
столбцов. В таком случае можно воспользоваться параметром --column-inserts,
для которого порядок столбцов не важен, но он работает еще медленнее.
--load-via-partition-root
При выгрузке данных партиции таблицы выводить команды COPY или INSERT,
ссылающиеся на корневую таблицу в содержащей ее иерархии партиционирования, а не
на саму эту партицию. В результате при загрузке данных для каждой строки будет
заново выбираться подходящая партиция. Это может быть полезно при перезагрузке
данных, когда на целевом сервере строки не всегда попадают в те же партиции, в
которых они были на исходном сервере. Это возможно, например, когда у столбца
разбиения текстовый тип и в двух системах по-разному определено правило
сортировки, по которому упорядочивается этот столбец.
--lock-wait-timeout=время_ожидания
Не ждать бесконечно получения совместных блокировок таблиц в начале выгрузки.
Вместо этого выдать ошибку, если не удастся заблокировать таблицу за указанное
время_ожидания. Время ожидания можно указать в любом из форматов,
принимаемых командой SET statement_timeout. (Допустимые форматы различаются в
зависимости от версии сервера, с которого выгружаются данные, однако целое число
миллисекунд принимается всеми версиями.)
--no-comments
Не выгружать комментарии.
--no-publications
Не выгружать публикации.
--no-security-labels
Не выгружать метки безопасности.
--no-subscriptions
Не выгружать подписки.
--no-sync
По умолчанию qhb_dump будет ждать, пока все файлы не будут надежно записаны
на диск. Этот параметр заставляет qhb_dump завершаться без ожидания, т. е.
выполняться быстрее, но впоследствии при неожиданном сбое операционной системы
дамп может оказаться поврежден. В целом, этот параметр предназначен для
тестирования, и его не следует использовать при выгрузке данных из производственной
установки.
--no-table-access-method
Не выводить команды для выбора табличных методов доступа. При указании этого
параметра все объекты будут создаваться с тем табличным методом доступа, который
устанавливается по умолчанию во время восстановления.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для архивных форматов этот параметр можно указать при вызове qhb_restore.
--no-tablespaces
Не выводить команды для выбора табличных пространств. При указании этого
параметра все объекты будут создаваться в том табличном пространстве, которое
устанавливается по умолчанию во время восстановления.
Этот параметр игнорируется при генерировании архивного (не текстового) выходного
файла. Для архивных форматов этот параметр можно указать при вызове qhb_restore.
--no-toast-compression
Не формировать команды, задающие методы сжатия TOAST. При указании этого параметра
все столбцы будут восстановлены с методом сжатия, выбранным по умолчанию.
--no-unlogged-table-data
Не выгружать содержимое нежурналируемых таблиц и последовательностей. Этот параметр
не влияет на выгрузку определений (схем) таблиц и последовательностей; он лишь
подавляет выгрузку их данных. При выгрузке с резервного сервера содержимое
нежурналируемых таблиц и последовательностей всегда исключается.
--on-conflict-do-nothing
Добавить предложения ON CONFLICT DO NOTHING в команды INSERT. Этот параметр
недопустим, если также не указаны параметры --inserts, --column-insert
или --rows-per-insert.
--quote-all-identifiers
Принудительно заключать в кавычки все идентификаторы. Этот параметр рекомендуется
при выгрузке базы данных с сервера QHB, основная версия которого
отличается от версии qhb_dump, или когда дамп предназначен для загрузки
на сервер с другой основной версией. По умолчанию qhb_dump заключает в
кавычки только те идентификаторы, которые являются зарезервированными словами в
ее собственной основной версии. Иногда это приводит к проблемам совместимости при
работе с серверами других версий, в которых наборы зарезервированных слов могут
немного отличаться. Использование параметра --quote-all-identifiers
предотвращает подобные проблемы ценой ухудшения читаемости скрипта с дампом.
--rows-per-insert=число_строк
Выгружать данные в виде команд INSERT (вместо COPY). Этот параметр задает
максимальное число строк в одной команде INSERT. Указанное значение должно быть
больше нуля. Любая ошибка во время восстановления приведет к потере только тех
строк INSERT, в которых возникли ошибки, а не всего содержимого таблицы.
--section=имя_раздела
Выгрузить только заданный раздел. Именем раздела может быть pre-data, data
или post-data. Для выбора нескольких разделов этот параметр можно указать более
одного раза. По умолчанию выгружаются все разделы.
Раздел data содержит фактические данные таблиц, содержимое больших объектов и
значения последовательности. Раздел post-data содержит определения индексов,
триггеров, правил и ограничений (кроме ограничений проверки, созданных без
NOT VALID). Раздел pre-data содержит все остальные элементы определений
данных.
--serializable-deferrable
Использовать для выгрузки транзакцию с уровнем изоляции serializable для
гарантированного получения снимка, согласованного с последующими состояниями базы
данных. Однако для этого нужно дождаться момента, когда в потоке транзакций не
может быть никаких аномалий, и поэтому нет риска сбоя выгрузки или отката других
транзакций с ошибкой serialization_failure. Более подробную информацию об
изоляции транзакций и управлении параллельным доступом см. в главе
Управление параллельным доступом.
Этот параметр не несет практической пользы для дампа, предназначенного только для
восстановления после сбоя. Он может быть полезен для дампа, используемого для
загрузки копии базы данных, в которой формируются отчеты и выполняются другие
операции чтения, в то время как в исходной базе продолжается обычная работа. Без
этого параметра дамп может отражать состояние, не согласующееся ни с каким
последовательным выполнением фиксируемых в итоге транзакций. Например, если
используются методы пакетной обработки, статус пакета может отображаться как
завершенный, хотя на самом деле в дампе будут находиться не все элементы пакета.
Этот параметр не повлияет на результат, если при запуске qhb_dump нет
активных транзакций чтения/записи. Если же такие транзакции есть, то начало
выгрузки может быть отложено на неопределенный срок. После запуска выгрузки
производительность с этим ключом или без него будет одинаковой.
--snapshot=имя_снимка
Использовать заданный синхронизированный снимок при создании дампа базы данных
(подробную информацию см. в таблице Функции синхронизации снимков).
Этот параметр полезен, когда необходимо синхронизировать дамп со слотом
логической репликации (см. главу Логическое декодирование) или с другим
одновременным сеансом.
В случае многопоточной выгрузки вместо создания нового снимка будет использовано
имя снимка, определенное этим параметром.
--strict-names
Требовать, чтобы каждому квалификатору расширения (-e/--extension), схемы
(-n/--schema) и таблицы (-t/--table) соответствовал как минимум
один объект расширение/схема/таблица в выгружаемой базе данных. Обратите внимание,
что если ни для одного из этих квалификаторов не найдется соответствующего объекта,
qhb_dump выдаст ошибку даже без --strict-names.
Этот параметр не действует на ключи -N/--exclude-schema, -T/
--exclude-table и --exclude-table-data. Если не находятся объекты,
соответствующие шаблонам исключения, это не считается ошибкой.
--use-set-session-authorization
Выводить команды SET SESSION AUTHORIZATION, соответствующие стандарту SQL,
вместо команд ALTER OWNER, чтобы определить владельца объекта. В итоге дамп будет
более стандартизированным, но, в зависимости от истории объектов в дампе, может
не восстановиться должным образом. Кроме того, при использовании SET SESSION AUTHORIZATION для корректного восстановления из дампа безусловно понадобятся
права суперпользователя, тогда как ALTER OWNER требует меньших привилегий.
-?
--help
Показать справку об аргументах командной строки qhb_dump и завершиться.
Следующие параметры командной строки управляют параметрами подключением к базе данных.
-d имя_бд
--dbname=имя_бд
Задает имя базы данных для подключения. Это равнозначно указанию имени_бд
в качестве первого аргумента, не являющегося ключом, в командной строке. В
имени_бд может задаваться строка подключения. В этом случае параметры в
строке подключения переопределяют любые конфликтующие параметры в командной строке.
-h хост
--host=хост
Задает имя хост-компьютера, на котором работает сервер. Если значение начинается
со слэша, оно используется в качестве каталога для сокета домена Unix. Значение по
умолчанию определяется переменной среды PGHOST, если она установлена. В
противном случае производится попытка подключения к сокету домена Unix.
-p порт
--port=порт
Указывает TCP-порт или расширение файла локального сокета домена Unix, через который
сервер принимает подключения. Значение по умолчанию определяется переменной
среды PGPORT, если она установлена, или значением по умолчанию, заданным при
компиляции.
-U имя_пользователя
--username=имя_пользователя
Имя пользователя, под которым производится подключение.
-w
--no-password
Никогда не запрашивать ввод пароля. Если серверу требуется аутентификация по
паролю, и пароль недоступен с помощью иных средств, таких как файл .pgpass,
попытка подключения завершится неудачно. Этот параметр может быть полезен в
пакетных заданиях и скриптах, где нет пользователя, чтобы ввести пароль.
-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как qhb_dump автоматически запросит
пароль, если сервер требует аутентификацию по паролю. Однако чтобы выяснить это,
qhb_dump потребуется дополнительная попытка подключения к серверу. В
некоторых случаях имеет смысл ввести -W, чтобы исключить эту лишнюю попытку.
--role=имя_роли
Задает имя роли, которая будет использоваться для создания дампа. При указании
этого параметра qhb_dump выполнит команду SET ROLE имя_роли после
подключения к базе данных. Это полезно, когда проходящий проверку пользователь
(заданный ключом -U) не имеет прав, требуемых qhb_dump, но может
переключиться на роль, наделенную этими правами. В некоторых установках имеется
политика, запрещающая подключаться к серверу непосредственно от имени
суперпользователя, и этот параметр позволяет создавать дампы, не нарушая ее.
Переменные среды
PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию.
PG_COLOR
Указывает, использовать ли цвет в диагностических сообщениях. Возможные значения:
always (всегда), auto (автоматически) и never (никогда).
Кроме того, эта утилита, как и большинство других утилит QHB, использует переменные среды, поддерживаемые libpq (см. раздел Переменные среды).
Диагностика
qhb_dump внутренне выполняет команды SELECT. При возникновении проблем с
запуском qhb_dump убедитесь, что в базе данных можно выполнить SELECT,
например, с помощью psql. Кроме того, будут применяться параметры
подключения и переменные среды, которые по умолчанию используются библиотекой
libpq на стороне клиента.
Обычно активность qhb_dump в базе данных собирается системой накопительной
статистики. Если это нежелательно, то можно установить параметр track_counts
в false в переменной среды PGOPTIONS или в команде ALTER USER.
Примечания
Если в базу данных template1 в кластере баз были локально установлены какие-либо дополнительные объекты, необходимо проследить за тем, чтобы вывод qhb_dump выгружался в действительно пустую базу данных; в противном случае есть вероятность возникновения ошибок из-за дублирования определений добавленных объектов. Чтобы создать пустую базу данных без каких-либо локальных дополнений, копируйте ее из шаблона template0, а не template1, например:
CREATE DATABASE foo WITH TEMPLATE template0;
Если выбрано создание дампа только с данными и используется параметр --disable-triggers, qhb_dump генерирует команды для выключения триггеров в пользовательских таблицах перед вставкой данных, а затем — команды, снова включающие их после вставки данных. Если восстановление прерывается в середине процесса, системные каталоги могут остаться в неправильном состоянии.
Файл дампа, созданный qhb_dump, не содержит статистику, используемую
оптимизатором для принятия решений по планированию запросов. Поэтому после
восстановления из файла дампа имеет смысл выполнить команду ANALYZE для
обеспечения оптимальной производительности; дополнительную информацию см. в
подразделах Обновление статистики планировщика и Процесс «Автовакуум».
Поскольку qhb_dump используется для переноса данных в более новые версии QHB, предполагается, что вывод qhb_dump загрузится на сервер QHB более новой версии, чем ее собственная. Также qhb_dump может создавать дампы серверов QHB более старых версий, чем ее собственная. Однако qhb_dump не может создавать дампы серверов QHB более новых основных версий, чем ее собственная; она не станет даже пытаться это делать, во избежание риска некорректной выгрузки. Кроме того, не гарантируется, что вывод qhb_dump может быть загружен на сервер более старой основной версии, даже если дамп был взят с сервера той же версии. Загрузка такого файла может потребовать его редактирования вручную, с удалением синтаксиса, не воспринимаемого старой версией. В случаях разных версий рекомендуется использовать параметр --quote-all-identifiers, поскольку он может предотвратить проблемы, возникающие из-за изменения списков зарезервированных слов в разных версиях QHB.
Выгружая подписки логической репликации, qhb_dump будет генерировать
команды CREATE SUBSCRIPTION которые используют параметр connect = false,
так что при восстановлении подписки не устанавливаются удаленные подключения
для создания слота репликации или для начального копирования таблиц. Таким
образом, дамп может быть восстановлен без сетевого доступа к удаленным серверам.
В задачу пользователя входит последующая повторная активация подписок должным
образом. Если задействованные хосты поменялись, возможно, потребуется изменить
информацию о подключении. Также может быть целесообразно опустошить целевые таблицы
перед началом нового полного копирования таблиц. Если пользователи намереваются
копировать исходные данные во время обновления, им следует создать слот с параметром
two_phase = false. После начальной синхронизации параметр two_phase
будет автоматически включен подписчиком, если подписка изначально была создана с
параметром two_phase = true.
Примеры
Выгрузка базы данных mydb в файл SQL-скрипта:
$ qhb_dump mydb > db.sql
Восстановление из такого скрипта в (только что созданную) базу данных с именем newdb:
$ psql -d newdb -f db.sql
Выгрузка базы данных в архивный файл в специальном формате:
$ qhb_dump -Fc mydb > db.dump
Выгрузка базы данных в архив в формате каталога:
$ qhb_dump -Fd mydb -f dumpdir
Выгрузка базы данных в архив в формате каталога с параллельным выполнением 5 рабочих процессов:
$ qhb_dump -Fd mydb -j 5 -f dumpdir
Восстановление из архивного файла в (только что созданную) базу данных с именем newdb:
$ qhb_restore -d newdb db.dump
Восстановление из архивного файла в ту же базу данных, из которой он был выгружен, с предварительным удалением текущего содержимого этой базы данных:
$ qhb_restore -d qhb --clean --create db.dump
Выгрузка отдельной таблицы с именем mytab:
$ qhb_dump -t mytab mydb > db.sql
Выгрузка всех таблиц, имена которых начинаются с emp и которые принадлежат схеме detroit, кроме таблицы employee_log:
$ qhb_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql
Выгрузка всех схем, имена которых начинаются с east или west, а заканчиваются на gsm, при этом исключая любые схемы, имена которых содержат слово test:
$ qhb_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql
То же самое, но с использованием записи регулярного выражения для объединения ключей:
$ qhb_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql
Выгрузка всех объектов базы данных, кроме таблиц, имена которых начинаются с ts_:
$ qhb_dump -T 'ts_*' mydb > db.sql
Чтобы указать имя в верхнем или смешанном регистре в ключе -t и связанных с ним ключах, нужно заключить это имя в кавычки, иначе оно будет приведено к нижнему регистру (см. Шаблоны). Но кавычки являются спецсимволом для оболочки, поэтому и они, в свою очередь, должны быть заключены в кавычки. Таким образом, чтобы выгрузить одну таблицу с именем в смешанном регистре, нужно написать что-то вроде
$ qhb_dump -t "\"MixedCaseName\"" mydb > mytab.sql