pg_dumpall#

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.

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

Утилиты 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

Параметры#

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

-a
--data-only

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

-c
--clean

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

-E encoding
--encoding=encoding

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

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

-f filename
--file=filename

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

--filter=filename

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

Файл перечисляет шаблон одной базы данных в строке, используя следующий формат: exclude database PATTERN.

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

-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

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

--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

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

--no-publications

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

--no-role-passwords

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

--no-security-labels

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

--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 предотвращает такие проблемы, но ухудшается читаемость скрипта с данными.

--rows-per-insert=nrows

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

--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, сохраняя их исходные свойства (локаль, кодировку). Без этого параметра они сохранят текущие настройки кластера, включая предыдущее содержимое.

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

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

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

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

Примеры#

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

$ pg_dumpall > db.out

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

$ psql -f db.out postgres

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

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

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