pg_dump

примечание

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

Предупреждение!

Изменено поведение оригинальной утилиты. Изменения описаны в рамках подраздела «Доработки Pangolin».

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

Синтаксис

pg_dump [connection-option...] [option...] [dbname]

Описание

pg_dump — утилита для резервного копирования базы данных PostgreSQL. Она создает согласованные резервные копии даже при параллельном использовании базы данных. При этом работа других пользователей (чтение и запись данных) не блокируется.

Утилита pg_dump создает резервную копию только одной базы данных. Чтобы создать резервную копию всего кластера или глобальных объектов, которые относятся ко всем базам данных в кластере (например, роли и табличные пространства), используйте pg_dumpall.

Результаты резервного копирования могут быть представлены в формате SQL-скриптов или архивных файлов. SQL-скрипт — это текстовые файлы, содержащие команды SQL для восстановления базы данных до состояния на момент создания копии. Они воспроизводятся с помощью psql, в том числе на других машинах и архитектурах. С некоторыми изменениями они могут быть адаптированы даже для других СУБД.

Для восстановления данных из архивных форматов файлов используется утилита pg_restore. Форматы архивных файлов позволяют pg_restore выбирать элементы для восстановления и изменения их порядка. Они предназначены для переноса между архитектурами.

Использование архивных форматов файлов совместно с pg_restore и pg_dump предоставляет гибкий механизм архивирования и передачи. Сначала база данных архивируется с помощью pg_dump, а затем pg_restore позволяет анализировать архив и восстанавливать только необходимые части. Наиболее гибкие выходные форматы файлов — это форматы custom (-Fc ) и directory (-Fd ). Они позволяют выбирать и изменять порядок всех объектов, поддерживают параллельное восстановление и сжимаются по умолчанию. Только формат directory поддерживает параллельное создание выгрузки.

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

Доработки Pangolin

Изменено поведение утилиты при использовании параметра -c/--clean:

• Команды DROP, для удаления существующих объектов базы данных, не генерируются при формировании защищенного дампа.
• Если указаны оба ключа -c и -С одновременно, команда DROP DATABASE также не будет сформирована. Восстановление дампа необходимо выполнять в другую предварительно созданную БД из шаблона template0 с установленным расширением secret_dump.

Важно

В текущей версии операции постановки под защиту для схемы public и ее объектов не выгружаются.

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

Утилиты 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_dump существуют следующие параметры командной строки:

dbname

Задает имя базы данных, которую необходимо выгрузить. Если параметр не указан, используется переменная окружения PGDATABASE. Если она не установлена, применяется имя пользователя, указанное для подключения.

-a
--data-only

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

Параметр похожа на --section = data, но не идентичен ему.

-b
--large-objects
--blobs (устаревший параметр)

Включает большие объекты в выгрузку. Это поведение по умолчанию, за исключением случаев, когда указаны

-B
--no-large-objects
--no-blobs (устаревший параметр)

Исключает большие объекты из выгрузки.

Когда указаны оба параметра -b и -B, большие объекты выводятся. Подробнее об этом в описании -b.

-c
--clean

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

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

-C
--create

Добавляет команду для создания базы данных и автоматического подключения к ней. Таким образом перед запуском скрипта неважно, к какой базе данных подключен клиент. Если указан также --clean, скрипт сначала удаляет, а затем создает целевую базу данных перед подключением к ней.

При использовании --create в выгрузку включаются комментарии к базе данных (если они есть), а также настройки конфигурации, применимые к данной базе. Это включает команды ALTER DATABASE ... SET ... и ALTER ROLE ... IN DATABASE ... SET ..., относящиеся к этой базе данных. Также сбрасываются права доступа, если не указан параметр --no-acl.

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

-e pattern
--extension=pattern

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

Любые конфигурационные данные, зарегистрированные через pg_extension_config_dump, включаются в выгрузку, если соответствующее расширение указано в параметре --extension.

Примечание

Когда -e указан, pg_dump не выгружает другие объекты базы данных, от которых могут зависеть выбранные расширения. Это означает, что восстановление выгрузки расширения в чистой базе данных не гарантирует его работоспособность.

-E encoding
--encoding = encoding

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

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

