1
августа
1

pg_restore



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

Синтаксис
pg_restore [connection-option…] [option…] [filename]

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

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

Очевидно, что pg_restore не может восстановить информацию, которая не присутствует в архивном файле. Для примера, если архив был сделан используя опцию «dump data as INSERT commands», то pg_restore не сможет загружать данные, используя команду COPY.

Опции
pg_restore принимает следующие аргументы командной строки.
filename
Задает местоположение архивного файла (или директории, для архива в directory-формате) для восстановления. Если не задано, то используется стандартный ввод.
-a
—data-only
Восстановить только данные, не схему (определения данных).
-c
—clean
Очистить (drop) объекты базы данных перед их созданием.
-C
—create
Создать базу данных перед восстановлением в нее. (Когда данная опция используется, база данных указанная с опцией -d используется только для выдачи начальной команды CREATE DATABASE. Все данные восстанавливаются в базу с именем присутствующим в архиве.)
-d dbname
—dbname=dbname
Подключиться к базе данных dbname и восстановить напрямую в базу.
-e
—exit-on-error
Выйти если произошла ошибка во время отправки SQL-команд в базу данных. По умолчанию будет продолжать выполняться и по окончанию восстановления выведет на экран подсчет ошибок.
-f filename
—file=filename
Задает выходной файл для генерации скрипта или списка, когда используется с -l.
По умолчанию это стандартный вывод.
-F format
—format=format
Задает формат архива. Указание формата не является необходимым, поскольку pg_restore будет автоматически определять формат.
c
custom
Архив в пользовательском формате утилиты pg_dump.
d
directory
Архив в формате директории.
t
tar
Архив в tar-формате.
-i
—ignore-version
Устаревшая опция, которая в настоящее время игнорируется.
-I index
—index=index
Восстановления определения только упомянутого индекса.
-j number-of-jobs
—jobs=number-of-jobs
Выполнить наиболее трудоемкие части pg_restore — те, которые подразумевают загрузку данных, создание индексов или ограничений — используя несколько параллельных рабочих процессов. Эта опция может значительно сократить время восстановления больших баз данных на сервер, работающий на многопроцессорной машине.
Каждая задача одного процесса или одного потока (в зависимости от операционной системы) использует отдельное подключение к серверу.
Оптимальное значение данной опции зависит от настройки оборудования сервера, клиента, а также сети.
В число факторов входит количество ядер процессора и конструкция диска. Хорошим значением для старта является количество ядер процессора на сервере, но большее значение в большинстве случаев также может привести к ускорению восстановления. Конечно же, слишком высокие значения будут приводить к снижению производительности из-за вздутия.
Эту опцию поддерживает только архив в custom-формате. Входной файл должен быть обычным файлом (к примеру, не pipe). Эта опция игнорируется при считывании файла сценария, а не прямом подключения к серверу баз данных. Также выполнение нескольких задач не может быть использовано вместе с опцией
—single-transaction.
-l
—list
Список содержимого архива. Вывод этой операции может быть использован как входные данные для опции -L. Следует заметить, что если фильтрация такими переключателями, как -n или -t, используется с -l, то они будут дополнительно ограничивать пункты в списке.
-L list-file
—use-list=list-file
Восстановить только элементы архива перечисленные в list-file в приведенном в файле порядке. Следует заметить, что если фильтрация такими переключателями, как -n или -t, используется с -L, то они будут дополнительно ограничивать пункты для восстановления.
list-file обычно создан редактированием вывода от предшествующей операции -l. Строки могут быть перенесены или удалены, а также могут быть закомментированы помещением точки с запятой (;) в начале строки. См. примеры ниже.
-n namespace
—schema=schema
Восстанавливать только объекты в вышеупомянутой схеме. При комбинировании с опцией -t восстанавливается только заданная таблица.
-O
—no-owner
Не включать в дамп команды задания принадлежности объектов, соответствующего оригинальной базе данных. По умолчанию pg_restore содержит предписание ALTER OWNER или SET SESSION AUTHORIZATION для установки принадлежности объектов созданных элементов схемы. Эти утверждения потерпят неудачу, когда инициализация подключения к базе данных выполняется суперпользователем (или некоторым пользователем, которому принадлежат все объекты в сценарие). Используя опцию -O любой пользователь может инициализировать подключение и он будет владеть всеми созданными объектами.
-P function-name(argtype [, …])
—function=function-name(argtype [, …])
Восстановить только функцию с заданным названием. Будьте осторожны, название функции и аргументы нужно вводить точно, как они выступают в содержании файла дампа таблицы.
-R
—no-reconnect
Эта опция устарела, но по-прежнему принимается для обеспечения обратной совместимости.
-s
—schema-only
Восстановить только схему (определения данных), не данные (содержимое таблиц). Текущая последовательность значений не будет восстановлена. (Не путайте это с опцией —schema, в которой используется слово «schema» в другом значении.)
-S username
—superuser=username
Задает имя суперпользователя для использования при отключении триггеров. Это имеет смысл только если используется —disable-triggers.
-t table
—table=table
Восстанавливать только определения и\или данные указанной таблицы. Это может быть комбинировано с опцией -n для указания схемы.
-T trigger
—trigger=trigger
Восстановить только указанный триггер.
-v
—verbose
Установить подробный режим.
-V
—version
Вывести версию pg_restore и завершить работу.
-x
—no-privileges
—no-acl
Не сохранять права доступа (команды grant/revoke).
-1
—single-transaction
Выполнить восстановление как отдельную транзакцию (то есть заключить внутрь команд BEGIN/COMMIT). Это дает гарантию, что либо все полностью команды выполняться успешно, либо никакие изменения не будут применены. Эта опция подразумевает —exit-on-error.
—disable-triggers
Эта опция имеет смысл лишь в случае восстановления только данных. Это заставляет pg_restore выполнять команды для временного отключения триггеров на целевых таблицах данные не будут загружены. Используете это, если есть проверки ссылочной целостности или другие триггеры на таблицы, которые вы не хотите вызывать во время загрузки данных.
В настоящее время выдаваемые команды для —disable-triggers должны быть выполнены от суперпользователя. Таким образом вы также должны задавать имя суперпользователя с -S или выполнять pg_restore, как суперпользователь PostgreSQL, что предпочтительнее.
—no-data-for-failed-tables
По умолчанию табличные данные восстанавливаются даже если команда создания таблицы завершилась неудачей (например, потому что она уже существует). С этой опцией данные для таких таблиц пропускаются. Это поведение полезно если целевая база данных уже содержит желаемое содержимое таблицы. Например, вспомогательные таблицы для расширений PostgreSQL, такие как PostGIS, уже могут быть загружены в целевую базу данных; установка этой опции предотвратит загрузку в них дублирующихся или устаревших данных.
Эта опция действует только при восстановлении непосредственно в базу данных, а не производящим SQL-скриптом выводом.
—no-security-labels
Не выводить команды восстановления меток безопасности даже если архив их содержит.
—no-tablespaces
Не выводить команды для выбора пространства таблиц. С помощью этой опции все объекты будут созданы в том пространстве таблиц, которое используется по умолчанию во время восстановления.
—use-set-session-authorization
Выдавать команду SQL-стандарта SET SESSION AUTHORIZATION вместо команды ALTER OWNER для определения принадлежности объектов. Это делает дамп более совместимым со стандартами, но в зависимости от истории объектов в дампе может не правильно восстановить.
-?
—help
Показать справку по аргументам командной строки pg_restore и выйти. pg_restore также принимает следующие опции командной строки управления параметрами подключения:
-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_restore принудительно выдает приглашение для ввода пароля перед подключением к базе данных.
Эта опция всегда несущественна, так как pg_restore будет автоматически выдавать запрос пароля если сервер требует аутентификации по паролю. Однако pg_restore будет делать излишнюю попытку подключения при обнаружении запроса сервером пароля. В некоторых случаях имеет смысл вводить -W чтобы избежать дополнительной попытки подключения.
—role=rolenam
Определяет какое имя роли использовать для выполнения восстановления. Эта опция заставляет pg_restore выдавать команду SET ROLE rolename после подключения к базе данных. Это полезно, когда аутентифицированный пользователь (задается опцией -U) не хватает привилегий необходимых pg_restore, но можно сменить на роль с требуемыми правами. Некоторые инсталляции имеют политику против входа в систему непосредственно в качестве суперпользователя и использование этой опции позволяет восстанавливать без нарушения политики.

