pg_restore

Contents

Синтаксис
Описание
Параметры
- Параметры восстановления
- Параметры подключения
Примечания
Примеры
См. также

Восстанавливает базу данных из файла архива, созданного командой pg_dump.

pg_restore [<connection-option> ...] [<restore_option> ...] [<filename>]

pg_restore -? | --help

pg_restore -V | --version

Описание

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

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

pg_restore не может восстановить информацию, которой нет в архивном файле. Например, если архив создан с использованием параметра "выгрузить данные в виде команд INSERT" (--inserts), pg_restore не сможет загрузить данные с помощью операторов COPY.

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

-a | --data-only: Восстанавливает только данные без схемы (определений объектов). Восстанавливаются данные таблиц и значения последовательностей, если они присутствуют в архиве.

Этот параметр аналогичен указанию --section=data, но по историческим причинам не полностью эквивалентен ему.
-c | --clean: Очищает (удаляет) объекты базы данных перед их созданием. Это может привести к появлению безвредных сообщений об ошибках, если каких-либо объектов не было в целевой базе данных.
-C | --create: Создает базу данных перед восстановлением в нее. Если также указан параметр --clean, целевая база данных удаляется и создается заново перед подключением к ней.

При использовании этого параметра база данных, указанная с помощью параметра -d, используется только для выполнения начальных команд DROP DATABASE и CREATE DATABASE. Все данные восстанавливаются в базу данных с именем, которое указано в архиве.
-d <dbname> | --dbname=<dbname>: Подключается к указанной базе данных и восстанавливает данные непосредственно в нее. Эта утилита, как и большинство других утилит Greengage DB, также использует переменные окружения, поддерживаемые libpq. Однако утилита не читает PGDATABASE, если имя базы данных не указано.
-e | --exit-on-error: Завершает работу при возникновении ошибки во время отправки SQL-команд в базу данных. По умолчанию утилита продолжает работу и выводит количество ошибок в конце процесса восстановления.
-f <outfilename> | --file=<outfilename>: Указывает выходной файл для генерируемого скрипта или для списка при использовании с параметром -l. По умолчанию используется стандартный вывод.
-F c|d|t | --format={custom | directory | tar}: Формат архива, созданного pg_dump. Указывать формат необязательно, так как pg_restore определит его автоматически. Формат может быть custom, directory или tar.
-I <index> | --index=<index>: Восстанавливает только определение указанного индекса.
-j <number-of-jobs> | --jobs=<number-of-jobs>: Выполняет наиболее длительные части pg_restore — те, которые загружают данные, создают индексы или создают ограничения — в нескольких параллельных заданиях. Этот параметр может значительно сократить время восстановления большой базы данных на сервере с многопроцессорной архитектурой.

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

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

С этим параметром поддерживается только специальный архивный формат. Входной файл должен быть обычным файлом (а не, например, конвейером). Этот параметр игнорируется при генерации скрипта вместо прямого подключения к серверу базы данных. Кроме того, несколько заданий нельзя использовать вместе с параметром --single-transaction.
-l | --list: Выводит список содержимого архива. Вывод этой операции можно использовать с параметром -L для ограничения и изменения порядка восстанавливаемых объектов.
-L <list-file> | --use-list=<list-file>: Восстанавливает только элементы из list-file в порядке их появления в файле. Обратите внимание, что если вместе с -L используются параметры фильтрации, такие как -n или -t, они дополнительно ограничат восстанавливаемые объекты.

list-file обычно создается путем редактирования вывода предыдущей операции -l. Строки можно перемещать или удалять, а также комментировать, помещая точку с запятой (;) в начале строки. См. примеры ниже.
-n <schema> | --schema=<schema>: Восстанавливает только объекты из указанной схемы. Можно комбинировать с параметром -t для восстановления только конкретной таблицы.
-O | --no-owner: Не выводит команды для установки владельца объектов в соответствии с исходной базой данных. По умолчанию pg_restore выполняет команды ALTER OWNER или SET SESSION AUTHORIZATION для установки владельца созданных элементов схемы. Эти команды завершатся ошибкой, если начальное подключение к базе данных не выполнено суперпользователем (или пользователем, владеющим всеми объектами в скрипте). При использовании -O для начального подключения можно использовать любое имя пользователя, и этот пользователь станет владельцем всех созданных объектов.
-P '<function-name>(<argtype> [, …])' | --function='<function-name>(<argtype> [, …])': Восстанавливает только указанную функцию. Имя функции должно быть заключено в кавычки. Убедитесь, что имя функции и аргументы указаны точно так же, как они указаны в оглавлении файла выгрузки (как показывает параметр --list).
-s | --schema-only: Восстанавливает только определения объектов схемы, без восстановления данных, если такие определения присутствуют в архиве.

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

Не путать с параметром --schema, который использует "схема" в другом значении.
-S <username> | --superuser=<username>: Указывает имя суперпользователя для использования при деактивации триггеров. Актуально только при использовании --disable-triggers.

ПРИМЕЧАНИЕ

Greengage DB не поддерживает пользовательские триггеры.
-t <table> | --table=<table>: Восстанавливает только определение и/или данные указанной таблицы. Можно указать несколько таблиц, используя несколько параметров -t. Можно комбинировать с параметром -n для указания схемы.
-T <trigger> | --trigger=<trigger>: Восстанавливает только указанный триггер.

ПРИМЕЧАНИЕ