-f file
--file=file

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

-F format
--format=format

Выбирает формат вывода. format может принимать следующие значения:

p
plain : Обычный текстовый файл SQL-скрипта (по умолчанию).

c
custom : Архивный формат, пригодный для использования утилитой pg_restore. Формат позволяет вручную выбирать и сортировать восстанавливаемые объекты, сжат по умолчанию.

d
directory : Архив в формате каталога, подходящий для ввода в pg_restore. В созданном каталоге для каждой таблицы и большого объекта создается отдельный файл, также создается файл оглавления в машинно-читаемом формате. С полученной резервной копией можно работать средствами Unix (например, файлы в несжатом архиве могут быть сжаты с помощью инструмента gzip, lz4 или zstd). Формат сжат по умолчанию с использованием gzip и также поддерживает многопоточный режим.

t
tar : Архив в формате tar для дальнейшего использования утилитой pg_restore. Формат tar совместим с форматом каталога: извлечение архива в формате tar создает допустимый архив в формате каталога. Формат tar не поддерживает сжатие. При его использовании нельзя изменить относительный порядок элементов данных во время восстановления.

-j njobs
--jobs=njobs

Запускает выгрузку параллельно, одновременно сбрасывает в количестве njobs таблиц. Этот параметр сокращает время, необходимое для выполнения выгрузки, но увеличивает нагрузку на сервер. Параметр используется только с форматом directory, так как в нем несколько процессов могут записывать данные одновременно.

примечание

Убедитесь, что параметр max_connections имеет достаточно высокое значение, чтобы вместить все соединения, так как утилита pg_dump откроет njobs + 1 соединений с базой данных.

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

Для выполнения параллельной выгрузки сервер базы данных должен поддерживать синхронизированные снимки, функцию, которая была представлена в PostgreSQL версии 9.2 для основных серверов и версии 10 для резервных копий. Это гарантирует, что все соединения видят одинаковые данные, что предотвращает создание несогласованных резервных копий. pg_dump -j использует множественные подключения. Первое подключение осуществляется головным процессом, а последующие — рабочими процессами (для гарантии, что каждое подключение увидит одни и те же данные).

-n pattern
--schema=pattern

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

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

Примечание

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

Объекты без схемы, например, большие бинарные объекты, не сбрасываются при указании параметра -n. Можно добавить их обратно в выгрузку с помощью параметра ---large-objects.

-N pattern
--exclude-schema=pattern

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

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

-O
--no-owner

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

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

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

-R
--no-reconnect

Параметр устарел, но принимается для обеспечения обратной совместимости.

-s
--schema-only

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

Параметр противоположен параметру --data-only. Он похож на указание --section=pre-data --section=post-data, но не идентичен ему.

Не путайте этот параметр с --schema, где слово «схема» в другом значении.

Чтобы не выгрузить данные отдельных таблиц, используйте параметр --exclude-table-data.

-S username
--superuser=username

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

примечание

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

-t pattern
--table=pattern

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

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

При использовании -t параметры -n и -N игнорируются, потому что таблицы, выбранные с помощью -t, будут выгружены независимо от них, а не табличные объекты не будут выгружаться.

Примечание

При использовании параметра -t утилита pg_dump не выгружает прочие объекты, от которых выгружаемые таблицы могут зависеть (не гарантируется, что выгруженные таблицы будут успешно восстановлены).

-T pattern
--exclude-table=pattern

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

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

-v
--verbose

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

-V
--version

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

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

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

-Z level
-Z method[:detail]
--compress=level
--compress=method[:detail]

Задайте метод сжатия и/или уровень сжатия для использования. Метод сжатия может быть установлен в значение gzip, lz4, zstd или none для отсутствия сжатия. Можно дополнительно указать строку детализации сжатия. Если строка детализации представляет собой целое число, оно задает уровень сжатия. В противном случае она должна представлять собой список элементов, разделенных запятыми, каждый из формы keyword или keyword=value. На данный момент поддерживаются ключевые слова level и long.

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