Окружение

PGHOST
PGOPTIONS
PGPORT
PGUSER

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

Диагностика

При прямом подключении к базе данных, которое задается с помощью опции -d, pg_restore внутренне выполняет SQL-заявления. Если наблюдаются проблемы с работой pg_restore, следует убедиться возможна ли выборка с базы данных, например, используя psql. Кроме того любые настройки соединения по умолчанию и переменные окружения, использующие интерфейсные библиотеки, будут применяться.

Примечания

Если ваша инсталляция имеет любые локальные дополнения в базе данных template1, будьте осторожны при загрузке вывода pg_restore в действительно пустую базу данных; иначе вероятно вы получите ошибки из-за дублирования определений добавленных объектов. Чтобы создать пустую базу данных без каких-либо локальных дополнений копируйте из template0, а не template1, например:
CREATE DATABASE foo WITH TEMPLATE template0;

Ограничения pg_restore приведены ниже
— Когда восстанавливаются данные для уже существующей таблицы и используется опция —disable-triggers, то pg_restore выдает команды для отключения триггеров на пользовательские таблицы перед вставкой данных, затем выдает команды для их обратного включения после того как данные были вставлены. Если восстановление было остановлено посредине, то системные каталоги могут прийти в неправильное состояние.
— pg_restore не может выборочно восстанавливать большие объекты; например, только те, которые для определенной таблицы. Если архив содержит больше объекты, тогда все большие объекты будут восстановлены, либо ни один из них, если они исключены через -L, -t или другие опции.

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