Greengage DB не поддерживает пользовательские триггеры.
-v | --verbose: Включает подробный вывод.
-V | --version: Выводит версию pg_restore и завершает работу.
-x | --no-privileges | --no-acl: Не восстанавливает привилегии доступа (команды GRANT/REVOKE).
-1 | --single-transaction: Выполняет восстановление как одну транзакцию. Это гарантирует, что либо все команды будут успешно выполнены, либо никакие изменения не будут применены.
--disable-triggers: Этот параметр актуален только при восстановлении только данных. Он указывает pg_restore выполнить команды для временной деактивации триггеров в целевых таблицах во время перезагрузки данных. Используйте этот параметр, если в таблицах есть триггеры, которые не должны срабатывать во время загрузки данных. Команды для --disable-triggers должны выполняться от имени суперпользователя. Поэтому следует также указать имя суперпользователя с -S или, что предпочтительнее, запустить pg_restore от имени суперпользователя.

ПРИМЕЧАНИЕ

Greengage DB не поддерживает пользовательские триггеры.
--if-exists: Добавляет выражение IF EXISTS к командам удаления объектов базы данных. Применяется только вместе с параметром --clean.
--no-data-for-failed-tables: По умолчанию данные таблицы восстанавливаются, даже если команда создания таблицы завершилась ошибкой (например, потому что она уже существует). С этим параметром данные для такой таблицы пропускаются. Это поведение полезно, если в целевой таблице уже содержатся нужные данные. Указание этого параметра предотвращает загрузку дублирующихся или устаревших данных. Этот параметр эффективен только при восстановлении непосредственно в базу данных, а не при генерации SQL-скрипта.
--no-security-labels: Не выводит команды для восстановления меток безопасности, даже если архив содержит их.
--no-tablespaces: Не выводит команды для выбора табличных пространств. С этим параметром все объекты будут созданы в том табличном пространстве, которое используется по умолчанию во время восстановления.
--section=<sectionname>: Восстанавливает только указанную секцию. Имя секции может быть pre-data, data или post-data. Этот параметр можно указать несколько раз для выбора нескольких секций.

По умолчанию восстанавливаются все секции.
--use-set-session-authorization: Выводит команды SQL-стандарта SET SESSION AUTHORIZATION вместо команд ALTER OWNER для определения владельца объектов. Это делает выгрузку более совместимой со стандартами, но в зависимости от истории объектов в выгрузке она может быть восстановлена некорректно.
-? | --help: Отображает справку по аргументам командной строки pg_restore и завершает работу.

-h <host> | --host=<host>: Имя хоста, на котором работает мастер Greengage DB. Если параметр не указан, читается из переменной окружения PGHOST; по умолчанию используется localhost.
-p <port> | --port=<port>: TCP-порт, на котором мастер Greengage DB прослушивает подключения. Если параметр не указан, читается из переменной окружения PGPORT; по умолчанию используется порт 5432.
-U <username> | --username=<username>: Имя роли базы данных для подключения. Если параметр не указан, читается из переменной окружения PGUSER; по умолчанию используется имя текущей системной роли.
-w | --no-password: Никогда не запрашивает пароль. Если сервер требует аутентификацию по паролю, а пароль недоступен другими способами (например, через файл .pgpass), попытка подключения завершится неудачей. Этот параметр удобен для пакетных заданий и скриптов, где нет пользователя для ввода пароля.
-W | --password: Принудительно запрашивает пароль.
--role=<rolename>: Указывает роль, которая будет использоваться для выполнения восстановления. После подключения к базе данных pg_restore выполнит команду SET ROLE rolename. Это полезно, когда аутентифицированному пользователю (через -U) не хватает прав, необходимых pg_restore, но он может переключиться на роль с нужными привилегиями. Некоторые инсталляции ограничивают прямой вход от имени суперпользователя; использование этого параметра позволяет выполнять восстановление, соблюдая политику безопасности.

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

CREATE DATABASE foo WITH TEMPLATE template0;

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

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

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

Предположим, что база данных с именем mydb выгружена в файл специального формата:

$ pg_dump -Fc mydb > db.dump

Чтобы удалить базу данных и создать ее заново из выгрузки, выполните:

$ dropdb mydb
$ pg_restore -C -d template1 db.dump

Приведенные ниже команды загружают выгрузку в новую базу данных с именем newdb. Обратите внимание, что параметр -C не указан, поэтому подключение выполняется напрямую к базе данных, в которую будет производиться восстановление. Также обратите внимание, что новая база данных создается на основе template0, а не template1, чтобы она была изначально пустой:

$ createdb -T template0 newdb
$ pg_restore -d newdb db.dump

Чтобы изменить порядок элементов базы данных, сначала необходимо выгрузить оглавление архива:

$ pg_restore -l db.dump > db.list

Файл списка состоит из заголовка и одной строки для каждого элемента, например:

; Archive created at Mon Dec 22 13:46:32 2025
;     dbname: mydb
;     TOC Entries: 9
;     Compression: -1
;     Dump Version: 1.13-0
;     Format: CUSTOM
;     Integer: 4 bytes
;     Offset: 8 bytes
;     Dumped from database version: 9.4.26
;     Dumped by pg_dump version: 9.4.26
;
;
; Selected TOC Entries:
;
2433; 1262 16384 DATABASE - mydb 10
6; 2615 2200 SCHEMA - public gpadmin
2434; 0 0 COMMENT - SCHEMA public gpadmin
2435; 0 0 ACL - SCHEMA public gpadmin
1; 3079 12331 EXTENSION - plpgsql
2436; 0 0 COMMENT - EXTENSION plpgsql

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

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

pgbouncer

pg_restore

Синтаксис

Описание

Параметры

Параметры восстановления

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

Примечания

Примеры

См. также