pg_dumpall

примечание

Эта страница переведена при помощи нейросети GigaChat.

warning

В подразделе «Совместимость утилит» приведено описание совместимости утилит при использовании различных версий клиентской и серверной частей СУБД Pangolin.

pg_dumpall — извлекает кластер баз данных PostgreSQL в файл сценария.

Синтаксис

pg_dumpall [connection-option...] [option...]

Описание

pg_dumpall — утилита для резервного копирования всех баз данных кластера PostgreSQL в файл SQL-скрипта. Этот файл содержит команды SQL, которые используются в psql для восстановления баз данных, формируется путем автоматического вызова pg_dump для каждой базы данных в кластере.

pg_dumpall сохраняет глобальные объекты, общие для всех баз данных:

• роли пользователей;
• табличные пространства;
• привилегии для параметров конфигурации (pg_dump не включает эти объекты).

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

• подключение выполняется от имени суперпользователя для полного экспорта;
• восстановление выполняет суперпользователь, чтобы иметь возможность создавать базы и управлять ролями.

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

pg_dumpall устанавливает соединение с сервером PostgreSQL несколько раз — по одному для каждой базы данных. Если используется парольная аутентификация, система запросит пароль для каждого подключения. Чтобы избежать этого, воспользуйтесь файлом ~/.pgpass.

Внимание!

Восстановление дампа приводит к выполнению произвольного кода по выбору суперпользователей источника на целевом сервере. Частичные дампы и частичное восстановление этого не ограничивают. Если суперпользователи источника не заслуживают доверия, перед восстановлением необходимо проверить выгруженные SQL-запросы. Обратите внимание, что клиент, выполняющий дамп и восстановление, не обязан доверять суперпользователям источника или назначения.

Совместимость утилит

Утилиты pg_dump и pg_dumpall имеют обратную совместимость и позволяют снять логическую копию с соответствующей мажорной версии СУБД, так и с предыдущих мажорных версий СУБД, в пределах жизненного цикла как СУБД, так и операционной системы.

В случае, если мажорная версия утилиты меньше мажорной версии СУБД будет получена ошибка следующего вида:

pg_dump: error: server version: 15.5; pg_dump version: 13.8
pg_dump: error: aborting because of server version mismatch

warning

Восстановление дампа приводит к выполнению произвольного кода по выбору суперпользователей источника на целевом сервере. Частичные дампы и частичное восстановление этого не ограничивают. Если суперпользователи источника не заслуживают доверия, необходимо проверить SQL-запросы, полученные при восстановлении. Обратите внимание, что клиент, выполняющий дамп и восстановление, не обязан доверять суперпользователям источника или назначения.

Параметры

Для утилиты pg_dumpall существуют следующие параметры командной строки:

-a
--data-only

Сохраняет только данные, исключая схему (определения данных) или статистику.

-c
--clean

Формирует команды удаления DROP всех выгружаемых объектов базы данных, ролей и табличных пространств перед командами их создания. Параметр полезен при восстановлении существующего кластера для перезаписи данных. Если не указан параметр --if-exists, то при удалении несуществующих объектов будет возникать ошибка, которую можно игнорировать.

-E encoding
--encoding=encoding

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

Другой способ задать кодировку — установить переменную окружения PGCLIENTENCODING для требуемой кодировки выгрузки.

-f filename
--file=filename

Отправляет вывод в указанный файл. Если параметр не указан, используется стандартный вывод.

--filter=filename

Завершение вывода в указанный файл. Если этот параметр опущен, используется стандартный вывод.

-g
--globals-only

Сохраняет только глобальные объекты (роли и табличные пространства), без баз данных.

-O
--no-owner

Отменяет формирование команд, устанавливающих владельца базы данных. По умолчанию утилита pg_dumpall генерирует команды ALTER OWNER или SET SESSION AUTHORIZATION для назначения владельца объектов БД. Эти команды не будут выполняться при запуске сценария, если он запущен не суперпользователем или владельцем объектов.

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

-r
--roles-only

Сохраняет только роли, без баз данных или табличных пространств.

-s
--schema-only

Сохраняет только определения объектов (схему), не данные.

-S username
--superuser=username

Указывает имя суперпользователя, который будет использоваться для отключения триггеров. Применяется вместе с параметром --disable-triggers.

примечание

Лучше оставьте параметр без изменений и запустите скрипт от имени суперпользователя.

-t
--tablespaces-only

Сохраняет только табличные пространства, без баз данных или ролей.

-v
--verbose

Задает подробный режим. Утилита pg_dumpall выводит подробные комментарии к объектам в стандартный поток ошибок (время начала и окончания выгрузки, сообщения о прогрессе выполнения). Если повторить параметр, то в стандартный поток ошибок будут выдаваться дополнительные отладочные сообщения. Параметр также передается в pg_dump.

-V
--version

Выводит версию pg_dumpall и завершается.

-x
--no-privileges
--no-acl

Отменяет выгрузку прав доступа (команды GRANT/REVOKE).

--binary-upgrade

