pg_restore

pg_restore — 从pg_dump创建的归档文件中还原PostgreSQL数据库

语法

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

描述

pg_restore是一个用于从pg_dump以非纯文本格式创建的存档中还原PostgreSQL数据库的实用程序。它将发出必要的命令，以将数据库重建为保存时所处状态。存档文件还允许pg_restore选择性地还原内容，甚至在还原之前重新排序项目。存档文件被设计为跨体系结构可移植。

pg_restore可以以两种模式运行。如果指定了数据库名称，pg_restore将连接到该数据库并将存档内容直接还原到数据库中。否则，将创建一个包含重建数据库所需的 SQL 命令的脚本，并将其写入文件或标准输出。此脚本输出等效于pg_dump的纯文本输出格式。因此，控制输出的一些选项类似于pg_dump选项。

显然，pg_restore无法还原存档文件中不存在的信息。例如，如果使用“以INSERT命令转储数据”选项创建存档，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 个并发会话。此选项可以显著减少将大型数据库恢复到在多处理器机器上运行的服务器上的时间。当发出脚本而不是直接连接到数据库服务器时，此选项将被忽略。

每个作业是一个进程或一个线程，具体取决于操作系统，并使用一个单独的连接到服务器。

此选项的最佳值取决于服务器、客户端和网络的硬件设置。因素包括 CPU 内核数和磁盘设置。一个好的起点是服务器上的 CPU 内核数，但在许多情况下，大于该值的值也可以带来更快的恢复时间。当然，过高的值会导致性能下降，因为会发生抖动。

此选项仅支持自定义和目录存档格式。输入必须是常规文件或目录（例如，不是管道或标准输入）。此外，多个作业不能与选项 --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 用户名
--superuser=用户名

禁用触发器时，指定要使用的超级用户用户名。仅当使用 --disable-triggers 时，此选项才相关。

-t 表
--table=表

仅恢复指定表的定义和/或数据。为此，“表” 包括视图、物化视图、序列和外部表。可以通过编写多个 -t 开关来选择多个表。此选项可以与 -n 选项结合使用，以指定特定架构中的表。

注意

当指定 -t 时，pg_restore 不会尝试恢复所选表可能依赖的任何其他数据库对象。因此，无法保证将特定表恢复到干净的数据库中会成功。

注意

此标志的行为与 pg_dump 的 -t 标志的行为不完全相同。目前 pg_restore 中没有通配符匹配的规定，您也不能在其 -t 中包含架构名称。而且，虽然 pg_dump 的 -t 标志还将转储所选表的辅助对象（例如索引），但 pg_restore 的 -t 标志不包括此类辅助对象。

注意

在 PostgreSQL 9.6 之前的版本中，此标志仅匹配表，而不匹配任何其他类型的关联。

-T 触发器
--trigger=触发器

仅还原指定名称的触发器。可以使用多个 -T 开关指定多个触发器。

-v
--verbose

指定详细模式。这将导致 pg_restore 将详细的对象注释和开始/停止时间输出到输出文件，并将进度消息输出到标准错误。重复此选项会导致标准错误中出现其他调试级别消息。

-V
--version

打印 pg_restore 版本并退出。

-x
--no-privileges
--no-acl

禁止还原访问权限（授予/撤销命令）。

-1
--single-transaction

将还原作为单个事务执行（即，用 BEGIN/COMMIT 将发出的命令包装起来）。这可确保所有命令都成功完成，或不应用任何更改。此选项暗示 --exit-on-error。

--disable-triggers

此选项仅在执行仅数据还原时相关。它指示 pg_restore 执行命令以在还原数据时暂时禁用目标表上的触发器。如果您在表上具有引用完整性检查或其他触发器，并且您不希望在数据还原期间调用这些触发器，请使用此选项。

目前，为 --disable-triggers 发出的命令必须作为超级用户执行。因此，您还应该使用 -S 指定超级用户名，或者最好以 PostgreSQL 超级用户的身份运行 pg_restore。

--enable-row-security

此选项仅在还原具有行安全性的表的表内容时相关。默认情况下，pg_restore 会将 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

仅还原命名的部分。部分名称可以是 pre-data、data 或 post-data。可以多次指定此选项以选择多个部分。默认情况下，还原所有部分。

数据部分包含实际的表数据以及大对象定义。后数据项由索引、触发器、规则和除已验证检查约束之外的约束的定义组成。前数据项由所有其他数据定义项组成。

--strict-names

要求每个架构 (-n/--schema) 和表 (-t/--table) 限定符至少与备份文件中的一个架构/表匹配。

--use-set-session-authorization

输出 SQL 标准 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。

此实用程序与大多数其他PostgreSQL实用程序一样，还使用libpq支持的环境变量（请参见第 34.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，以便优化器拥有有用的统计信息；请参阅第 25.1.3 节和第 25.1.6 节了解更多信息。

示例

假设我们已将名为mydb的数据库转储到自定义格式的转储文件中

$ pg_dump -Fc mydb > db.dump

若要删除数据库并从转储中重新创建它

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

在-d开关中命名的数据库可以是群集中存在的任何数据库；pg_restore仅使用它为mydb发出CREATE DATABASE命令。使用-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

分号开头为注释，行首的数字引用分配给每个项目的内部存档 ID。

文件中的行可以注释掉、删除和重新排序。例如

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