Для форматов архивов custom и directory это указывает на сжатие отдельных сегментов данных таблиц, причем по умолчанию используется сжатие методом gzip со средним уровнем. Для обычного текстового вывода установка ненулевого уровня сжатия приводит к сжатию всего выходного файла так, будто он был пропущен через gzip, lz4 или zstd, однако по умолчанию сжатие не применяется. С использованием zstd-сжатия режим long может улучшить коэффициент сжатия, но ценой увеличения объема используемой памяти.

Формат архива tar пока не поддерживает сжатие вообще.

--binary-upgrade

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

--column-inserts
--attribute-inserts

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

--disable-dollar-quoting

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

--disable-triggers

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

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

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

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

--enable-row-security

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

По умолчанию pg_dump устанавливает для row_security значение off, чтобы убедиться, что все данные выгружены из таблицы. Если у пользователя нет достаточных прав для обхода защиты строк, то выдается ошибка. С --enable-row-security утилита pg_dump включает параметр row_security, что позволяет пользователю выгружать части содержимого таблицы, к которым он имеет доступ.

Внимание!

В настоящий момент необходимо, чтобы данные были выгружены в формате INSERT (COPY FROM не поддерживает защиту строк).

--exclude-extension=pattern Не выполнять выгрузку никаких расширений, соответствующих шаблону pattern. Шаблон интерпретируется согласно тем же правилам, что и для параметра -e. Переключатель --exclude-extension может быть указан более одного раза, чтобы исключить расширения, соответствующие любому из нескольких шаблонов.

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

--exclude-table-and-children=pattern Это аналогично опции -T/--exclude-table, за исключением того, что она также исключает любые разделенные или дочерние таблицы наследования таблиц, соответствующих шаблону pattern.

--exclude-table-data=pattern

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

Используйте --schema-only, чтобы исключить содержимое всех таблиц базы данных.

--exclude-table-data-and-children=pattern

Аналогична опции --exclude-table-data, за исключением того, что она также исключает данные любых разделенных или дочерних таблиц наследования таблиц, соответствующих шаблону pattern.

--extra-float-digits=ndigits

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

--filter=filename Укажите имя файла, из которого нужно прочитать шаблоны для включения или исключения объектов из выгрузки. Шаблоны интерпретируются согласно тем же правилам, что и соответствующие параметры: -t/--table, --table-and-children, -T/--exclude-table, и --exclude-table-and-children для таблиц, -n/--schema и -N/--exclude-schema для схем, --include-foreign-data для данных на удаленных серверах, --exclude-table-data и --exclude-table-data-and-children для данных таблиц и -e/--extension и --exclude-extension для расширений. Чтобы читать из STDIN, используйте - в качестве имени файла. Опцию --filter можно указывать совместно с перечисленными выше параметрами для включения или исключения объектов и также можно указать ее более одного раза для множества файлов фильтров.

Файл перечисляет один шаблон объекта в каждой строке, со следующим форматом:

{ include | exclude } { extension | foreign_data | table | table_and_children | table_data | table_data_and_children | schema } PATTERN

Первое ключевое слово указывает, следует ли включать объекты, соответствующие шаблону, или исключать их. Второе ключевое слово определяет тип объектов для фильтрации по шаблону:

• extension – расширения. Работает аналогично опции -e/--extension или --exclude-extension.
• foreign_data – данные на внешних серверах. Работает аналогично опции --include-foreign-data. Это ключевое слово может использоваться только совместно с ключевым словом include.
• table – таблицы. Работает аналогично опциям -t/--table или -T/--exclude-table.
• table_and_children – таблицы включая любые разделы или дочерние таблицы наследования. Работает аналогично опциям --table-and-children или --exclude-table-and-children.
• table_data – табличные данные любых таблиц, соответствующих шаблону pattern. Работает аналогично опции --exclude-table-data. Это ключевое слово можно использовать только совместно с ключевым словом exclude.
• table_data_and_children – табличные данные любых таблиц, соответствующих шаблону pattern, а также любых разделов или дочерних элементов наследования этих таблиц. Работает аналогично опции --exclude-table-data-and-children. Это ключевое слово можно использовать только совместно с ключевым словом exclude.
• schema – схемы. Работает аналогично опциям -n/--schema или -N/--exclude-schema.

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

Примеры файлов приведены ниже в разделе «Примеры».

--if-exists

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

