pg_restore
Название
pg_restore -- восстановить базу данных PostgreSQL из файла архива, созданного командой pg_dumpОписание
Утилита pg_restore предназначена для восстановления базы данных PostgreSQL из архива, созданного командой 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, удалить и пересоздать целевую базу данных перед подключением к ней.
С этим параметром база, заданная параметром -d, применяется только для подключения и выполнения начальных команд DROP DATABASE и CREATE DATABASE. Все данные восстанавливаются в базу данных, имя которой записано в архиве.
- -d база_данных
--dbname=база_данных Подключиться к базе данных имя_базы и восстановить данные непосредственно в неё.
- -e
--exit-on-error Завершать работу в случае возникновения ошибки при выполнении команд SQL в базе данных. По умолчанию процесс восстановления продолжается, а по его окончании выдаётся число ошибок.
- -f имя_файла
--file=имя_файла Задаёт файл для вывода сгенерированного скрипта или списка объектов, полученного с параметром -l. По умолчанию используется стандартный вывод.
- -F format
--format=format Задаёт формат архива. Указывать формат необязательно, так как pg_restore определяет формат автоматически. Но если формат задаётся, допускается один из этих вариантов:
- c
custom Архив сохранён в настраиваемом формате pg_dump.
- d
directory Архив сохранён в каталоге.
- t
tar Архив сохранён в формате tar.
- c
- -i
--ignore-version Устаревший флаг и сейчас игнорируется.
- -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, чтобы восстановить только определённую таблицу.
- -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 триггер
--trigger=триггер Восстановить только указанный триггер. Добавив дополнительные ключи -T, можно указать несколько триггеров.
- -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.
- --if-exists
При очистке целевой базы использовать условные команды (добавлять предложение IF EXISTS). Применяется только с параметром --clean.
- --no-data-for-failed-tables
По умолчанию данные восстанавливаются даже при ошибке команды создания таблицы (например, когда она уже существует). С этим параметром данные в таком случае не восстанавливаются. Это поведение полезно, если в целевой таблице уже содержатся нужные данные. Например, вспомогательные таблицы для расширений PostgreSQL (в частности, PostGIS) могут быть уже заполнены; этот параметр позволяет предотвратить дублирование или загрузку устаревших данных в эти таблицы.
Этот параметр действует только при восстановлении непосредственно в базу данных (не при генерации SQL-скрипта).
- --no-security-labels
Не выводить команды, восстанавливающие метки безопасности, даже если они содержатся в архиве.
- --no-tablespaces
Не формировать команды для указания табличных пространств. Все объекты будут создаваться в табличном пространстве по умолчанию.
- --section=имя секции
Восстановить только указанный раздел. В качестве имени раздела можно задать pre-data, data или post-data. Указав этот параметр неоднократно, можно выбрать несколько разделов. По умолчанию восстанавливаются все разделы.
Раздел «data» содержит собственно данные таблиц и определения больших объектов. В разделе «post-data» содержатся определения индексов, триггеров, правил и ограничений (кроме отдельно проверяемых). Раздел «pre-data» содержит все остальные определения.
- --use-set-session-authorization
Выводить команды SET SESSION AUTHORIZATION, соответствующие стандарту, вместо ALTER OWNER, для назначения владельцев объектов. В результате выгруженный скрипт будет более стандартизированным, но может не восстановиться корректно, в зависимости от истории объектов.
- -?
--help Показать справку по аргументам командной строки pg_restore и завершиться.
pg_restore также принимает в качестве параметров соединения следующие аргументы командной строки:
- -h host
--host=host Указывает имя компьютера, на котором запущен сервер. Если значение начинается с косой черты, оно интерпретируется как имя каталога с доменным сокетом Unix. Значение по умолчанию берётся из переменной окружения PGHOST, если она установлена. В противном случае выполняется подключение к доменному сокету.
- -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 Параметры подключения по умолчанию
Как и большинство других утилит PostgreSQL, эта утилита также использует переменные среды, поддерживаемые libpq (см. Раздел 31.14). Однако она не учитывает 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
| Пред. | Начало | След. |
| pg_recvlogical | Уровень выше | psql |