pg_restore

примечание

Эта страница переведена при помощи нейросети GigaChat.

Предупреждение!

В подразделе «Совместимость pg_restore» приведено описание совместимости утилиты при использовании различных версий клиентской и серверной частей СУБД Pangolin.

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

Синтаксис

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

Описание

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

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

Важно

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

Совместимость pg_restore

Утилита pg_restore позволяет восстановить резервную копию, снятую:

• в формате custom, при условии, что мажорная версия целевой СУБД не меньше мажорной версии СУБД, с которой получена резервная копия.
• в форматах tar/directory и с использованием утилиты pg_dump мажорной версии, не превышающую мажорную версию утилиты pg_restore на СУБД, чья мажорная версия соответствует мажорной версии утилиты pg_restore.

Внимание!

При восстановлении резервной копии утилитой pg_restore учитывайте не только совместимость утилит и версий СУБД, но и наличие необходимых объектов и атрибутов СУБД и БД:

• ролей и пользователей;
• ТП (табличных пространств);
• активных расширений и их версий, а также сторонних расширений из 3rdparty части;
• модулей процедурных языков (например, Pl/Perl);
• доступности внешних источников данных (FDW);
• правил pg_hba.conf;
• и других.

Параметры

Для утилиты pg_restore существуют следующие параметры командной строки:

filename

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

-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 может быть строкой подключения. В этом случае параметры строки подключения имеют приоритет над одноименными параметрами командной строки.

-e
--exit-on-error

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

-f file
--file=file

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

--filter=filename

Указывает имя файла, из которого следует читать шаблоны для исключаемых или включаемых объектов при восстановлении. Шаблоны интерпретируются согласно тем же правилам, что и -n/--schema для включения объектов в схемы, -N/--exclude-schema для исключения объектов из схем, -P/--function для восстановления именованных функций, -I/--index для восстановления именованных индексов, -t/--table для восстановления именованных таблиц или -T/--trigger для восстановления триггеров. Чтобы прочитать из STDIN, используйте - в качестве имени файла. Опцию --filter можно указать одновременно с перечисленными выше параметрами для включения или исключения объектов и более одного раза для нескольких файлов фильтров.

Файл содержит одну шаблонную строку для каждой базы данных, со следующим форматом: { include | exclude } { function | index | schema | table | trigger } PATTERN.

Первое ключевое слово указывает, должны ли объекты, соответствующие шаблону, быть включены или исключены. Второе ключевое слово определяет тип объекта, фильтруемый с использованием шаблона:

• function – функции, работает аналогично опции -P/--function. Это ключевое слово можно использовать только с ключевым словом include.
• index – индексы, работает аналогично опции -I/--indexes. Это ключевое слово можно использовать только с ключевым словом include.
• schema – схемы, работают аналогично опциям -n/--schema и -N/--exclude-schema.
• table – таблицы, работает аналогично опции -t/--table. Это ключевое слово можно использовать только с ключевым словом include.
• trigger – триггеры, работает аналогично опции -T/--trigger. Это ключевое слово можно использовать только с ключевым словом include.

Строки, начинающиеся с #, считаются комментариями и игнорируются. Комментарии могут располагаться после строки шаблона объекта. Пустые строки также игнорируются.

-F format
--format=format

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

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

d
directory : Архив в формате каталога.

t
tar : Архив в формате tar.

-I index
--index=index

Восстанавливает только указанный индекс. Параметр можно указать несколько раз для восстановления нескольких индексов.

-j njobs
--jobs=njobs

Выполняет наиболее длинные этапы восстановления параллельно (загрузку данных, создание индексов и ограничений), с использованием до njobs одновременных сессий. Это значительно сокращает общее время восстановления большой базы данных на сервере с многопроцессорной архитектурой. Параметр применяется только при прямом подключении к серверу базы данных, при выводе SQL-скрипта игнорируется.

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

Оптимальное значение этого параметра зависит от конфигурации сервера, клиента и сети. Учитываются, например, количество ядер процессора и организация хранения данных. В качестве ориентира можно начать с количества ядер процессора на сервере, однако иногда увеличение этого значения сверх количества ядер также приводит к ускорению восстановления. Слишком большое значение, напротив, может замедлить процесс из-за перегрузки ресурсов.

Параметр поддерживается только для архивов в форматах custom и directory. Входной файл должен быть обычным файлом или каталогом. Не совместимо с --single-transaction и не поддерживает ввод из канала или stdin.

-l
--list

Показывает оглавление архива. Результат можно использовать как входной файл для параметра -L. Применение параметров фильтрации -n или -t ограничивает вывод.

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

Восстанавливает только элементы, указанные в list-file, и в заданном порядке. list-file можно получить, отредактировав вывод -l. Поддерживаются комментарии (строки, начинающиеся с ;).

примечание

Если используются такие параметры фильтрации, как -n или -t с -L, они будут дополнительно ограничивать восстанавливаемые элементы.

-n schema
--schema=schema

Восстанавливает только объекты указанной схемы. Параметр можно указать несколько раз для восстановления нескольких схем. Можно комбинировать с -t для восстановления только определенной таблицы.

-N schema
--exclude-schema=schema

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

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

-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

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

Не путайте этот параметр с --schema, где слово «схема» в другом значении.

-S username
--superuser=username

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

-t table
--table=table

