8
июля
1

pg_dump



Наименование
pg_dump — извлекает базу данных PostgreSQL в скриптовый или архивный файл

Синтаксис
pg_dump [connection-option…] [option…] [dbname]

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

Альтернативные архивные форматы файла для восстановления базы данных используются с pg_restore. Они дают возможность pg_restore выбрать что восстанавливать или даже изменить порядок приоритетов пунктов при восстановлении. Архивные форматы файлов разработанные портативными для всех архитектур.
Использование одного из архивных форматов файла и комбинирование с pg_restore, pg_dump обеспечивает гибкий механизм архивирования и переноса. pg_dump может быть использован для резервного копирования всей базы данных, тогда с помощью pg_restore можно посмотреть содержимое архива и/или выбрать какие части базы данных нужно восстановить. Наибольшую гибкость выходного файла имеет пользовательский формат «custom» (-Fc). Он дает возможность выбора и изменения порядка всех пунктов архивирования, и использует сжатие по умолчанию.

Во время работы pg_dump следует проверять вывод на предмет каких-либо предупреждений (вывод на stderr), особенно в свете ограничений, перечисленных ниже.

Опции

Следующие опции командной строки управляют содержанием и форматом вывода.
dbname
Задает имя базы данных для резервного копирования. Если не установлено, то для этого используется переменная окружения PGDATABASE. Если и она не установлена, то используется имя пользователя при подключении.
-a
— -data-only
Скидывать в дамп только данные (определения данных).
Эта опция имеет смысл только для текстового формата. Для архивных форматов можно задать опцию при вызове pg_restore.
-b
— -blobs
Включать большие объекты в дамп. Эта опция установлена по умолчанию за исключением, когда присутствуют опции — -schema, — -table, или — -schema-only, следовательно включать -b полезно только при добавлении больших объектов в выборочном дампе.
-c
— -clean
В дамп добавляются команды для очистки (drop) объектов базы данных перед командами для их создания. (Восстановление может вызвать некоторые безвредные ошибки.)
Эта опция имеет смысл только для текстового формата. Для архивных форматов можно задать опцию при вызове pg_restore.
-C
— -create
В начале вывода включается команда для создания данной базы данных и дальнейшего подключения к ней. (В данном случае не имеет значения какая база данных используется для подключения перед выполнением содержимого дампа.)
Эта опция имеет смысл только для текстового формата. Для архивных форматов можно задать опцию при вызове pg_restore.
-E encoding
— -encoding=encoding
Создать дамп в определенной кодировке символов. По умолчанию создается в кодировке базы данных. (Получить такой же результать возможно при установке переменной среды PGCLIENTENCODING в желаемую кодировку дампа.)
-f file
—file=file
Направить вывод в заданный файл. Этот параметр может быть пропущен для базового формата вывода, в случае использования стандартного вывода (stdout). Он должен быть установлен при формате вывода directory, однако будет определять директорию вместо файла. В этом случае директория создается утилитой pg_dump и должна не существовать до этого.
-F format
—format=format
Выбор формата вывода. format может быть одним из следующих:
p
plain
Вывод простого текстового файла с набором SQL команд (по умолчанию).
c
custom
Вывод в архивном пользовательском формате, подходящем для входа в pg_restore. Вместе с форматом вывода directory это наиболее гибкий формат вывода, так как позволяет ручной выбор и изменение порядка элементов архивирования при восстановлении. Этот формат также сжатый по умолчанию.
d
directory
Формат вывода в каталог подходящий для входа в pg_restore. При его задании будет создана директория с одним файлом для каждой таблицы и больших объектов, которые архивируются, дополнительно файл так называемой таблицы содержания, описывающей сохраненные объекты в машиночитаемом формате, который pg_restore умеет читать. Архивами в этом формате можно управлять с помощью стандартных инструментов UNIX; например, несжатые файлы в архиве могут быть сжаты с помощью gzip. Этот формат обладает сжатием по умолчанию.
t
tar
Формат вывода tar подходящий для входа в pg_restore. tar-формат является совместимым с directory-форматом; извлечение из архива в tar-формате дает правильный архив в directory-формате. Однако, tar-формат не поддерживает сжатие и имеет ограничение на размер в 8 GB для отдельных таблиц. Также релятивный порядок пунктов для табличных данных не может быть изменен в течении восстановления.
-i
—ignore-version
Устаревшая опция, которая в настоящее время игнорируется.
-n schema
—schema=schema
Помещать в дамп только схемы соответствующие schema; этим выбирается как сама схема, так и все элементы, в ней содержащиеся. Когда эта опция не установлена, то будут сохранены все схемы целевой базы данных, кроме системных. Несколько схем может быть задано путем написания их всех с ключом -n. Также параметр schema интерпретируется как шаблон в соответствии с теми же правилами используемыми командой \d консольного клиента psql, поэтому несколько схем может быть выбрано написанием маски символов в шаблоне. Когда используются маски нужно быть осторожными с кавычками в шаблоне если нужно предотвратить распространение масок на командный интерпретатор; см. примеры.
Примечание: Когда -n задана, то pg_dump не пытается сбросить в дамп любые другие объекты базы данных от которых может зависеть выбранная схема(ы). Поэтому нет никакой гарантии, что результаты дампа конкретной схемы могут быть успешно восстановлены сами по себе в чистую базу данных.
Примечание: Объекты, не относящиеся к схеме, такие как blobs, не архивируются, когда -n задана. Можно добавить объекты blobs в дамп опцией —blobs.
-N schema
—exclude-schema=schema
Не добавлять в дамп любые схемы соответствующие шаблону schema. Шаблон интерпретируется в соответствии с теме же правилами, что и для -n. -N может быть задано более одного раза, исключая схемы соответствующие любым из нескольких шаблонов.
Когда заданы обе опции -n и -N в дамп сбрасываются только те схемы, которые соответствуют хотя бы одному из заданных вхождений -n и ни одному -N. При наличии -N без заданных -n, схемы соответствующие перечисленным в -N исключаются из дампа.
-o
—oids
Сбрасывать в дамп идентификаторы объектов (OID
-O
—no-owner
Не включать в дамп команды задания принадлежности объектов, соответствующего оригинальной базе данных. По умолчанию pg_dump содержит предписание ALTER OWNER или SET SESSION AUTHORIZATION для установки принадлежности объектов созданной базы данных. Эти утверждения потерпят неудачу когда выполняется сценарий, если он был запущен суперпользователем (или некоторым пользователем, которому принадлежат все объекты в сценарии). Для создания сценария, который может быть восстановлен любым пользователем, но даст пользователю право владения всеми объектами, установите -O.
Эта опция имеет смысл только для текстового формата. Для архивных форматов можно задать опцию при вызове pg_restore.
-R
—no-reconnect
Эта опция устарела, но по-прежнему принимается для обеспечения обратной совместимости.
-s
—schema-only
Включать в дамп только определения объектов (схема), а не данные.
-S username
—superuser=username
Можно указать имя суперпользователя, для использования при отключении триггеров. Это имеет смысл только если используется —disable-triggers. (Обычно это лучше оставить в стороне, а взамен запускать полученный сценарий как суперпользователь.)
-t table
—table=table
Помещать в дамп только таблицы (или представления или последовательности или внешние таблицы), соответствующие table. Несколько таблиц могут быть выбраны написанием их всех с ключем -t. Также параметр table интерпретируется как шаблон в соответствии с теми же правилами используемыми командой \d консольного клиента psql, поэтому несколько таблиц может быть выбрано написанием маски символов в шаблоне. Когда используются маски нужно быть осторожными с кавычками в шаблоне если нужно предотвратить распространение масок на командный интерпретатор; см. примеры.
Переключатели -n и -N не действуют, когда используется -t, потому что выбранные таблицы с помощью -t будут сброшены в дамп независимо от этих установок и не табличные данные в дамп помещаться не будут.
Примечание: Когда -t задана, то pg_dump не пытается сбросить в дамп любые другие объекты базы данных от которых может зависеть выбранная таблица(ы). Поэтому нет никакой гарантии, что результаты дампа конкретной таблицы могут быть успешно восстановлены сами по себе в чистую базу данных.
Примечание: Поведение опции -t не вполне совместимо с версиями PostgreSQL меньше 8.2. Раньше написав -t tab в дамп попадали бы все таблицы с названием tab, а сейчас это только дампы той одной, которая находится в пути поиска по умолчанию. Получить прежнее поведение можно написав -t ‘*.tab’. Также вы должны написать что-то подобное -t sch.tab для выбора таблицы в определенной схеме, а не старое решение через -n sch -t tab.
-T table
—exclude-table=table
Не сбрасывать в дамп любые таблицы соответствующие шаблону table. Шаблон интерпретируется в соответствии с теме же правилами, что и для -t. -T может быть задано более одного раза, исключая схемы соответствующие любым из нескольких шаблонов. Когда заданы обе опции -t и -T в дамп сбрасываются только те таблицы, которые соответствуют хотя бы одному из заданных вхождений -n и ни одному -N. При наличии -T без заданных -t, таблицы соответствующие перечисленным в -T исключаются из дампа.
-v
—verbose
Установить подробный режим. В этом случае pg_dump будет выводить детальные комментарии объекта и время пуска/завершения создания файла дампа, и сообщения хода выполнения направляются на стандартный поток ошибок.
-V
—version
Вывести версию pg_dump и завершить работу.
-x
—no-privileges
—no-acl
Не сохранять права доступа (команды grant/revoke).
-Z 0..9
—compress=0..9
Установить какой использовать уровень сжатия. Ноль означает без сжатия. Для архивного формата custom это указывает отдельных сегментов данных таблицы и по умолчанию сжимается на умеренном уровне. Для простого текстового формата вывода в случае установки ненулевого уровня сжатия весь выходной файл будет сжат, как если бы это было сделано через GZIP; но по умолчанию не сжимается. Архив в формате tar на текущий момент не поддерживает сжатие вообще.
—binary-upgrade
Эта опция предназначена для использования вместо утилиты обновления. Ее применение для других целей не рекомендуется и не поддерживается. Поведение для опции может измениться в будущих версиях без предварительного уведомления.
—column-inserts
—attribute-inserts
Сохранять данные как INSERT-команды с точным определением названия столбцов (INSERT INTO table (column, …) VALUES …). Это будет приводить к очень медленному восстановлению; это главным образом полезно для создания дампов, которые могут быть загружены в не-PostgreSQL базы данных. Однако, поскольку эта опция создает отдельную команду для каждой строки, то в случае ошибки при загрузке строки, только эта строка будет потеряна, а не все содержимое таблицы. Обратите внимание, что восстановление может пройти не совсем удачно если реконструировать порядок столбцов. Опция —column-inserts предотвратит изменения порядка столбцов, но замедлит работу .
—lock-wait-timeout=timeout
Не ждать всегда достижения блокировок разделяемой таблицы в начале создания дампа. Вместо этого потерпеть неудачу если блокировка таблицы недоступна в течении установленного timeout. Тайм-аут может быть указан в любом из форматов, принятых командой SET statement_timeout. (Допустимые значения изменяются в зависимости от версии сервера с которого снимается дамп, но целое число миллисекунд, принимается всеми версиями с 7.3. Эта опция игнорируется, когда версия мешьше чем 7.3.)
—no-security-labels
Не сбрасывать в дамп метки безопасности.
—no-tablespaces
Не включать в вывод команды выбора табличных пространств. С этой опцией все объекты будут созданы в табличном пространстве используемом по умолчанию во время восстановления. Эта опция имеет смысл только для простого текстового формата. Для архивных форматов можно задать опцию при вызове pg_restore.
—no-unlogged-table-data
Не сбрасывать в дамп содержимое незарегистрированных таблиц. Эта опция не повлияет на результат в зависимости от наличия или отсутствия определений сохраняемой таблицы (схемы); она только подавляет сброс в дамп данных таблицы.
—quote-all-identifiers
Принужденное включение в кавычки всех идентификаторов. Это может быть полезным, когда сбрасывается в дамп база данных для миграции на будущую версию, в которую могут быть введены дополнительные ключевые слова.
—serializable-deferrable
Использовать для дампа сериализуемые транзакции, чтобы обеспечить получение снимка, который является согласующимся с более поздними состояниями базы данных; но происходит это ожидая точки в потоке транзакций, при которой не могут присутствовать аномалии, таким образом нет риска неудачи дампа или предпосылок другими транзакциями отката с serialization_failure. В главе 13 можно найти более детальную информацию о изоляции транзакции и управление параллелизмом.
Эта опция не является благоприятной для дампа, который предназначен только для аварийного восстановления. Это может быть полезно для дампа, используемого для загрузки копии базы данных для отчетности и другого распределения нагрузки только для чтения в то время как исходная база данных продолжает обновляться. Без этого дамп может отражать состояние, которое является не согласующимся с любым порядковым выполнением транзакций в итоге совершенных. Например, если используются методы пакетной обработки, пакет может представляться как замкнутый в дампе без всех элементов, которые проявляются в пакете.
Эта опция будет безразлична если нет активных операций чтения-записи во время запуска pg_dump. Если активные операции чтения-записи существуют, начало создания дампа может быть отложено на неопределенное количество времени. Производительность после запуска с или без переключателя одинаковая.
—use-set-session-authorization
Включить в вывод стандартные SQL-команды SET SESSION AUTHORIZATION вместо команд ALTER OWNER для установки права собственности объекта. Это делает дамп более совместимым со стандартами, но в зависимости от истории объектов в дампе может не восстановиться должным образом. Также, дамп использующий SET SESSION AUTHORIZATION будет непременно требовать привилегий суперпользователя для корректного восстановления, в то время как ALTER OWNER требует меньших привилегий.
-?
—help
Показать справку по аргументам командной строки pg_dump и выйти.

Следующие опции командной строки управляют параметрами подключения к базе данных.
-h host
—host=host
Задает сетевое имя машины на которой работает сервер. Если значение начинается с косой черты, оно используется в качестве указателя для Unix-сокета. По умолчанию берется из переменной окружения PGHOST, если она установлена, иначе попытается подключиться к Unix-сокету.
-p port
—port=port
Задает порт TCP или файл локального Unix-сокет на котором сервер прослушивает подключения. По умолчанию используется переменная окружения PGPORT, если установлена, или значение заданное по умолчанию при компиляции.
-U username
—username=username
Имя пользователя от которого происходит подключение.
-w
—no-password
Никогда не выдавать приглашения ввести пароль. Если сервер требует аутентификации с помощью пароля и пароль не доступен другим способом, таким как файл .pgpass, то попытка подключения завершиться неудачей. Эта опция может быть полезна в ряде задач и скриптов, где от пользователя не требуется ввод пароля.
-W
—password
pg_dump принудительно выдает приглашение для ввода пароля перед подключением к базе данных.
Эта опция всегда несущественна, так как pg_dump автоматически запросит пароль, если сервер требует аутентификации по паролю. Однако pg_dump будет совершать излишнюю попытку подключения, определив, что серверу необходим пароль. В некоторых случаях имеет смысл вводить -W, чтобы избежать дополнительной попытки соединения.
—role=rolename
Определяет имя роли, которое будет использоваться для создания дампа. Эта опция заставляет pg_dump выдавать команду SET ROLE rolename после подключения к базе данных. Это полезно, когда у аутентифицированного пользователя (задается опцией -U) не хватает привилегий необходимых pg_dump, но можно сменить на роль с требуемыми правами. Некоторые установки имеют политику против входа в систему непосредственно в качестве суперпользователя и использование этой опции позволяет создавать дампы без нарушения политики.

Окружение
PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER

Параметры подключения по умолчанию.
Эта утилита (прим. pg_dump), как и большинство утилит PostgreSQL, также использует переменные окружения поддерживаемые libpq.

Диагностика

pg_dump внутренне выполняет операторы SELECT. Если наблюдаются проблемы с запуском pg_dump, следует убедиться возможна ли выборка с базы данных, например, используя psql. Кроме того любые настройки соединения по умолчанию и переменные окружения использующие интерфейсные библиотеки будут применяться.
Активность базы данных обычно собрана сборщиком статистики. Если это нежелательно, то можно установить параметр track_counts в false через PGOPTIONS или командой ALTER USER.

Примечания

Если ваш кластер баз данных имеет любые локальные дополнения в базе данных template1, будьте осторожны при восстановлении вывода pg_dump в по-настоящему пустую базу данных; иначе вы вероятно получите ошибки из-за дублирования определений добавляемых объектов. Чтобы создать пустую базу данных без каких-либо локальных дополнений копируйте из template0, а не template1, например:
CREATE DATABASE foo WITH TEMPLATE template0;
Когда выбран дамп только данных и используется опция —disable-triggers, pg_dump издает команды отключения триггеров на таблицах пользователей перед вставкой данных, а затем их обратного включения после вставки данных. Если воспроизведение было остановлено посредине, то системные каталоги могут прийти в неправильное состояние.
Элементы tar-архива имеют ограничение в размене на меньше чем 8 GB. (Это свойственное ограничение для формата tar-файла.) Поэтому этот формат не может быть использован если текстовое представление какой-либо одной таблицы превышает этот размер. Общий размер tar-архива и любых других выходных форматов не ограничено за исключением, возможно, операционной системой.
Файл дампа, созданный с помощью pg_dump, не содержит статистики используемой оптимизатором для создания решений планируемых запросов. Поэтому после восстановления из файла дампа для обеспечения оптимальной производительности имеет смысл запускать ANALYZE. Файл дампа также не содержит какие-либо команды ALTER DATABASE … SET; эти настройки сбрасываются в дамп утилитой pg_dumpall наряду с базой данных пользователей и другими настройками всей инсталляции.
Поскольку pg_dump используется для передачи данных на новые версии PostgreSQL, вывод pg_dump можно предполагать для загрузки в сервер PostgreSQL новее версий, чем версия pg_dump. pg_dump также может создавать дамп из серверов PostgreSQL версии старше, чем собственная. (В настоящее время поддерживаются сервера обратно до 7.0.) Однако pg_dump не может создавать дамп из серверов PostgreSQL новее, чем собственная старшая версия; будет получен отказ даже попробовать, а не ставить под угрозу создание ошибочного дампа. Кроме того, это не гарантирует, что вывод pg_dump может быть загружен на сервер старше основной версии — нет, даже если дамп был взят с сервера этой версии. Загрузка файла дампа в более старый сервер может потребовать ручного редактирования файла дампа, для удаления синтаксиса не понятного более старому серверу.

Примеры

Создание дампа базы данных mydb в файл сценариев SQL:

pg_dump mydb > db.sql 

Загрузка такого скрипта в (новосозданную) базу данных с названием newdb:

psql -d newdb -f db.sql 

Создание дампа базы данных в архивный файл custom-формата:

pg_dump -Fc mydb > db.dump 

Создание дампа базы данных в архив directory-формата:

pg_dump -Fd mydb -f dumpdir 

Загрузка архивного файла в (новосозданную) базу данных с названием newdb:

pg_restore -d newdb 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

Смотрите также
pg_dumpall, pg_restore, psql

Эта статья является переводом соответствующей страницы официальной документации PostgreSQL 9.1 раздела VI «Reference» подраздела II «Клиентские приложения PostgreSQL».

Понравилась статья?
Подписаться на RSS feed
Один комментарий:
  1. Дмитри 25 апреля, 2013

    Спасибо за перевод для оказался крайне полезен.

Оставить комментарий