pg_restore#

pg_restore

pg_restore

pg_restore — восстановление базы данных Tantor SE-1С из архивного файла, созданного приложением pg_dump

Синтаксис

pg_restore [connection-option...] [option...] [filename]

Описание

pg_restore - это утилита для восстановления базы данных Tantor SE-1С из архива, созданного 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

Указывает местоположение файла архива (или каталога для архива в формате каталога), который будет восстановлен. Если не указано, используется стандартный ввод.

-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
--dbname=dbname

Подключитесь к базе данных dbname и восстановите данные непосредственно в базу данных. dbname может быть строкой подключения. Если это так, параметры строки подключения переопределят любые конфликтующие параметры командной строки.

-e
--exit-on-error

Выход, если произошла ошибка при отправке SQL-команд в базу данных. По умолчанию процесс будет продолжаться и будет отображено количество ошибок в конце восстановления.

-f filename
--file=filename

Укажите выходной файл для сгенерированного сценария или для списка, когда используется с -l. Используйте - для stdout.

-F format
--format=format

Укажите формат архива. Не обязательно указывать формат, так как pg_restore автоматически определит его. Если указан, он можно записать одним из следующих способов:

c
custom

Архив имеет пользовательский формат pg_dump.

d
directory

Архив - это архив каталога.

t
tar

Архив представляет собой архив tar.

-I index
--index=index

Сохранить только определение именованного индекса. Несколько индексов можно указать с помощью нескольких переключателей -I.

-j number-of-jobs
--jobs=number-of-jobs

Запустите самые трудоемкие шаги pg_restore — те, которые загружают данные, создают индексы или создают ограничения — одновременно, используя до number-of-jobs параллельных сессий. Этот параметр может значительно сократить время восстановления большой базы данных на сервере, работающем на многопроцессорной машине. Этот параметр игнорируется при создании скрипта, а не при подключении непосредственно к серверу базы данных.

Каждая задача представляет собой один процесс или один поток, в зависимости от операционной системы, и использует отдельное соединение с сервером.

Оптимальное значение для этой опции зависит от аппаратной конфигурации сервера, клиента и сети. Факторы включают количество ядер ЦП и настройку диска. Хорошим местом для начала является количество ядер ЦП на сервере, но значения, большие, чем это, также могут привести к более быстрым временам восстановления во многих случаях. Конечно, слишком высокие значения приведут к снижению производительности из-за трашинга.

Сохраняются только пользовательские и архивные форматы каталога с этой опцией. Ввод должен быть обычным файлом или каталогом (а не, например, каналом или стандартным вводом). Кроме того, нельзя использовать несколько заданий вместе с опцией --single-transaction.

-l
--list

Содержимое архива: Список содержимого архива. Результат этой операции может быть использован в качестве входных данных для опции -L. Обратите внимание, что если используются фильтрующие переключатели, такие как -n или -t с опцией -l, они ограничат перечисленные элементы.

-L list-file
--use-list=list-file

Восстановите только те элементы архива, которые перечислены в list-file, и восстановите их в порядке, в котором они появляются в файле. Обратите внимание, что если используются фильтрующие переключатели, такие как -n или -t с -L, они дополнительно ограничат восстанавливаемые элементы.

list-file обычно создается путем редактирования вывода предыдущей операции -l. Строки могут быть перемещены или удалены, а также могут быть закомментированы, поставив точку с запятой (;) в начале строки. См. примеры ниже.

-n schema
--schema=schema

Сохранить только объекты, которые находятся в указанной схеме. Можно указать несколько схем с помощью нескольких переключателей -n. Это можно совместить с опцией -t, чтобы восстановить только конкретную таблицу.

-N schema
--exclude-schema=schema

Не восстанавливайте объекты, которые находятся в указанной схеме. Несколько схем, которые нужно исключить, можно указать с помощью нескольких переключателей -N.

Когда оба -n и -N указаны для одного и того же имени схемы, выигрывает переключатель -N и схема исключается.

-O
--no-owner

Не выводите команды для установки владельца объектов, чтобы соответствовать исходной базе данных. По умолчанию pg_restore выполняет операторы ALTER OWNER или SET SESSION AUTHORIZATION для установки владельца созданных элементов схемы. Эти операторы не будут выполнены, если начальное подключение к базе данных осуществляется суперпользователем (или тем же пользователем, который владеет всеми объектами в скрипте). С помощью -O можно использовать любое имя пользователя для начального подключения, и этот пользователь будет владеть всеми созданными объектами.

-P function-name(argtype [, ...])
--function=function-name(argtype [, ...])

Восстановить только именованную функцию. Будьте внимательны при написании имени функции и аргументов точно так, как они указаны в таблице содержимого файла дампа. Можно указать несколько функций с помощью нескольких переключателей -P.

-R
--no-reconnect

Эта опция устарела, но все еще принимается для обратной совместимости.

-s
--schema-only

Восстановить только схему (определения данных), а не данные, в той степени, в которой записи схемы присутствуют в архиве.

Этот параметр является обратным для параметра --data-only. Он похож на, но по историческим причинам не идентичен, указанию --section=pre-data --section=post-data.

(Не путайте это с опцией --schema, которая использует слово схема в другом значении).

-S username
--superuser=username

Укажите имя пользователя суперпользователя, которое будет использоваться при отключении триггеров. Это актуально только в случае использования опции --disable-triggers.

-t table
--table=table