Параметр для утилит обновления сервера. Использование для других целей не поддерживается Поведение параметра может измениться в будущих выпусках без предварительного уведомления.

--column-inserts
--attribute-inserts

Выгружает данные таблиц с явным указанием столбцов. Команды INSERT будут иметь вид INSERT INTO table (column, ...) VALUES .... Скорость восстановления заметно снижается. Параметр используется для создания выгрузок, которые будут загружены в базы данных, отличные от PostgreSQL.

--disable-dollar-quoting

Запрещает заключать тела функции в знаки доллара $. Тело функции заключается в кавычки, используя стандартный синтаксис SQL.

--disable-triggers

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

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

Команды, генерируемые с параметром --disable-triggers, выполняются суперпользователем (укажите имя суперпользователя в параметре -S или выполнять скрипт от имени суперпользователя).

--exclude-database=pattern

Отменяет выгрузку баз данных, соответствующих шаблону pattern. Параметр можно указать несколько раз для исключения баз данных, соответствующих разным шаблонам.

Шаблон pattern интерпретируется так же, как в командах \d в psql, что позволяет указывать подстановочные символы. При использовании таких символов, убедитесь, что pattern заключен в кавычки, чтобы избежать его обработки оболочкой.

--extra-float-digits=ndigits

Указывает точность для чисел с плавающей точкой. При выгрузке данных в целях резервного копирования параметр не используется.

--filter=filename

Укажите имя файла, из которого будут считываться шаблоны для баз данных, исключенных из дампа. Шаблоны интерпретируются по тем же правилам, что и --exclude-database. Для чтения из STDIN используйте в качестве имени файла. Параметр --filter можно указывать совместно с --exclude-database для исключения баз данных, а также можно указывать несколько раз для нескольких файлов фильтров.

В файле в каждой строке указан один шаблон базы данных в следующем формате:

exclude database PATTERN

Строки, начинающиеся с #, считаются комментариями и игнорируются. Комментарии также могут быть размещены после строки с шаблоном объекта. Пустые строки также игнорируются. Смотрите раздел «Шаблоны» для получения информации о том, как выполнять экранирование в шаблонах.

--if-exists

Добавляет проверки в команды удаления, не действует без указания --clean. Утилита pg_dumpall использует команды DROP ... IF EXISTS для удаления объектов в режиме --clean. При использовании параметра возможные ошибки does not exist не выводятся.

--inserts

Выгружает данные в виде команд INSERT вместо COPY.Скорость восстановления заметно снижается. Параметр используется для создания выгрузок, которые будут загружены в базы данных, отличные от PostgreSQL. Восстановление может завершиться неудачно, если у таблицы изменен порядок столбцов (используйте параметр --column-inserts, чтобы избежать этого).

--load-via-partition-root

Формирует команды COPY или INSERT, ссылающихся на корневую таблицу в иерархии партиционирования.

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

--lock-wait-timeout=timeout

Указывает время ожидания получения разделяемых блокировок. Параметр позволяет не ждать бесконечно получения разделяемых блокировок таблиц в начале выгрузки (выдается ошибка, если не удастся заблокировать таблицы за timeout). Это время можно указать в любом из форматов, принимаемых SET statement_timeout. (Допустимые форматы зависят от версии сервера, с которого выполняется выгрузка, но целое число миллисекунд принимается всеми версиями).

--no-comments

Не выгружать команды COMMENT.

--no-data

Не выгружать данные.

--no-policies

Не выгружать политики безопасности строк.

--no-publications

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

--no-role-passwords

Не выгружать пароли для ролей. После восстановления пароли будут пустыми, и аутентификация по паролю окажется невозможной, пока пароль не будет задан. Так как при указании параметра значения паролей не требуются, информация о ролях берется из представления каталога pg_roles, а не из pg_authid. Это позволяет обойти ограничения, накладываемые политиками безопасности на доступ к pg_authid.

--no-schema

Не выгружать схему (определения данных).

--no-security-labels

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

--no-statistics

Не выгружать статистику. Это значение по умолчанию.

--no-subscriptions

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

--no-sync

Завершает процесс pg_dumpall без ожидания записи файлов на диск. По умолчанию утилита ждет, пока все файлы будут надежно записаны на диск. С данным параметром pg_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-inserts.

--quote-all-identifiers

Принудительно заключает все идентификаторы в кавычки.

подсказка

Используйте при выгрузке базы данных с сервера, основная версия PostgreSQL которого отличается от версии pg_dumpall, или когда копия предназначена для загрузки на сервер другой основной версии.

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

--restrict-key=restrict_key

Указывает использовать предоставленную строку в качестве ключа \restrict psql в выходных данных дампа. Если ключ ограничения не указан, pg_dumpall сгенерирует случайный ключ по мере необходимости. Ключи могут содержать только буквенно-цифровые символы.

Эта опция в основном предназначена для целей тестирования и других сценариев, требующих воспроизводимых результатов (например, сравнение файлов дампа). Она не рекомендуется для общего использования, поскольку вредоносный сервер, заранее знающий ключ, может внедрить произвольный код, который будет выполнен на машине, где запущен psql, с выходными данными дампа.

