pg_dumpall
pg_dumpall — выгрузить кластер баз данных Postgres Pro в файл скрипта
Синтаксис
pg_dumpall
[параметр-подключения
...] [параметр
...]
Описание
Утилита pg_dumpall предназначена для записи («выгрузки») всех баз данных кластера Postgres Pro в один файл в формате скрипта. Этот файл содержит команды SQL, так что передав его на вход psql, можно восстановить все базы данных. Для формирования этого файла вызывается pg_dump для каждой базы данных в кластере. pg_dumpall также выгружает глобальные объекты, общие для всех баз данных, то есть роли и табличные пространства. (Программа pg_dump не сохраняет эти объекты.)
Так как утилита pg_dumpall читает таблицы из всех баз данных, для получения полного содержимого баз запускать её, как правило, нужно от имени суперпользователя. Также права суперпользователя требуются при последующем выполнении сохранённого скрипта, чтобы он смог добавить роли и создать базы данных.
Генерируемый SQL-скрипт записывается в стандартное устройство вывода. Чтобы перенаправить его в файл, воспользуйтесь параметром -f
/--file
или операторами оболочки.
Утилите pg_dumpall требуется подключаться к серверу Postgres Pro несколько раз (к каждой базе по отдельности). Если вы проходите проверку подлинности по паролю, вам придётся каждый раз вводить пароль. Чтобы избежать этого, удобно иметь файл ~/.pgpass
. За дополнительными сведениями обратитесь к Разделу 34.15.
Параметры
Параметры командной строки для управления содержимым и форматом вывода.
-a
--data-only
Выгружать только данные, без схемы (определений данных).
-c
--clean
Выводить SQL-команды для
DROP
всех выгруженных баз данных, ролей и табличных пространств перед их воссозданием. Этот параметр полезен, когда при восстановлении необходимо перезаписать существующий кластер. Без дополнительного указания--if-exists
при этом могут выдаваться безвредные сообщения об ошибках, если таких объектов не окажется в целевой базе данных.-E
кодировка
--encoding=
кодировка
Создать копию в заданной кодировке. По умолчанию копия создаётся в кодировке базы данных. (Другой способ достичь того же результата — задать желаемую кодировку в переменной окружения
PGCLIENTENCODING
.)-f
имя_файла
--file=
имя_файла
Направить вывод в указанный файл. Если этот параметр опущен, скрипт записывается в стандартный вывод.
-g
--globals-only
Выгружать только глобальные объекты (роли и табличные пространства), без баз данных.
-O
--no-owner
Не генерировать команды, устанавливающие владение объектами, как в исходной базе данных. По умолчанию, pg_dumpall генерирует команды
ALTER OWNER
илиSET SESSION AUTHORIZATION
, восстанавливающие исходных владельцев для создаваемых элементов схемы. Однако выполнить эти команды сможет только суперпользователь (или пользователь, владеющий всеми объектами, создаваемыми скриптом). Чтобы получить скрипт, который сможет восстановить любой пользователь (но при этом он станет владельцем всех объектов), используется-O
.-r
--roles-only
Выгружать только роли, без баз данных и табличных пространств.
-s
--schema-only
Выгружать только определения объектов (схемы), без данных.
-S
имя_пользователя
--superuser=
имя_пользователя
Указать суперпользователя, который будет использоваться для отключения триггеров. Параметр имеет значение только вместе с
--disable-triggers
. Обычно его лучше не использовать, а запускать полученный скрипт от имени суперпользователя.-t
--tablespaces-only
Выгружать только табличные пространства, без баз данных и ролей.
-v
--verbose
Включить режим подробных сообщений. В этом режиме pg_dumpall записывает в выходной файл время начала/завершения выгрузки, а в стандартный канал ошибок — сообщения о процессе. При этом подробные сообщения будет также выводить pg_dump.
-V
--version
Сообщить версию pg_dumpall и завершиться.
-x
--no-privileges
--no-acl
Не выгружать права доступа (команды GRANT/REVOKE).
--add-collprovider
Если провайдер правил сортировки для выгружаемой базы данных задаётся неявно, этот параметр добавляет явное указание провайдера в выгрузку. Этот вариант рекомендуется, если вы используете pg_dumpall и pg_restore для обновления с предыдущих версий Postgres Pro или любой версии PostgreSQL. Это позволяет сохранить изначальный провайдер основного правила сортировки для переносимой базы данных, если в базе
template0
в новом кластере используются другие параметры правил сортировки. В противном случае ограничения-проверки, которые используют основное правило сортировки в базе данных, могут поменять поведение, и командаCOPY
завершится ошибкой. При обновлении в двоичном формате провайдер сохраняется автоматически.--binary-upgrade
Этот параметр предназначен для утилит обновления сервера. Использование для иных целей не рекомендуется и не поддерживается. Поведение параметра может быть изменено в последующих версиях без предварительного уведомления.
--column-inserts
--attribute-inserts
Выгружать данные в виде команд
INSERT
с явно задаваемыми именами столбцов (INSERT INTO
). При этом восстановление будет очень медленным; в основном это применяется для выгрузки данных, которые затем будут загружаться не в Postgres Pro.таблица
(столбец
, ...) VALUES ...--disable-dollar-quoting
Этот параметр запрещает заключать в доллары тело функций, что оставляет возможность только заключать их в кавычки, применяя стандартный синтаксис SQL.
--disable-triggers
Этот параметр действует только при выгрузке одних данных. С ним pg_dumpall добавляет команды, отключающие триггеры в целевых таблицах на время загрузки данных. Используйте его, если в ваших таблицах определены проверки ссылочной целостности или другие триггеры, которые вы не хотели бы выполнять в процессе загрузки данных.
В настоящее время команды, генерируемые с параметром
--disable-triggers
, должны исполняться от имени суперпользователя. Таким образом, необходимо также передавать флаг-S
, либо при восстановлении выполнять скрипт от имени суперпользователя.--extra-float-digits=
число_цифр
Выводить числа с плавающей точкой не с максимальной точностью, а с заданным значением extra_float_digits. При выгрузке данных в целях резервного копирования данный параметр использовать не следует.
--exclude-database=
шаблон
Не выгружать базы данных, имена которых соответствуют
шаблону
. Исключить имена по нескольким шаблонам можно, добавив несколько ключей--exclude-database
. Параметршаблон
в данном аргументе обрабатывается по тем же правилам, что и в командах psql\d
(см. Шаблоны поиска), что позволяет также исключить несколько баз данных, добавив в шаблон звёздочку. Используя звёздочку, заключайте шаблон в кавычки, если звёздочка может быть развёрнута оболочкой.--if-exists
Используйте команды
DROP ... IF EXISTS
для удаления объектов в режиме--clean
. При этом возможные ошибки «does not exist» (не существует) не выводятся. Этот параметр недействителен без указания--clean
.--inserts
Выгружать данные в виде команд
INSERT
, а неCOPY
. При этом восстановление значительно замедлится; в основном это применяется для выгрузки данных, которые затем будут загружаться не в Postgres Pro. Заметьте, что восстановление может вовсе не выполниться при изменении порядка столбцов в таблицах. В этом смысле параметр--column-inserts
безопаснее, но восстановление будет ещё медленнее.--load-via-partition-root
При выгрузке данных для секции таблицы выводить команды
COPY
илиINSERT
, ссылающиеся на корневую таблицу в иерархии секционирования, а не на эту секцию. В результате при загрузке данных подходящая секция будет выбираться заново для каждой строки. Это может быть полезно при восстановлении данных, когда на целевом сервере строки не всегда попадают в те же секции, в которых они находились на исходном. Это возможно, например, когда столбец разбиения имеет текстовый тип и в двух системах по-разному определено правило сортировки, по которому упорядочивается этот столбец.--lock-wait-timeout=
время_ожидания
Не ждать бесконечно получения разделяемых блокировок таблиц в начале процедуры выгрузки. Вместо этого выдать ошибку, если не удастся заблокировать таблицы за указанное
время_ожидания
. Это время можно задать в любом из форматов, принимаемых командойSET statement_timeout
. Допустимые значения зависят от версии сервера, выгружающего данные, но количество миллисекунд в виде целого числа принимают все версии, начиная с 7.3. Более ранние версии игнорируют этот параметр.--no-comments
Не выгружать комментарии.
--no-publications
Не выгружать публикации.
--no-role-passwords
Не выгружать пароли ролей. При восстановлении все роли получат пароль NULL и не смогут пройти проверку подлинности, пока им не будут назначены пароли. Так как значения паролей не нужны, когда используется это указание, информация о ролях считывается из системного представления
pg_roles
, а не изpg_authid
. Таким образом, данный вариант может быть также полезен, если доступ кpg_authid
ограничен политикой безопасности.--no-security-labels
Не выгружать метки безопасности.
--no-subscriptions
Не выгружать подписки.
--no-sync
По умолчанию
pg_dumpall
ждёт, пока все файлы не будут надёжно записаны на диск. С данным параметромpg_dumpall
завершается немедленно, то есть выполняется быстрее, но в случае неожиданного сбоя операционной системы выгруженные данные могут оказаться испорченными. Вообще этот параметр предназначен прежде всего для тестирования, для производственной среды он не подходит.--no-tablespaces
Не выводить команды, создающие или выбирающие табличные пространства для объектов. С этим параметром все объекты будут созданы в пространстве по умолчанию, установленном во время восстановления.
--no-unlogged-table-data
Не выгружать содержимое нежурналируемых таблиц. Этот параметр не влияет на то, как выгружаются определения этих таблиц (схема); он отключает только выгрузку данных из них.
--on-conflict-do-nothing
Добавить предложения
ON CONFLICT DO NOTHING
в командыINSERT
. Это указание допускается только при выборе режима--inserts
или--column-inserts
.--quote-all-identifiers
Принудительно экранировать все идентификаторы. Этот параметр рекомендуется при выгрузке базы, когда основная версия сервера PostgreSQL, с которого выгружается база, отличается от версии pg_dumpall, или когда выгруженная копия предназначена для загрузки на сервере с другой основной версией. По умолчанию pg_dumpall экранирует только те идентификаторы, которые являются зарезервированными словами в собственной основной версии. Иногда это приводит к проблемам совместимости с серверами других версий, в которых множество зарезервированных слов может быть несколько другим. Применение параметра
--quote-all-identifiers
предотвращает подобные проблемы, ценой ухудшения читаемости скрипта с выгруженными данными.--rows-per-insert=
число_строк
Выгружать данные таблиц в виде команд
INSERT
вместоCOPY
. В данном параметре задаётся максимальное число строк для одной командыINSERT
. Указанное в нём значение должно быть больше 0. При этом в случае каких-либо ошибок при восстановлении данных будут потеряны только строкиINSERT
, где возникли ошибки, но не всё содержимое таблицы.--use-set-session-authorization
Выводить команды
SET SESSION AUTHORIZATION
, соответствующие стандарту, вместоALTER OWNER
, для назначения владельцев объектов. В результате выгруженный скрипт будет более стандартизированным, но может не восстановиться корректно, в зависимости от истории объектов.-?
--help
Показать справку по аргументам командной строки pg_dumpall и завершиться.
Далее описаны параметры управления подключением.
-d
строка_подключения
--dbname=
строка_подключения
Указывает параметры подключения к серверу в формате строки подключения; они будут переопределять любые одноимённые параметры, заданные в командной строке.
Этот параметр называется
--dbname
для согласованности с другими клиентскими приложениями, но так как pg_dumpall подключается не к одной базе данных, имя базы в строке подключения игнорируется. Чтобы указать имя базы данных для начального подключения, которое будет использоваться для выгрузки глобальных объектов и обнаружения других выгружаемых баз, воспользуйтесь параметром-l
.-h
сервер
--host=
сервер
Указывает имя компьютера, на котором работает сервер баз данных. Если значение начинается с косой черты, оно определяет каталог Unix-сокета. Значение по умолчанию берётся из переменной окружения
PGHOST
, если она установлена. В противном случае выполняется подключение к Unix-сокету.-l
имя_бд
--database=
имя_бд
Задаёт имя базы данных, через подключение к которой будут выгружаться глобальные объекты и находиться другие выгружаемые базы. По умолчанию используется база
postgres
, а в случае её отсутствия —template1
.-p
порт
--port=
порт
Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения. Значение по умолчанию определяется переменной окружения
PGPORT
, если она установлена, либо числом, заданным при компиляции.-U
имя_пользователя
--username=
имя_пользователя
Имя пользователя, под которым производится подключение.
-w
--no-password
Не выдавать запрос на ввод пароля. Если сервер требует аутентификацию по паролю и пароль не доступен с помощью других средств, таких как файл
.pgpass
, попытка соединения не удастся. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, который вводит пароль.-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как pg_dumpall запрашивает пароль автоматически, если сервер проверяет подлинность по паролю. Однако чтобы понять это, pg_dumpall лишний раз подключается к серверу. Поэтому иногда имеет смысл ввести
-W
, чтобы исключить эту ненужную попытку подключения.Заметьте, что пароль будет запрашиваться повторно для выгрузки каждой базы данных. Поэтому обычно лучше настроить файл
~/.pgpass
, и не вводить пароль каждый раз вручную.--role=
имя роли
Задаёт имя роли, которая будет осуществлять выгрузку. Получив это имя, pg_dumpall выполнит
SET ROLE
имя_роли
после подключения к базе данных. Это полезно, когда проходящий проверку пользователь (указанный в-U
) не имеет прав, необходимых для pg_dumpall, но может переключиться на роль, наделённую этими правами. В некоторых окружениях правила запрещают подключаться к серверу непосредственно суперпользователю, и этот параметр позволяет выполнить выгрузку, не нарушая их.
Переменные окружения
PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию
PG_COLOR
Выбирает вариант использования цвета в диагностических сообщениях. Возможные значения:
always
(всегда),auto
(автоматически) иnever
(никогда).
Эта утилита, как и большинство других утилит Postgres Pro, также использует переменные среды, поддерживаемые libpq (см. Раздел 34.14).
Примечания
Так как pg_dumpall внутри себя вызывает pg_dump, часть диагностических сообщений будет относиться к pg_dump.
Ключ --clean
может быть полезен, даже если вы намереваетесь восстановить копию из скрипта в новом кластере. С --clean
скрипт сможет удалить и пересоздать встроенные базы данных postgres
и template1
, так что они получат свойства, которые имели одноимённые базы в исходном кластере (например, локаль и кодировку). Без данного ключа эти базы сохранят свои свойства уровня базы данных, а также всё существующее содержимое.
После восстановления имеет смысл запустить ANALYZE
для каждой базы данных, чтобы оптимизатор получил актуальную статистику. Также можно запустить анализ для всех баз данных, выполнив команду vacuumdb -a -z
.
Не следует ожидать, что скрипт выгрузки будет выполняться абсолютно без ошибок. В частности, так как он будет содержать CREATE ROLE
для каждой существующей в исходном кластере роли, при попытке создать суперпользователя определённо произойдёт ошибка «role already exists» (роль уже существует), если только целевой кластер был инициализирован не с другим начальным именем суперпользователя. Эта ошибка некритична и её следует просто игнорировать. С ключом --clean
весьма вероятны другие незначительные сообщения об ошибках, связанные с несуществующими объектами; их число можно минимизировать, добавив ключ --if-exists
.
При использовании pg_dumpall требуется, чтобы все необходимые каталоги табличных пространств существовали до восстановления; в противном случае создание баз данных в нестандартном размещении завершится ошибкой.
Примеры
Выгрузка всех баз данных:
$
pg_dumpall > db.out
Восстановить базы данных из этого файла можно так:
$
psql -f db.out postgres
К какой базе вы подключаетесь, в принципе не имеет значения, так как скрипт, созданный утилитой pg_dumpall, будет содержать все команды, требующиеся для создания сохранённых баз данных и подключения к ним. Однако это важно, если применяется ключ --clean
— тогда вы должны изначально подключиться к базе postgres
; скрипт попытается прежде всего удалить остальные базы данных, но не сможет этого сделать для базы, к которой вы подключены.
См. также
Обратитесь к описанию pg_dump, чтобы узнать об условиях, при которых могут возникнуть проблемы.