Восстанавливает определения и/или данные только для указанной таблицы. К таблицам относятся представления, материализованные представления, последовательности и внешние таблицы. Параметр можно указать несколько раз для восстановления нескольких таблиц. Его можно комбинировать с параметром -n для указания таблиц в определенной схеме.

Примечание

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

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

До версии PostgreSQL 9.6 параметр -t в pg_restore ограничивал только таблицы, а не другие типы отношений.

-T trigger
--trigger=trigger

Восстанавливает только указанный триггер. Параметр можно указать несколько раз для восстановления нескольких триггеров.

-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

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

Команды, генерируемые с параметром --disable-triggers, должны выполняются суперпользователем (нужно указать имя суперпользователя в параметре -S или выполнять скрипт от имени суперпользователя).

--enable-row-security

Включает защиту строк, применяется при восстановлении содержимого таблицы, которая имеет защиту строк.

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

Внимание!

В настоящий момент необходимо, чтобы данные были в формате INSERT (COPY FROM не поддерживает защиту строк).

--if-exists

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

--no-comments

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

--no-data-for-failed-tables

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

примечание

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

--no-publications

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

--no-security-labels

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

--no-subscriptions

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

--no-table-access-method

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

--no-tablespaces

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

--section=sectionname

Восстанавливает только указанный раздел. Параметр можно указать несколько раз для восстановления нескольких разделов. По умолчанию восстанавливаются все разделы.

Имя раздела может принимать значения:

• data содержит данные таблиц, больших объектов и значения последовательностей;
• pre-data содержит определения индексов, триггеров, правил и ограничений, кроме ограничений проверки, кроме проверенных;
• post-data содержит все остальные определения данных.

--strict-names

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

--transaction-size=N

Выполнять восстановление как серию транзакций, каждая из которых обрабатывает до N объектов базы данных. Этот параметр подразумевает --exit-on-error.

Параметр --transaction-size предлагает промежуточный вариант между поведением по умолчанию (одна транзакция на команду SQL) и -1/--single-transaction (одна транзакция для всех восстановленных объектов). Хотя --single-transaction имеет наименьшие накладные расходы, он может оказаться непрактичным для крупных баз данных, поскольку транзакция будет блокировать каждый объект восстановления, возможно исчерпав пространство блокировки сервера. Использование --transaction-size с размером нескольких тысяч объектов обеспечивает почти такую же производительность, ограничивая объем пространства блокировки, необходимого.

--use-set-session-authorization

Формирует команды SET SESSION AUTHORIZATION вместо команд ALTER OWNER для назначения владельцев объектов. Это делает выгрузку более стандартизированной, но может привести к некорректному восстановлению, если изменялась история владения объектами.

-?
--help

Показывает справку о параметрах командной строки утилиты pg_restore и завершается.

-h host
--host = host

Указывает хост компьютера, на котором запущен сервер. Значение по умолчанию берется из переменной окружения PGHOST. Если она не установлена, выполняется подключение к Unix-сокету (каталог Unix-сокета начинается с косой черты).

-p port
--port = port

Указывает TCP-порт или расширение файла локального Unix-сокета для подключения к серверу. Значение по умолчанию берется из переменной окружения PGPORT или задается при компиляции.

-U username
--username=username

Указывает имя пользователя для подключения.

-w
--no-password

Отключает запрос на ввод пароля. Если сервер требует аутентификации по паролю и пароль недоступен другими способами, такими как файл .pgpass, попытка подключения завершится неудачей. Параметр полезен в пакетных заданиях и сценариях, где нет пользователя, который мог бы ввести пароль.

-W
--password

Запрашивает пароль перед подключением к основному серверу.

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

--role=rolename

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

Переменные окружения

Утилита поддерживает переменные окружения:

• PGHOST
• PGOPTIONS
• PGPORT
• PGUSER
• PG_COLOR

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

Утилита не читает PGDATABASE при отсутствии имени базы данных.

Утилита pg_restore использует переменные окружения, поддерживаемые libpq.

Диагностика

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

Примечания

Если в установке база данных template1 содержит пользовательские дополнения, не восстанавливайте архив в базу данных, созданную на ее основе, если требуется «чистая» база. В противном случае возможно появление ошибок из-за дублирующихся определений объектов. Чтобы создать действительно пустую базу данных без пользовательских дополнений, используйте шаблон template0, например:

CREATE DATABASE foo WITH TEMPLATE template0;

Ограничения

При использовании pg_restore следует учитывать ряд важных ограничений, которые могут повлиять на корректность и полноту восстановления данных:

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

Подробную информацию об ограничениях архивации можно найти в документации по pg_dump.

После завершения восстановления рекомендуется запустить команду ANALYZE для всех восстановленных таблиц. Это позволит оптимизатору PostgreSQL собрать статистику и повысить эффективность выполнения запросов. Подробнее об этом смотрите в разделах «Обновление статистики планировщика» и «Демон Autovacuum».

Примеры

Выгрузка базы данных mydb в пользовательском формате:

$ pg_dump -Fc mydb > db.dump

Удаление базы данных mydb и ее восстановление из выгрузки:

$ 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

Файл 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

Восстановление из списка только элементов с идентификаторами 10 и 6, именно в указанном порядке:

$ pg_restore -L db.list db.dump

Смотрите также

pg_dump, pg_dumpall, psql