pg_restore
pg_restore — восстановить базу данных Postgres Pro из файла архива, созданного командой pg_dump
Синтаксис
pg_restore
[параметр-подключения
...] [параметр
...] [имя_файла
]
Описание
Утилита pg_restore предназначена для восстановления базы данных Postgres Pro из архива, созданного командой pg_dump в любом из не текстовых форматов. Она выполняет команды, необходимые для восстановления того состояния базы данных, в котором база была сохранена. При наличии файлов архивов, pg_restore может восстанавливать данные избирательно или даже переупорядочить объекты перед восстановлением. Заметьте, что разработанный для файлов архива формат не привязан к архитектуре.
Утилита pg_restore может работать в двух режимах. Если указывается имя базы данных, pg_restore подключается к этой базе данных и восстанавливает содержимое архива непосредственно в неё. В противном случае создаётся SQL-скрипт с командами, необходимыми для пересоздания базы данных, который затем выводится в файл или в стандартное устройство вывода. Сформированный скрипт будет в точности соответствовать выводу pg_dump в простом текстовом формате. Поэтому некоторые из параметров, управляющих выводом, аналогичны параметрам pg_dump.
Разумеется, pg_restore может восстановить информацию, только если она присутствует в файле архива, и только в существующем виде. Например, если архив был создан с указанием «выгрузить данные в виде команд INSERT
», pg_restore не сможет загрузить эти данные, используя операторы COPY
.
Параметры
Утилита pg_restore принимает следующие аргументы командной строки.
имя_файла
Указывает расположение восстанавливаемого файла архива (или каталога, для архива в формате каталога). По умолчанию используется устройство стандартного ввода.
-a
--data-only
Восстанавливать только данные, без схемы (определений данных). При этом восстанавливаются данные таблиц, большие объекты и значения последовательностей, имеющиеся в архиве.
Флаг похож на
--section=data
, но по историческим причинам не равнозначен ему.-c
--clean
Прежде чем восстанавливать объекты базы данных, выполните команды
DROP
для всех восстанавливаемых объектов. Этот параметр полезен для перезаписи существующей базы данных. Без дополнительного указания--if-exists
при этом могут выдаваться безвредные сообщения об ошибках, если таких объектов не окажется в целевой базе данных.-C
--create
Создать базу данных, прежде чем восстанавливать данные. Если также указан параметр
--clean
, удалить и пересоздать целевую базу данных перед подключением к ней.С ключом
--create
программа pg_restore также восстанавливает комментарий к базе данных (если он задан) и все назначения переменных конфигурации, связанные с базой данных, то есть все командыALTER DATABASE ... SET ...
иALTER ROLE ... IN DATABASE ... SET ...
, ссылающиеся на эту базу данных. Также восстанавливаются права доступа к самой базе данных, если не добавлен ключ--no-acl
.С этим параметром база, заданная параметром
-d
, применяется только для подключения и выполнения начальных командDROP DATABASE
иCREATE DATABASE
. Все данные восстанавливаются в базу данных, имя которой записано в архиве.-d
имя_бд
--dbname=
имя_бд
Подключиться к базе данных
имя_базы
и восстановить данные непосредственно в неё. В данном аргументе может задаваться строка подключения. В этом случае параметры в строке подключения переопределяют одноимённые параметры, заданные в командной строке.-e
--exit-on-error
Завершать работу в случае возникновения ошибки при выполнении команд SQL в базе данных. По умолчанию процесс восстановления продолжается, а по его окончании выдаётся число ошибок.
-f
имя_файла
--file=
имя_файла
Задаёт файл для вывода сгенерированного скрипта или списка объектов, получаемого с параметром
-l
. Чтобы выбрать stdout, используйте-
.-F
формат
--format=
формат
Задаёт формат архива. Указывать формат необязательно, так как pg_restore определяет формат автоматически. Но если формат задаётся, допускается один из этих вариантов:
c
custom
Архив сохранён в специальном формате pg_dump.
d
directory
Архив сохранён в каталоге.
t
tar
Архив сохранён в формате
tar
.
-I
индекс
--index=
индекс
Восстановить определение только заданного индекса. Добавив дополнительные ключи
-I
, можно указать несколько индексов.-j
число-заданий
--jobs=
число-заданий
Выполнять наиболее длительные этапы pg_restore (в частности, загрузку данных, создание индексов или ограничений) параллельно, используя несколько заданий (в количестве, не превышающем
число-заданий
). Это позволяет кардинально сократить время восстановления большой базы данных, когда сервер работает на многопроцессорном компьютере. Данный параметр игнорируется, когда генерируется скрипт (нет прямого подключения к базе данных).Каждое задание выполняется в отдельном задании или потоке, в зависимости от операционной системы, и использует отдельное подключение к серверу.
Оптимальное значение этого параметра зависит от аппаратной конфигурации сервера, клиента и сети. В частности, имеет значение количество процессорных ядер и устройство дискового хранилища. В качестве начального значения можно выбрать число ядер на сервере, но и при увеличении этого значения во многих случаях восстановление будет быстрее. Конечно, при слишком больших значениях производительность упадёт из-за перегрузки.
Этот параметр поддерживается только с архивом в специальном формате или в каталоге. Входные данные должны поступать из обычного файла или каталога, а не из канала или стандартного устройства ввода. Кроме того, несколько заданий не могут выполняться в сочетании с параметром
--single-transaction
.-l
--list
Вывести оглавление архива. Вывод этой операции можно подать на вход этой же команде с параметром
-L
. Учтите, что когда вместе с-l
применяются параметры фильтрации (например,-n
или-t
), они сокращают список выводимых объектов.-L
файл-список
--use-list=
файл-список
Восстановить из архива только элементы, перечисленные в
файле-списке
, и в том порядке, в каком они идут в этом файле. Заметьте, что когда вместе с-L
применяются параметры фильтрации (например,-n
или-t
), они дополнительно ограничивают восстанавливаемые объекты.Данный
файл-список
обычно представляет собой отредактированный результат предыдущей операции-l
. Строки в нём могут быть переставлены или удалены, а также могут быть закомментированы точкой с запятой (;
), добавленной в начале строки. См. примеры ниже.-n
схема
--schema=
схема
Восстановить только объекты в указанной схеме. Добавив дополнительные ключи
-n
, можно указать несколько схем. Этот параметр можно сочетать с-t
, чтобы восстановить только определённую таблицу.-N
схема
--exclude-schema=
схема
Не восстанавливать объекты в указанной схеме. Добавив дополнительные ключи
-N
, можно исключить несколько схем.Когда и с ключом
-n
, и с ключом-N
передаётся имя одной схемы, ключ-N
выигрывает и схема исключается.-O
--no-owner
Не генерировать команды, устанавливающие владение объектами, как в исходной базе данных. По умолчанию, pg_restore генерирует команды
ALTER OWNER
илиSET SESSION AUTHORIZATION
, восстанавливающие исходных владельцев создаваемых элементов схемы. Однако эти команды можно будет выполнить, только если к базе данных первоначально подключается суперпользователь (или пользователь, владеющими всеми объектами в скрипте). Чтобы получить скрипт, который сможет восстановить любой подключающийся пользователь (но при этом он станет владельцем всех созданных объектов), используется-O
.-P
имя-функции(тип-аргумента[, ...])
--function=
имя-функции(тип-аргумента[, ...])
Восстановить только указанную функцию. При этом важно записать имя функции и аргументы в точности так, как они фигурируют в оглавлении файла архива. Добавив дополнительные ключи
-P
, можно указать несколько функций.-R
--no-reconnect
Параметр является устаревшим, но в целях совместимости ещё работает.
-s
--schema-only
Восстановить только схему (определения данных), без данных, в объёме, в котором элементы схемы представлены в архиве.
Действие параметра противоположно действию
--data-only
. Это похоже на указание--section=pre-data --section=post-data
, но по историческим причинам не равнозначно ему.(Не путайте этот параметр с
--schema
, где слово «схема» используется в другом значении.)-S
имя_пользователя
--superuser=
имя_пользователя
Задаёт имя суперпользователя, полномочия которого будут использоваться для отключения триггеров. Этот параметр применяется только с параметром
--disable-triggers
.-t
таблица
--table=
таблица
Восстановить определение и/или данные только указанной таблицы. В этом контексте под «таблицей» подразумеваются также представления, материализованные представления, последовательности и сторонние таблицы. Чтобы выбрать несколько таблиц, ключ
-t
можно указать несколько раз. Этот параметр можно скомбинировать с-n
, чтобы выбрать таблицу(ы) в определённой схеме.Примечание
Когда указывается
-t
, pg_restore не пытается восстанавливать объекты базы данных, от которых могут зависеть выбранные таблицы. Таким образом, в этом случае не гарантируется, что выгруженные таблицы будут успешно восстановлены в чистой базе данных.Примечание
Этот флаг действует не совсем так, как флаг
-t
утилиты pg_dump. В настоящее время pg_restore не поддерживает выбор объектов по маске, а также не позволяет указать имя схемы с-t
. И хотя pg_dump с флагом-t
также выгружает подчинённые объекты (например, индексы) выбранных таблиц, pg_restore с флагом-t
такие подчинённые объекты не обрабатывает.Примечание
В версиях Postgres Pro до 9.6 этот флаг выбирал только таблицы, но не другие типы отношений.
-T
триггер
--trigger=
триггер
Восстановить только указанный триггер. Добавив дополнительные ключи
-T
, можно указать несколько триггеров.-v
--verbose
Включить подробный режим. pg_restore будет выводить в стандартный поток ошибок подробные комментарии к объектам, включая время начала и окончания операции, а также сообщения о прогрессе выполнения. Если повторить этот ключ, в стандартный поток ошибок будут выдаваться дополнительные отладочные сообщения.
-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 от имени суперпользователя Postgres Pro.--enable-row-security
Этот параметр имеет смысл только при восстановлении содержимого таблицы, для которой включена защита строк. По умолчанию pg_restore устанавливает для row_security значение off для уверенности, что в таблице восстановлены все данные. Если у пользователя недостаточно прав для обхода защиты строк, выдаётся ошибка. Этот параметр указывает pg_restore установить в row_security значение on, чтобы пользователь мог попытаться восстановить содержимое таблицы с включённой защитой строк. Однако и при этом возможна ошибка, если пользователь не будет иметь права добавлять в эту таблицу выгруженные строки данных.
Заметьте, что в настоящее время для этого требуется, чтобы выгрузка выполнялась в режиме
INSERT
, так какCOPY FROM
не поддерживает защиту строк.--if-exists
Используйте команды
DROP ... IF EXISTS
для удаления объектов в режиме--clean
. При этом возможные ошибки «does not exist» (не существует) не выводятся. Этот параметр недействителен без указания--clean
.--no-comments
Не выводить команды, восстанавливающие комментарии, даже если они содержатся в архиве.
--no-data-for-failed-tables
По умолчанию данные восстанавливаются даже при ошибке команды создания таблицы (например, когда она уже существует). С этим параметром данные в таком случае не восстанавливаются. Это поведение полезно, если в целевой таблице уже содержатся нужные данные. Например, вспомогательные таблицы для расширений Postgres Pro (в частности, PostGIS) могут быть уже заполнены; этот параметр позволяет предотвратить дублирование или загрузку устаревших данных в эти таблицы.
Этот параметр действует только при восстановлении непосредственно в базу данных (не при генерации SQL-скрипта).
--no-publications
Не выводить команды, восстанавливающие публикации, даже если они содержатся в архиве.
--no-security-labels
Не выводить команды, восстанавливающие метки безопасности, даже если они содержатся в архиве.
--no-subscriptions
Не выводить команды, восстанавливающие подписки, даже если они содержатся в архиве.
--no-tablespaces
Не формировать команды для указания табличных пространств. При восстановлении все объекты будут создаваться в табличном пространстве по умолчанию.
--section=
имя секции
Восстановить только указанный раздел. В качестве имени раздела можно задать
pre-data
,data
илиpost-data
. Указав этот параметр неоднократно, можно выбрать несколько разделов. По умолчанию восстанавливаются все разделы.Раздел «data» содержит собственно данные таблиц и определения больших объектов. В разделе «post-data» содержатся определения индексов, триггеров, правил и ограничений (кроме отдельно проверяемых). Раздел «pre-data» содержит все остальные определения.
--strict-names
Требует, чтобы каждому указанию схемы (
-n
/--schema
) и таблицы (-t
/--table
) соответствовала минимум одна схема/таблица в файле резервной копии.--use-set-session-authorization
Выводить команды
SET SESSION AUTHORIZATION
, соответствующие стандарту, вместоALTER OWNER
, для назначения владельцев объектов. В результате выгруженный скрипт будет более стандартизированным, но может не восстановиться корректно, в зависимости от истории объектов.-?
--help
Показать справку по аргументам командной строки pg_restore и завершиться.
pg_restore также принимает в качестве параметров соединения следующие аргументы командной строки:
-h
сервер
--host=
сервер
Указывает имя компьютера, на котором работает сервер. Если значение начинается с косой черты, оно определяет каталог Unix-сокета. Значение по умолчанию берётся из переменной окружения
PGHOST
, если она установлена. В противном случае выполняется подключение к Unix-сокету.-p
порт
--port=
порт
Указывает TCP-порт или расширение файла локального Unix-сокета, через который сервер принимает подключения. Значение по умолчанию определяется переменной окружения
PGPORT
, если она установлена, либо числом, заданным при компиляции.-U
имя_пользователя
--username=
имя_пользователя
Имя пользователя, под которым производится подключение.
-w
--no-password
Не выдавать запрос на ввод пароля. Если сервер требует аутентификацию по паролю и пароль не доступен с помощью других средств, таких как файл
.pgpass
, попытка соединения не удастся. Этот параметр может быть полезен в пакетных заданиях и скриптах, где нет пользователя, который вводит пароль.-W
--password
Принудительно запрашивать пароль перед подключением к базе данных.
Это несущественный параметр, так как pg_restore запрашивает пароль автоматически, если сервер проверяет подлинность по паролю. Однако чтобы понять это, pg_restore лишний раз подключается к серверу. Поэтому иногда имеет смысл ввести
-W
, чтобы исключить эту ненужную попытку подключения.--role=
имя роли
Задаёт имя роли, которая будет осуществлять восстановление. Получив это имя, pg_restore выполнит
SET ROLE
имя_роли
после подключения к базе данных. Это полезно, когда проходящий проверку пользователь (указанный в-U
) не имеет прав, необходимых для pg_restore, но может переключиться на роль, наделённую этими правами. В некоторых окружениях правила запрещают подключаться к серверу непосредственно суперпользователю, и этот параметр позволяет выполнить восстановление, не нарушая их.
Переменные окружения
PGHOST
PGOPTIONS
PGPORT
PGUSER
Параметры подключения по умолчанию
PG_COLOR
Выбирает вариант использования цвета в диагностических сообщениях. Возможные значения:
always
(всегда),auto
(автоматически) иnever
(никогда).
Как и большинство других утилит Postgres Pro, эта утилита также использует переменные среды, поддерживаемые libpq (см. Раздел 32.15). Однако она не учитывает PGDATABASE
, когда имя базы не указано.
Диагностика
Когда с параметром -d
устанавливается прямое подключение к базе данных, pg_restore выполняет обычные операторы SQL. При этом применяются все свойства подключения по умолчанию и переменные окружения, которые использует клиентская библиотека libpq. Если вы сталкиваетесь с проблемами при запуске 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
для каждой восстановленной таблицы, чтобы оптимизатор получил актуальную статистику; за дополнительными сведениями обратитесь к Подразделу 23.1.3 и Подразделу 23.1.6.
Примеры
Предположим, что мы выгрузили базу данных 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
С точки с запятой начинаются комментарии, а число в начале строки обозначает внутренний идентификатор, назначаемый каждому элементу в архиве.
Строки в этом файле можно закомментировать, удалить или переместить. Например, список:
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