pg_dump
pg_dump — выгрузить базу данных Postgres Pro в виде скрипта или в архивном формате
Синтаксис
pg_dump
[параметр-подключения
...] [параметр
...] [имя_бд
]
Описание #
pg_dump — это программа для создания резервных копий базы данных Postgres Pro. Она создаёт целостные копии, даже если база параллельно используется. Программа pg_dump не препятствует доступу других пользователей к базе данных (ни для чтения, ни для записи).
Программа pg_dump выгружает только одну базу данных. Чтобы выгрузить весь кластер или сохранить глобальные объекты, относящиеся ко всем базам в кластере, например, роли и табличные пространства, воспользуйтесь программой pg_dumpall.
Выгружаемые данные могут быть сохранены в виде скрипта, либо в одном из архивных форматов. Скрипты представляют собой текстовые файлы, содержащие SQL-команды, необходимые для воссоздания базы данных до состояния на момент создания скрипта. Для восстановления из скрипта его содержимое можно передать psql. Скрипты можно использовать для восстановления базы на других машинах, в том числе с иной архитектурой, а с некоторыми коррективами даже в других СУБД.
Для восстановления из архивных форматов файлов используется утилита pg_restore. Эти форматы позволяют указывать pg_restore какие объекты базы данных восстановить, а также позволяют изменить порядок следования восстанавливаемых объектов. Архивные форматы файлов спроектированы так, чтобы их можно были переносить на другие платформы с другой архитектурой.
Применение архивных форматов в сочетании утилит pg_restore и pg_dump позволяет организовывать эффективный механизм архивации и переноса данных. pg_dump можно использовать для резервирования всей базы данных, а затем при применении pg_restore выбрать нужные объекты для восстановления. Наиболее гибкие форматы выходных файлов это «custom» (-Fc
) и «directory» (-Fd
). Они позволяют выбрать и изменить порядок объектов, поддерживают восстановление в несколько потоков, а также сжимаются по умолчанию. При этом только формат «directory» поддерживает выгрузку данных в несколько потоков.
Во время работы pg_dump следует обращать внимание на предупреждения, которые печатаются в стандартный поток ошибок, особенно ввиду рассмотренных далее ограничений.
Параметры #
Параметры командной строки для управления содержимым и форматом вывода.
имя_бд
Указывает имя базы данных, из которой будут выгружаться данные. Если имя не задано, то используется значение переменной окружения
PGDATABASE
. Если и переменная не задана, то в качестве имени базы будет взято имя пользователя, под которым осуществляется подключение.-a
--data-only
Выводить только данные, но не схемы объектов (DDL). Будут копироваться данные таблиц, большие объекты, значения последовательностей.
Флаг похож на
--section=data
, но по историческим причинам не равнозначен ему.-b
--large-objects
--blobs
(устаревший параметр)Включить большие объекты в выгрузку. Это поведение по умолчанию при отсутствии ключей
--schema
,--table
или--schema-only
. Таким образом, ключ-b
полезен, лишь когда нужно добавить большие объекты при выгрузке только избранной схемы или таблицы. Заметьте, что большие объекты относятся к данным, и поэтому будут выгружаться, когда используется ключ--data-only
, но не ключ--schema-only
.-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
шаблон
--extension=
шаблон
Выгрузить только расширения, соответствующие
шаблону
. Когда этот параметр отсутствует, выгружаются все несистемные расширения в целевой базе данных. Чтобы выгрузить несколько расширений, ключ-e
можно задать несколько раз. Параметршаблон
интерпретируется по тем же правилам, что и шаблон в командах psql\d
(см. Шаблоны поиска ниже), так что несколько расширений можно выбрать и шаблоном со знаками подстановки. Используя знаки подстановки, при необходимости заключайте шаблон в кавычки, чтобы эти знаки не разворачивала оболочка системы.Для расширения, указанного в
--extension
, в выгрузку включаются все его конфигурационные данные, зарегистрированные функциейpg_extension_config_dump
.Примечание
При использовании
-e
, pg_dump не выгружает прочие объекты, от которых выгружаемые расширения могут зависеть. Таким образом не гарантируется, что выгруженные расширения будут успешно восстановлены в чистой базе данных.-E
кодировка
--encoding=
кодировка
Создать копию в заданной кодировке. По умолчанию копия создаётся в кодировке, используемой базой данных. Другой способ достичь того же результата — задать желаемую кодировку в переменной окружения
PGCLIENTENCODING
. Поддерживаемые кодировки описаны в Подразделе 22.3.1.-f
файл
--file=
файл
Отправить вывод в указанный файл. Параметр можно не указывать, если используется формат с выводом в файл. В этом случае будет использован стандартный вывод. Однако для формата с выводом в каталог параметр является обязательным и должен задавать путь к каталогу. В этом случае целевой каталог будет создан командой
pg_dump
и не должен существовать заранее.-F
format
--format=
format
Указывает формат вывода копии.
format
может принимать следующие значения:p
plain
Сформировать текстовый SQL-скрипт. Это поведение по умолчанию.
c
custom
Выгрузить данные в специальном архивном формате, пригодном для дальнейшего использования утилитой pg_restore. Наряду с форматом
directory
является наиболее гибким форматом, позволяющим вручную выбирать и сортировать восстанавливаемые объекты. Вывод в этом формате по умолчанию сжимается.d
каталог
Выгрузить данные в формате каталога. Этот формат пригоден для дальнейшего использования утилитой pg_restore. При этом будет создан каталог, в котором для каждой таблицы и большого объекта будут созданы отдельные файлы, а также файл оглавления в машинно-читаемом формате, понятном для pg_restore. С полученной резервной копией можно работать штатными средствами Unix, например, несжатую копию можно сжать посредством gzip, lz4 или zstd. Этот формат по умолчанию сжимается с использованием
gzip
, а также поддерживает работу в несколько потоков.t
tar
Выгрузить данные в формате
tar
, для дальнейшего использования с утилитой pg_restore. Этот формат совместим с форматом вывода в каталог: если архив распаковать, получится корректная копия в формате каталога. Однако формат tar не поддерживает сжатие. Также, применяя формат tar, при восстановлении нельзя изменить относительный порядок элементов данных.
-j
число_заданий
--jobs=
число_заданий
Осуществить выгрузку в параллельном режиме, обрабатывая одновременно несколько таблиц (в количестве
число_заданий
). Это может сократить время, необходимое для выгрузки, но увеличивает нагрузку на сервер. Этот параметр можно использовать только с форматом вывода в каталог, так как это единственный формат, позволяющий нескольким процессам записывать данные одновременно.pg_dump откроет
число_заданий
+ 1 соединений с базой данных. Таким образом необходимо обеспечить достаточное значение параметра max_connections.Если во время выгрузки в несколько потоков параллельно работающие сеансы будут запрашивать эксклюзивные блокировки на объекты базы данных, то pg_dump может завершиться аварийно. Дело в том, что головной процесс pg_dump вначале запрашивает разделяемые блокировки (ACCESS SHARE) на объекты, которые позже будут выгружать рабочие процессы. Это делается для того, чтобы никто не смог удалить объекты на время работы pg_dump. Если же другой сеанс запросит эксклюзивную блокировку на объект, то запрос на блокировку будет поставлен в очередь, до тех пор пока разделяемая блокировка головного процесса pg_dump не будет снята. В последующем, любая попытка доступа к этому объекту будет вставать в очередь, вслед за эксклюзивной блокировкой. В том числе в очередь попадет и рабочий процесс pg_dump. Если не принять меры предосторожности, то получим классическую взаимоблокировку. Для предупреждения подобных конфликтов, рабочий процесс pg_dump ещё раз запрашивает разделяемую блокировку на объект с указанием
NOWAIT
. И если он не смог получить блокировку, значит кто-то ещё запросил эксклюзивную блокировку объекта. А это значит, что нет возможности продолжить выгрузку, поэтому pg_dump прерывает дальнейшую работу.Для выполнения параллельной выгрузки сервер баз данных должен поддерживать функциональность синхронизированных снимков, которая была введена в версии PostgreSQL 9.2 для ведущих серверов и в 10 для ведомых. Это позволяет разным клиентам работать с одной и той же версией данных, несмотря на использование разных подключений.
pg_dump -j
использует множественные подключения. Первое подключение осуществляется головным процессом, а последующие — рабочими процессами. Без функциональности синхронизируемых снимков нет гарантии того, что каждое подключение увидит одни и те же данные, что может привести к несогласованности данных резервной копии.-n
шаблон
--schema=
шаблон
Выгрузить только схемы, соответствующие
шаблону
; вместе с этими схемами будут выгружены и все содержащиеся в них объекты. Когда этот параметр отсутствует, выгружаются все несистемные схемы в целевой базе данных. Чтобы выгрузить несколько схем, ключ-n
можно указать несколько раз. Параметршаблон
интерпретируется по тем же правилам, что и шаблон в командах psql\d
(см. Шаблоны поиска), так что несколько схем можно выбрать и шаблоном со знаками подстановки. Используя знаки подстановки, при необходимости заключайте шаблон в кавычки, чтобы эти знаки не разворачивала оболочка системы (см. Примеры ниже).Примечание
При использовании
-n
, pg_dump не выгружает объекты других схем, от которых выгружаемая схема может зависеть. Таким образом не гарантируется, что выгруженная схема будет успешно восстановлена в чистой базе данных.Примечание
Не принадлежащие схемам объекты (например, большие объекты), не выгружаются с параметром
-n
. Однако можно указать--large-objects
, чтобы они попали в выгрузку.-N
шаблон
--exclude-schema=
шаблон
Не выгружать схемы, соответствующие
шаблону
. Шаблон интерпретируется по тем же правилам, что и для параметра-n
. Параметр-N
можно использовать в команде несколько раз для исключения схем, соответствующих нескольким шаблонам.При одновременном использовании параметров
-n
и-N
будут выгружаться схемы, соответствующие шаблону параметра-n
и не противоречащие шаблону параметра-N
.-O
--no-owner
Не формировать команды, устанавливающие владельца объектов базы данных. По умолчанию pg_dump генерирует команды
ALTER OWNER
илиSET SESSION AUTHORIZATION
для назначения владельцев объектов базы. Эти команды завершатся неудачно, если скрипт будет запущен не суперпользователем или не владельцем объектов. Чтобы создать скрипт, который можно выполнить при восстановлении от лица произвольного пользователя и назначить его в качестве владельца объектов восстанавливаемой базы, необходимо указать флаг-O
.Этот параметр игнорируется, когда данные выгружаются в архивных форматах (не в текстовом). Для таких форматов данный параметр можно указать при вызове
pg_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
можно указать несколько раз. Параметршаблон
интерпретируется по тем же правилам, что и шаблон в командах psql\d
(см. Шаблоны поиска), так что несколько таблиц можно выбрать и шаблоном со знаками подстановки. Используя знаки подстановки, при необходимости заключайте шаблон в кавычки, чтобы эти знаки не разворачивала оболочка системы (см. Примеры ниже).Помимо обычных таблиц, с этим указанием можно выгрузить определения соответствующих шаблону последовательностей, представлений, материализованных представлений и сторонних таблиц. При этом содержимое представлений и матпредставлений выгружаться не будет, а содержимое сторонних таблиц будет выгружено, только если в аргументе
--include-foreign-data
указан соответствующий сторонний сервер.Параметры
-n
и-N
не действуют в присутствии параметра-t
, так как отобранные им таблицы всё равно будут выгружены, а не табличные объекты выгружаться не будут.Примечание
При использовании
-t
, pg_dump не выгружает прочие объекты, от которых выгружаемые таблицы могут зависеть. Таким образом не гарантируется, что выгруженные таблицы будут успешно восстановлены в чистой базе данных.-T
шаблон
--exclude-table=
шаблон
Не выгружать таблицы, соответствующие
шаблону
. Шаблон интерпретируется по тем же правилам, что и для параметра-t
. Параметр-T
можно использовать в команде несколько раз для исключения таблиц, соответствующих нескольким шаблонам.При одновременном использовании параметров
-t
и-T
будут выгружаться таблицы, соответствующие шаблону параметра-t
и не противоречащие шаблону параметра-T
.-v
--verbose
Включить подробный режим. pg_dump будет выводить в стандартный поток ошибок подробные комментарии к объектам, включая время начала и окончания выгрузки, а также сообщения о прогрессе выполнения. Если повторить этот ключ, в стандартный поток ошибок будут выдаваться дополнительные отладочные сообщения.
-V
--version
Вывести версию pg_dump.
-x
--no-privileges
--no-acl
Не выгружать права доступа (команды GRANT/REVOKE).
-Z
уровень
-Z
[:метод
строка_информации
]--compress=
уровень
--compress=
[:метод
строка_информации
]Указывает метод и/или уровень сжатия. В качестве метода сжатия можно выбрать
gzip
,lz4
,zstd
илиnone
(без сжатия). В качестве дополнительной информации можно передать параметры сжатия. Если в строке информации передаётся целое число, оно задаёт уровень сжатия. В противном случае она должна содержать список элементов, разделённых запятыми, в формеключевое_слово
илиключевое_слово=значение
. На данный момент поддерживаются ключевые словаlevel
иlong
.Если уровень сжатия не указан, будет выбран уровень сжатия по умолчанию. Если указан только уровень сжатия, но не указан метод, будет применяться метод сжатия
gzip
, когда уровень больше0
, а когда уровень равен0
, сжатие не будет выполняться.Для специального формата и формата каталога будут сжиматься файлы отдельных таблиц. По умолчанию применяется умеренный уровень сжатия с использованием
gzip
. Если указать отличный от нулевого уровень сжатия для простого формата, то сжиматься будет весь выходной файл, как это было бы при передаче файла команде gzip, lz4 или zstd. Однако по умолчанию для простого формата сжатие не производится. Сжатие с использованием zstd можно проводить с указаниемlong
, что может улучшить коэффициент сжатия за счёт повышения нагрузки на память.Формат
tar
в настоящий момент не поддерживает сжатие.--binary-upgrade
Этот параметр предназначен для утилит обновления сервера. Использование для иных целей не рекомендуется и не поддерживается. Поведение параметра может быть изменено в последующих версиях без предварительного уведомления.
--column-inserts
--attribute-inserts
Выгружать данные таблиц в виде команд
INSERT
с явным указанием столбцов (INSERT INTO
). Скорость восстановления при этом значительно снизится, но данный вариант оправдан, когда загружать данные нужно не в Postgres Pro. При этом в случае каких-либо ошибок при загрузке данных будут потеряны только строкитаблица
(столбец
, ...) VALUES ...INSERT
, где возникли ошибки, но не всё содержимое таблицы.--disable-dollar-quoting
Этот параметр запрещает заключать в доллары тело функций, что оставляет возможность только заключать их в кавычки, применяя стандартный синтаксис SQL.
--disable-triggers
Используется при выгрузке одних данных. Указывает pg_dump включать в вывод команды для временного выключения триггеров при восстановлении в целевой базе данных. Применяется в ситуациях, когда существуют проверки ссылочной целостности или другие триггеры, которые необходимо выключить на время восстановления.
В настоящее время команды, генерируемые с параметром
--disable-triggers
, должны исполняться от имени суперпользователя. Таким образом, необходимо также передавать флаг-S
, либо при восстановлении выполнять скрипт от имени суперпользователя.Этот параметр игнорируется, когда данные выгружаются в архивных форматах (не в текстовом). Для таких форматов данный параметр можно указать при вызове
pg_restore
.--enable-row-security
Этот параметр имеет смысл только при выгрузке содержимого таблицы, для которой включена защита строк. По умолчанию pg_dump устанавливает для row_security значение off, чтобы убедиться, что выгружаются все данные из таблицы. Если пользователь не имеет достаточных прав для обхода защиты строк, выдаётся ошибка. Этот параметр указывает pg_dump включить row_security, что позволит пользователю выгрузить часть содержимого таблицы, к которой он имеет доступ.
Заметьте, что в настоящее время для использования этого параметра обычно желательно, чтобы данные были выгружены в формате
INSERT
, так как командаCOPY FROM
в процессе восстановления не поддерживает защиту строк.--exclude-extension=
шаблон
Не выгружать расширения, соответствующие
шаблону
. Шаблон интерпретируется по тем же правилам, что и для параметра-e
. Параметр--exclude-extension
можно использовать в команде несколько раз для исключения расширений, соответствующих нескольким шаблонам.При одновременном использовании параметров
-e
и-exclude-extension
будут выгружаться расширения, соответствующие шаблону параметра-e
, но не шаблону параметра--exclude-extension
. Использование--exclude-extension
без-e
исключит из выгрузки расширения, соответствующие--exclude-extension
.--exclude-table-and-children=
шаблон
Этот параметр делает то же, что
-T
/--exclude-table
, кроме того, что с ним также исключаются любые наследуемые дочерние таблицы или секции таблиц, соответствующихшаблону
.--exclude-table-data=
шаблон
Не выгружать содержимое таблиц, соответствующих
шаблону
. Шаблон таблицы интерпретируется по тем же правилам, что и для параметра-t
. Параметр--exclude-table-data
можно использовать в команде несколько раз для исключения таблиц, соответствующих нескольким шаблонам. Полезно, когда нужно получить определение таблицы, без содержимого.Чтобы не выгружать содержимое всех таблиц базы, используйте параметр
--schema-only
.--exclude-table-data-and-children=
шаблон
Этот параметр делает то же, что
--exclude-table-data
, кроме того, что с ним также исключаются данные любых наследуемых дочерних таблиц или секций таблиц, соответствующихшаблону
.--extra-float-digits=
число_цифр
Выводить числа с плавающей точкой не с максимальной точностью, а с заданным значением
extra_float_digits
. При выгрузке данных в целях резервного копирования данный параметр использовать не следует.--filter=
имя_файла
Задаёт имя файла, из которого будут считываться шаблоны включения/исключения объектов из выгрузки. Шаблоны интерпретируются по тем же правилам, что и соответствующие параметры:
-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 }
ШАБЛОН
Первое ключевое слово указывает, будут ли объекты, соответствующие шаблону, включены или исключены. Второе ключевое слово указывает тип объектов, фильтруемых с помощью шаблона:
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
: табличные данные любых таблиц, соответствующихшаблону
; работает как параметр--exclude-table-data
. Это ключевое слово может использоваться только с ключевым словомexclude
.table_data_and_children
: табличные данные любых таблиц, соответствующихшаблону
, а также любые секции или дочерние таблицы в иерархии наследования; работает как параметр--exclude-table-data-and-children
. Это ключевое слово может использоваться только с ключевым словомexclude
.schema
: схемы; работает как параметр-n
/--schema
или-N
/--exclude-schema
.
Строки, начинающиеся с
#
, считаются комментариями и игнорируются. Комментарии также могут размещаться после строки с шаблоном объекта. Пустые строки также игнорируются. См. раздел Шаблоны поиска для информации о том, как применять экранирование в шаблонах.Примеры файлов приведены ниже в Примеры.
--if-exists
Использовать команды
DROP ... IF EXISTS
для удаления объектов в режиме--clean
. При этом возможные ошибки «does not exist» (не существует) не выводятся. Этот параметр недействителен без указания--clean
.--include-foreign-data=
сторонний_сервер
Выгрузить данные всех сторонних таблиц со стороннего сервера, имя которого соответствует шаблону
сторонний_сервер
. Для выгрузки данных с нескольких сторонних серверов параметр--include-foreign-data
можно использовать несколько раз. К тому же, значениесторонний_сервер
интерпретируется как шаблон, согласно правилам, используемым командами\d
утилиты psql (см. Шаблоны поиска). Поэтому несколько сторонних серверов можно также выбрать, используя в шаблоне символы подстановки. Когда используются символы подстановки, шаблон лучше экранировать кавычками, чтобы командная оболочка ОС не интерпретировала их по-своему (см. Примеры ниже). Единственное отличие от вышеупомянутых правил — шаблон не может быть пустым.Примечание
Использование знаков подстановки в
--include-foreign-data
может привести к доступу к неподходящим сторонним серверам. Кроме того, для безопасного использования этого параметра необходимо убедиться, что у указанного сервера есть доверенный владелец.Примечание
Когда используется параметр
--include-foreign-data
, pg_dump не проверяет возможность записи в стороннюю таблицу. Таким образом, не гарантируется, что выгруженная сторонняя таблица может быть успешно восстановлена.--inserts
Выгружать данные таблиц в виде команд
INSERT
вместоCOPY
. Скорость восстановления при этом значительно снизится, но данный вариант оправдан, когда загружать данные нужно не в Postgres Pro. При этом в случае каких-либо ошибок при загрузке данных будут потеряны только строки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
По умолчанию
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=
число_строк
Выгружать данные таблиц в виде команд
INSERT
вместоCOPY
. В данном параметре задаётся максимальное число строк для одной командыINSERT
. Указанное в нём значение должно быть больше 0. При этом в случае каких-либо ошибок при загрузке данных будут потеряны только строкиINSERT
, где возникли ошибки, но не всё содержимое таблицы.--section=
имя_секции
Выгружать лишь указанную секцию. Имя секции может принимать значения
pre-data
,data
илиpost-data
. Для выгрузки нескольких секций, параметр можно использовать несколько раз в одной команде. По умолчанию резервируются все секции.Секция
data
содержит непосредственно данные таблиц, больших объектов и значения последовательностей. Секцияpost-data
содержит определения индексов, триггеров, правил и ограничений (кроме ограничений проверки, созданных безNOT VALID
). Секцияpre-data
включает определения остальных элементов.--serializable-deferrable
Использовать при выгрузке транзакцию с уровнем изоляции
serializable
для получения снимка, согласованного с последующими состояниями базы. Правда для этого нужно выждать момент, когда в потоке транзакций нет аномалий, и поэтому нет риска, что выгрузка завершится неудачно, и риска отката других транзакций с ошибкойserialization_failure
. Более подробно изоляция транзакций и управление одновременным доступом описывается в Главе 13.Параметр не особо полезен в случаях, когда требуется восстановление после сбоя. Он полезен для создания копии базы данных, в которой формируются отчёты и выполняются другие операции чтения, в то время как в основной базе продолжается обычная работа. Без этого параметра выгрузка может содержать не целостное состояние базы данных. Например, если используется пакетная обработка, статус пакета может отражаться как завершённый, в то время как в выгрузке будут не все элементы пакета.
Параметр не будет влиять на результат, если во время запуска pg_dump нет активных транзакций на чтение-запись. Если же активные транзакции чтения-записи есть, то начало выгрузки может быть отложено на неопределённый период времени. После того как выгрузка началась, производительность с этим ключом или без него будет одинаковой.
--snapshot=
имя_снимка
Использовать заданный синхронный снимок при выгрузке данных из базы (за подробностями обратитесь к Таблице 9.98).
Этот параметр полезен, когда требуется синхронизировать выгружаемые данные со слотом логической репликации (см. Главу 47) или с другим одновременным сеансом.
В случае с параллельной выгрузкой будет использоваться имя снимка, определённое этим параметром; новый снимок не будет сделан.
--strict-names
Требует, чтобы каждому шаблону расширения (
-e
/--extension
), схемы (-n
/--schema
) и таблицы (-t
/--table
) соответствовал минимум один объект (расширение/схема/таблица) в выгружаемой базе данных. Это также относится и к фильтрам, используемым в параметре--filter
. Заметьте, что если не находится вообще ни одного такого объекта для заданных шаблонов, pg_dump выдаёт ошибку и без ключа--strict-names
.Этот параметр не действует на ключи
--exclude-extension
,-N
/--exclude-schema
,-T
/--exclude-table
или--exclude-table-data
. Если не находятся объекты, соответствующие шаблонам исключения, это не считается ошибкой.--sync-method=
метод
Со значением
fsync
(по умолчанию)pg_dump --format=directory
будет рекурсивно открывать и синхронизировать все файлы в каталоге архива.В Linux возможен вариант
syncfs
, когда от ОС требуется синхронизировать целиком каждую из файловых систем, содержащих каталог архива. Более подробно особенности использованияsyncfs
описаны в recovery_init_sync_method.Этот параметр не действует в режиме
--no-sync
или если значение параметра--format
неdirectory
.--table-and-children=
шаблон
Этот параметр делает то же, что
-t
/--table
, кроме того, что с ним также включаются любые наследуемые дочерние таблицы или секции таблиц, соответствующихшаблону
.--use-set-session-authorization
Выводить команды
SET SESSION AUTHORIZATION
, соответствующие стандарту, вместоALTER OWNER
, для назначения владельцев объектов. В результате выгруженный скрипт будет более стандартизированным, но может не восстановиться корректно, в зависимости от истории объектов. Кроме того, для использованияSET SESSION AUTHORIZATION
при восстановлении нужны права суперпользователя, в то время какALTER OWNER
требует меньших привилегий.-?
--help
Показать справку по аргументам командной строки pg_dump и завершиться.
Далее описаны параметры управления подключением.
-d
имя_бд
--dbname=
имя_бд
Указывает имя базы данных для подключения. Равнозначно указанию
имя_бд
в первом аргументе, не являющемся ключом, в командной строке. Вместо имени может задаваться строка подключения. В этом случае параметры в строке подключения переопределяют одноимённые параметры, заданные в командной строке.-h
сервер
--host=
сервер
Указывает имя компьютера, на котором работает сервер. Если значение начинается с косой черты, оно определяет каталог Unix-сокета. Значение по умолчанию берётся из переменной окружения
PGHOST
, если она установлена. В противном случае выполняется подключение к Unix-сокету.-p
порт
--port=
порт
Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения. Значение по умолчанию определяется переменной окружения
PGPORT
, если она установлена, либо числом, заданным при компиляции.-U
имя_пользователя
--username=
имя_пользователя
Имя пользователя, под которым производится подключение.
-w
--no-password
Не выдавать запрос на ввод пароля. Если сервер требует аутентификацию по паролю и пароль не доступен с помощью других средств, таких как файл
.pgpass
, попытка соединения не удастся. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, который вводит пароль.-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как pg_dump запрашивает пароль автоматически, если сервер проверяет подлинность по паролю. Однако чтобы понять это, pg_dump лишний раз подключается к серверу. Поэтому иногда имеет смысл ввести
-W
, чтобы исключить эту ненужную попытку подключения.--role=
имя роли
Задаёт имя роли, которая будет осуществлять выгрузку. Получив это имя, pg_dump выполнит
SET ROLE
имя_роли
после подключения к базе данных. Это полезно, когда проходящий проверку пользователь (указанный в-U
) не имеет прав, необходимых для pg_dump, но может переключиться на роль, наделённую этими правами. В некоторых окружениях правила запрещают подключаться к серверу непосредственно суперпользователю, и этот параметр позволяет выполнить выгрузку, не нарушая их.
Переменные окружения
PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию.
PG_COLOR
Выбирает вариант использования цвета в диагностических сообщениях. Возможные значения:
always
(всегда),auto
(автоматически) иnever
(никогда).
Эта утилита, как и большинство других утилит Postgres Pro, также использует переменные среды, поддерживаемые libpq (см. Раздел 32.15).
Диагностика #
pg_dump на низком уровне выполняет команды SELECT
. Если есть проблемы с работой pg_dump, убедитесь, что в базе данных можно выполнить SELECT
, например из psql. Также следует учитывать, что при этом применяются все свойства подключения по умолчанию и переменные окружения, которые использует клиентская библиотека libpq.
Обычно действия pg_dump в базе данных отслеживаются системой накопительной статистики. Если это нежелательно, то можно установить параметр track_counts
в false в переменной окружения PGOPTIONS
или в команде ALTER USER
.
Примечания #
Если в базу данных кластера template1
устанавливались дополнительные объекты, то следует убедиться, что выгрузка pg_dump загружается в пустую базу данных. Иначе существует вероятность возникновения ошибок дублирования создаваемых объектов. Чтобы создать пустую базу данных, копируйте её из шаблона template0
, вместо template1
, например:
CREATE DATABASE foo WITH TEMPLATE template0;
Если выгружаются только данные с одновременным использованием --disable-triggers
, pg_dump сформирует команды для выключения табличных триггеров перед вставкой данных, а после них — команды, включающие триггеры обратно. Если восстановление будет прервано в середине процесса, системный каталог может остаться в неверном состоянии.
Сформированный pg_dump файл не содержит статистики, которую использует планировщик для принятия решений при планировании запросов. Поэтому после восстановления разумно будет выполнить ANALYZE
для достижения оптимальной производительности; за дополнительными сведениями обратитесь к Подразделу 23.1.3 и Подразделу 23.1.6.
Так как pg_dump применяется для переноса данных в новые версии Postgres Pro, предполагается, что вывод pg_dump можно загрузить на сервер Postgres Pro более новой версии, чем версия pg_dump. pg_dump может также выгружать данные серверов Postgres Pro более старых версий, чем его собственная. (В настоящее время поддерживаются версии, начиная с PostgreSQL 9.2.) Однако утилита pg_dump не может выгружать данные с серверов Postgres Pro более новых основных версий; она не будет даже пытаться делать это, во избежание некорректной выгрузки. Также не гарантируется, что вывод pg_dump может быть загружен на сервере более старой основной версии — даже если данные были выгружены с сервера той же версии. Для загрузки такого файла на старом сервере может потребоваться вручную исправить в нём синтаксис, не воспринимаемый старой версией. Имея дело с разными версиями, рекомендуется применять параметр --quote-all-identifiers
, так как он может предотвратить проблемы, возникающие при изменении множества зарезервированных слов в разных версиях PostgreSQL.
Выгружая подписки на логическую репликацию, pg_dump будет выдавать команды CREATE SUBSCRIPTION
с указанием connect = false
, так что при восстановлении подписки не будут устанавливаться удалённые подключения для создания слота репликации или для начального копирования таблиц. Таким образом, выгруженные данные могут быть восстановлены без сетевого доступа к удалённым серверам. Вновь активировать подписки должным образом — задача пользователя. Если задействованные серверы поменялись, возможно, придётся скорректировать информацию о подключении. Также может быть уместно опустошить целевые таблицы перед началом полного копирования таблиц. Если пользователь намерен копировать исходные данные во время обновления, он должен создать слот с параметром two_phase = false
. После начальной синхронизации параметр two_phase
будет автоматически включён подписчиком, если подписка изначально была создана с параметром two_phase = true
.
Примеры #
Выгрузка базы данных mydb
в файл SQL-скрипта:
$
pg_dump mydb > db.sql
Восстановление из ранее полученного скрипта в чистую базу newdb
:
$
psql -d newdb -f db.sql
Выгрузка базы данных в специальном формате:
$
pg_dump -Fc mydb > db.dump
Выгрузка базы данных в формате каталога:
$
pg_dump -Fd mydb -f dumpdir
Выгрузка базы данных в формате каталога в 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