Примеры

Предположим, что мы сбросили базу данных под названием mydb в дамп-файл в пользовательском формате:
$ pg_dump -Fc mydb > db.dump
Чтобы удалить базу данных и восстановить ее с дампа:
$ dropdb mydb
$ pg_restore -C -d postgres db.dump
База данных с именем возле -d может быть любая существующая в кластере база данных; pg_restore использует ее только чтобы выполнить команду CREATE DATABASE для mydb. С опцией -C данные всегда восстанавливаются в базу данных с именем указанным в дамп-файле.
Чтобы загрузить дамп в новую базу данных под названием newdb:
$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump
Следует заметить, что мы не используем -C, а вместо этого происходит непосредственное подключение к базе данных для восстановления. Также обратите внимание, что мы клонируем новую базу данных из template0, а не template1, чтобы гарантировано она была изначально пуста.
Чтобы изменить порядок элементов базы данных, сначала необходимо для этого сбросить в файл оглавление содержимого архива:
$ pg_restore -l db.dump > db.list
Файл листинга состоит из заголовка и одной линии для каждого элемента, например:
;
; Archive created at Mon Sep 14 13:55:39 2009
; dbname: DBDEMOS
; TOC Entries: 81
; Compression: 9
; Dump Version: 1.10-0
; Format: CUSTOM
; Integer: 4 bytes
; Offset: 8 bytes
; Dumped from database version: 8.3.5
; Dumped by pg_dump version: 8.3.8
;
;
; Selected TOC Entries:
;
3; 2615 2200 SCHEMA — public pasha
1861; 0 0 COMMENT — SCHEMA public pasha
1862; 0 0 ACL — public pasha
317; 1247 17715 TYPE public composite pasha
319; 1247 25899 DOMAIN public domain0 pasha
Точка с запятой служат началом комментария, а числа в начале линий относятся к внутренним ID архива, присвоенных каждому пункту.
Строки в файле могут быть закомментированы, удалены или размещены в другом порядке. Например:
10; 145433 TABLE map_resolutions postgres
;2; 145344 TABLE species postgres
;4; 145359 TABLE nt_header postgres
6; 145402 TABLE species_records postgres
;8; 145416 TABLE ss_old postgres
могут быть использованы как входные данные для pg_restore и будут восстановлены только пункты 10 и 6 в данном порядке:
$ pg_restore -L db.list db.dump

См. также
pg_dump, pg_dumpall, psql

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

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

    Недавно столкнулся с проблемой переноса данных в postgresql, как оказалось, сделать дамп и потом загрузку данных в PostgreSQL несколько сложнее, чем в MySQL. Рассмотрим как это сделать с помощью двух команд — pg_dump и pg_restore.

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