--include-foreign-data=foreign_server

Выгружает данных всех сторонних таблиц со сторонних серверов, соответствующих шаблону foreign_server. Параметр можно указать несколько раз для выгрузки со сторонних серверов, соответствующих разным шаблонам (шаблон не может быть пустым). foreign_server интерпретируется так же, как в командах \d в psql. Поэтому можно выбрать несколько сторонних серверов, используя символы подстановки в шаблоне.

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

Примечание

При использовании параметра утилита pg_dump не проверяет возможность записи в стороннюю таблицу. Поэтому не гарантируется успешное восстановление этой таблицы.

--inserts

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

--load-via-partition-root

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

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

--lock-wait-timeout = timeout

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

--no-comments

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

--no-publications

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

--no-security-labels

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

--no-subscriptions

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

--no-sync

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

--no-table-access-method

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

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

--no-tablespaces

Не формирует команды для выбора табличных пространств. Во время восстановления все объекты будут созданы в стандартном табличном пространстве.

Параметр игнорируется при создании архивного выходного файла. Для таких форматов укажите этот параметр при вызове pg_restore.

--no-toast-compression

Не формирует команды, которые задают методы сжатия TOAST. Все столбцы будут восстановлены с настройками сжатия по умолчанию.

--no-unlogged-table-data

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

примечание

С резервного сервера (реплики) данные в нежурналируемых таблицах и последовательностях не выгружаются.

--on-conflict-do-nothing

Добавляет предложение ON CONFLICT DO NOTHING к INSERT командам. Действителен только при указании параметра --inserts, --column-inserts или --rows-per-insert.

--quote-all-identifiers

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

Совет

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

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

--rows-per-insert = n_rows

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

--section=section_name

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

Имя раздела может принимать значения:

• data содержит данные таблиц, больших объектов и значения последовательностей.
• pre-data содержит определения индексов, триггеров, правил и ограничений, кроме ограничений проверки, кроме проверенных.
• post-data содержит все остальные определения данных.

--serializable-deferrable

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

Внимание!

Дождитесь момента, когда в потоке транзакций отсутствуют аномалии, чтобы избежать сбоев при выгрузке и минимизировать риск отката других транзакций из-за ошибки serialization_failure.

Подробнее о изоляции транзакций и управлении конкуренцией можно ознакомиться в разделе «Управление конкурентным доступом».

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

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

--snapshot=snapshot_name

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

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

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

--strict-names

Требует, чтобы каждый шаблон расширения (-e/--extension), схемы (-n/--schema) и таблицы (-t/--table) соответствовал хотя бы одному расширению/схеме/таблице в базе данных, подлежащей выгрузке. Это также относится к фильтрам, используемым с --filter. Обратите внимание, что если ни один из шаблонов расширения/схемы/таблицы не находит совпадений, pg_dump выдаст ошибку даже без указания --strict-names.

Параметр не влияет на параметры исключения -N/--exclude-schema, -T/--exclude-table или --exclude-table-data. Если объекты, соответствующие шаблонам исключения, отсутствуют, это не считается ошибкой.

--sync-method=method

При установке в fsync, что является значением по умолчанию, pg_dump --format=directory рекурсивно открывает и синхронизирует все файлы в каталоге архива.

На Linux вместо этого можно использовать syncfs, чтобы попросить операционную систему синхронизировать всю файловую систему, содержащую каталог архива. См. информацию о предостережениях, связанных с использованием syncfs, в описании параметра recovery_init_sync_method.

Этот параметр не имеет эффекта, если используется --no-sync или --format не установлен в directory.

--table-and-children=pattern

То же самое, что и опция -t/--table, за исключением того, что она также включает любые дочерние таблицы наследования или партиционирования таблиц, соответствующих выражению pattern.

--use-set-session-authorization

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

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

-?
--help

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

-d dbname
--dbname=dbname

Задает имя базы данных для подключения. Равнозначно указанию dbname как первого параметра без ключа в командной строке. dbname может быть строкой подключения. В этом случае параметры строки подключения имеют приоритет над одноименными параметрами командной строки.

-h host
--host = host

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

-p port
--port = port

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

-U username
--username=username

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

-w
--no-password

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

-W
--password

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

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