Сохранить определение и/или данные только для указанной таблицы. В этом случае таблица включает в себя представления, материализованные представления, последовательности и внешние таблицы. Несколько таблиц могут быть выбраны путем указания нескольких переключателей -t. Этот параметр может быть объединен с параметром -n для указания таблиц(ы) в определенной схеме.

Примечание

Когда указана опция -t, приложение pg_restore не пытается восстановить другие объекты базы данных, от которых могут зависеть выбранные таблицы. Поэтому нет гарантии, что восстановление конкретной таблицы в чистую базу данных будет успешным.

Примечание

Этот флаг не ведет себя идентично флагу -t у pg_dump. В настоящее время не предусмотрено возможности использования шаблонов в pg_restore, и нельзя указывать имя схемы в его -t. Кроме того, в то время как флаг -t у pg_dump также выполняет выгрузку дополнительных объектов (таких как индексы) выбранных таблиц, флаг -t у pg_restore не включает такие дополнительные объекты.

Примечание

В версиях до PostgreSQL 9.6 этот флаг соответствовал только таблицам, а не любому другому типу отношений.

-T trigger
--trigger=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 от имени суперпользователя Tantor SE-1С.

--enable-large-allocations

Увеличение допустимого размера загрузки ячейки таблицы до 2 ГБ для типов данных bytea и text. Этот аргумент активирует параметр конфигурации enable_large_allocations. Также включите этот параметр, когда pg_dump или pg_dumpall были вызваны с опцией --enable-large-allocations.

--enable-row-security

Этот параметр актуален только при восстановлении содержимого таблицы, у которой есть защита строк. По умолчанию, pg_restore устанавливает значение row_security в off, чтобы гарантировать, что все данные будут восстановлены в таблицу. Если у пользователя недостаточно привилегий для обхода защиты строк, то будет сгенерирована ошибка. Этот параметр указывает pg_restore установить значение row_security в on, позволяя пользователю попытаться восстановить содержимое таблицы с включенной защитой строк. Это все равно может завершиться неудачей, если у пользователя нет прав на вставку строк из дампа в таблицу.

Обратите внимание, что в настоящее время для этой опции также требуется, чтобы дамп был в формате INSERT, поскольку COPY FROM не поддерживает защиту строк.

--if-exists

Используйте команды DROP ... IF EXISTS для удаления объектов в режиме --clean. Это подавляет ошибки не существует, которые в противном случае могли бы быть сообщены. Этот параметр недействителен, если не указан также --clean.

--no-comments

Не выводить команды для восстановления комментариев, даже если они есть в архиве.

--no-data-for-failed-tables

По умолчанию, данные таблицы восстанавливаются даже если команда создания таблицы не удалась (например, потому что она уже существует). С этой опцией данные для такой таблицы пропускаются. Такое поведение полезно, если целевая база данных уже содержит нужное содержимое таблицы. Например, вспомогательные таблицы для расширений Tantor SE-1С, таких как PostGIS, могут уже быть загружены в целевую базу данных; указание этой опции предотвращает загрузку дублирующихся или устаревших данных в них.

Этот параметр действует только при восстановлении непосредственно в базу данных, а не при создании выходного SQL-скрипта.

--no-publications

Не выводить команды для восстановления публикаций, даже если они есть в архиве.

--no-security-labels

Не выводить команды для восстановления меток безопасности, даже если архив содержит их.

--no-subscriptions

Не выводить команды для восстановления подписок, даже если они есть в архиве.

--no-table-access-method

Не выводить команды для выбора методов доступа к таблицам. С этой опцией все объекты будут созданы с тем методом доступа, который является значением по умолчанию при восстановлении.

--no-tablespaces

Не выводить команды для выбора табличных пространств. С этой опцией все объекты будут созданы в табличном пространстве, который является по умолчанию во время восстановления.

--section=sectionname

Восстановить только указанный раздел. Имя раздела может быть pre-data, data или post-data. Эту опцию можно указать несколько раз, чтобы выбрать несколько разделов. По умолчанию восстанавливаются все разделы.

Секция данных содержит фактические данные таблицы, а также определения больших объектов. Пост-данные состоят из определений индексов, триггеров, правил и ограничений, кроме проверочных ограничений. Пред-данные состоят из всех остальных элементов определения данных.

--strict-names

Требуется, чтобы каждая схема (-n/--schema) и таблица (-t/--table) соответствовали хотя бы одной схеме/таблице в файле резервной копии.

--use-set-session-authorization

Выводите команды 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=rolename

Указывает имя роли, которое будет использоваться для выполнения восстановления. Эта опция заставляет pg_restore выполнять команду SET ROLE rolename после подключения к базе данных. Это полезно, когда аутентифицированный пользователь (указанный с помощью -U) не имеет привилегий, необходимых для pg_restore, но может переключиться на роль с требуемыми правами. Некоторые установки имеют политику против прямого входа в систему в качестве суперпользователя, и использование этой опции позволяет выполнять восстановление без нарушения политики.

Окружение

PGHOST
PGOPTIONS
PGPORT
PGUSER

Параметры подключения по умолчанию

PG_COLOR

Определяет, следует ли использовать цвет в диагностических сообщениях. Возможные значения: always, auto и never.

Эта утилита, как и большинство других утилит Tantor SE-1С, также использует переменные среды, поддерживаемые libpq (см. Раздел 31.15). Однако, она не считывает PGDATABASE, когда имя базы данных не указано.

Диагностика

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

Примечания

Если в вашей установке есть локальные дополнения к базе данных 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_dump, pg_dumpall, psql