--rows-per-insert=nrows

Указывает максимальное количеством строк в команде INSERT (сохраняет данные в виде команд INSERT, а не COPY). Значение должно быть больше 0. В случае ошибок будут утеряны только строки INSERT, в которых возникли ошибки, а не все содержимое таблицы.

--statistics

Вывести статистику оптимизатора.

--statistics-only

Вывести только статистику, без схемы (определений данных) или данных. Выводится статистика оптимизатора для таблиц, материализованных представлений, внешних таблиц и индексов.

--sequence-data

Включить данные последовательности в вывод. Это поведение по умолчанию, за исключением случаев, когда указаны --no-data, --schema-only или --statistics-only.

--use-set-session-authorization

Формирует команды SET SESSION AUTHORIZATION вместо команд ALTER OWNER для назначения владельцев объектов.

Такой подход делает выгрузку более стандартизированной, но может привести к некорректному восстановлению, если изменялась история владения объектами.

-?
--help

Показывает справку о параметрах командной строки утилиты pg_dumpall и завершается.

-d connstr
--dbname=connstr

Задает параметры подключения к серверу в виде строки подключения. Они переопределят любые конфликтующие параметры командной строки.

Этот параметр называется --dbname для совместимости с другими клиентскими приложениями, но поскольку pg_dumpall подключается к нескольким базам данных, имя базы данных в строке подключения будет проигнорировано. Используйте параметр -l для явного указания базы данных, используемой при первом подключении (чтобы экспортировать глобальные объекты и определить список баз для выгрузки).

-h host
--host=host

Указывает хост компьютера, на котором запущен сервер. Значение по умолчанию берется из переменной окружения PGHOST. Если она не установлена, выполняется подключение к Unix-сокету (каталог Unix-сокета начинается с косой черты).

-l dbname
--database=dbname

Определяет имя базы данных, к которой устанавливается подключение для выгрузки глобальных объектов и получения списка остальных баз данных. Если параметр не указан, используется база данных postgres, при ее отсутствии — template1.

-p port
--port=port

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

-U username
--username=username

Указывает имя пользователя для подключения.

-w
--no-password

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

-W
--password

Запрашивает пароль перед подключением к основному серверу.

Параметр не является обязательным, поскольку pg_dumpall автоматически запросит пароль, если сервер требует аутентификацию паролем. Однако утилита потратит попытку подключения, чтобы выяснить, что сервер хочет пароль. В некоторых случаях стоит ввести -W, чтобы избежать дополнительной попытки подключения.

Внимание!

Запрос пароля будет повторяться для каждой базы данных, которую необходимо выгрузить. Настройте файл ~/.pgpass, чтобы избежать ошибок при ручном вводе пароля.

--role=rolename

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

Переменные окружения

Утилита поддерживает переменные окружения:

• PGDATABASE
• PGHOST
• PGOPTIONS
• PGPORT
• PGUSER
• PG_COLOR

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

Утилита pg_dump использует переменные окружения, поддерживаемые libpq.

Примечания

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

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

Если указан параметр --statistics, pg_dumpall включит в результирующий файл дампа большую часть статистики оптимизатора. Это не включает всю статистику, например, созданную явно с помощью CREATE STATISTICS, пользовательскую статистику, добавленную расширением, или статистику, собранную системой кумулятивной статистики. Поэтому может быть полезно запустить ANALYZE для каждой базы данных после восстановления из файла дампа, чтобы обеспечить оптимальную производительность. Также можно запустить vacuumdb -a -z для анализа всех баз данных.

Не следует ожидать полного выполнения дамп-файла без ошибок. Например, если в исходном кластере существовала роль, то команда CREATE ROLE вызовет ошибку role already exists, если только в целевом кластере не было изменено имя суперпользователя. Эта ошибка может быть проигнорирована.

Использование --clean может привести к появлению дополнительных сообщений об ошибках, связанных с удалением несуществующих объектов. Минимизируйте эти сообщения, добавив параметр --if-exists.

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

Как правило, рекомендуется использовать опцию -X (--no-psqlrc) при восстановлении базы данных из скрипта pg_dumpall, чтобы обеспечить чистый процесс восстановления и предотвратить потенциальные конфликты с нестандартными конфигурациями psql. Кроме того, поскольку скрипт pg_dumpall может включать метакоманды psql, он может быть несовместим с клиентами, отличными от psql.

Примеры

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

$ pg_dumpall > db.out

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

$ psql -X -f db.out -d postgres

Не важно, к какой базе данных подключаться, так как файл скрипта, созданный pg_dumpall, будет содержать соответствующие команды для создания и подключения к сохраненным базам данных. Исключение составляет случай, если указан параметр --clean. В этом случае подключитесь к базе данных postgres изначально, так как сценарий попытается удалить другие базы данных сразу, и это не удастся для базы данных, к которой уже подключены.

Смотрите также

Проверьте pg_dump для получения информации о возможных условиях ошибки.