--role=role_name

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

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

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

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

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

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

Диагностика

На низком уровне pg_dump выполняет команды SELECT. Если при работе утилиты возникают проблемы, рекомендуется проверить возможность выполнения SELECT, например из psql. Используются все настройки подключения по умолчанию и переменные окружения, применяемые клиентской библиотекой libpq.

По умолчанию действия pg_dump фиксируются в системе накопительной статистики. Чтобы отключить сбор статистики, установите для параметра track_counts значениеfalse через переменную окружения PGOPTIONS или с помощью команды ALTER USER.

Примечания

Если в шаблонной базе template1 создавались дополнительные объекты, убедитесь, что выгрузка загружается в пустую базу. В противном случае возможны ошибки из-за дублирования объектов. Чтобы создать чистую базу, следует использовать template0 вместо template1:

CREATE DATABASE foo WITH TEMPLATE template0;

Если выгружаются только данные с параметром --disable-triggers, pg_dump автоматически отключит триггеры перед вставкой данных и включит их после. Но если восстановление прервется, системные каталоги могут остаться в некорректном состоянии.

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

Совместимость версий

При использовании pg_dump важно учитывать ограничения на перенос данных между разными версиями сервера. Основные правила следующие:

• Выгруженные данные можно загрузить на новую версию сервера.
• pg_dump поддерживает выгрузку данных из старых версий сервера (начиная с PostgreSQL 9.2).
• Утилита не выгружает данные с серверов более новых основных версий.
• Не гарантируется, что выгруженные данные корректно загрузятся в старую версию сервера. В некоторых случаях может потребоваться ручное редактирование файла для исправления несовместимого синтаксиса.

При работе с разными версиями рекомендуется использовать параметр --quote-all-identifiers, чтобы избежать проблем с изменением зарезервированных слов между версиями PostgreSQL.

Выгрузка логических подписок репликаций

При выгрузке подписок pg_dump добавляет параметр connect=false в команды CREATE SUBSCRIPTION для предотвращения автоматического создание слота репликации и начального копирования таблиц при восстановлении, что позволяет выполнить процесс без сетевого доступа к удаленным серверам.

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

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

Примеры

Выгрузка базы данных mydb в файл SQL-скрипта:

$ pg_dump mydb > db.sql

Восстановление из полученного скрипта в чистую базу данных newdb:

$ psql -d newdb -f db.sql

Выгрузка базы данных в специальном формате:

$ pg_dump -Fc mydb > db.dump

Выгрузка базы данных в формате directory:

$ pg_dump -Fd mydb -f dumpdir

Выгрузка базы данных в формате directory с 5 параллельными потоками:

$ pg_dump -Fd mydb -j 5 -f dumpdir

Восстановление из архива в новую базу данных newdb:

$ pg_restore -d newdb db.dump

Восстановление архива в ту же базу данных с предварительным удалением текущего содержимого:

$ pg_restore -d postgres --clean --create db.dump

Выгрузка отдельной таблицы mytab:

$ pg_dump -t mytab mydb > db.sql

Выгрузка всех таблиц, чьи имена начинаются с emp и принадлежат схеме detroit, за исключением таблицы employee_log:

$ pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql

Выгрузка всех схем, имена которых начинаются с east или west, заканчиваются на gsm и не содержат test:

$ pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql

Тот же пример, но с использованием регулярных выражений:

$ pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql

Выгрузка всех объектов базы данных, кроме таблиц, имена которых начинаются с ts_:

$ pg_dump -T 'ts_*' mydb > db.sql

Выгрузка таблицы с именем в смешанном регистре: Для указания имени в верхнем или смешанном регистре в ключе -t, его нужно заключить в кавычки. Так как кавычки являются спецсимволом для оболочки, их также необходимо заключать в дополнительные кавычки:

$ pg_dump -t "\"MixedCaseName\"" mydb > mytab.sql

Для выгрузки всех таблиц, чьи имена начинаются с mytable, за исключением таблицы mytable2, укажите файл фильтра filter.txt следующим образом:

include table mytable*
exclude table mytable2
$ pg_dump --filter=filter.txt mydb > db.sql

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

pg_dumpall, pg_restore, psql