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 会自动确定格式。如果指定，可以是以下格式之一：
ccustom归档采用 pg_dump 的自定义格式。
ddirectory归档是目录格式归档。
ttar归档是 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列出归档的目录内容（table of contents）。此操作的输出可用作 -L 选项的输入。 请注意，如果在 -l 中使用 -n 或 -t 等过滤开关，它们会限制被列出的项目。
-L list-file--use-list=list-file仅恢复在 list-file 中列出的归档元素， 并按它们在文件中出现的顺序进行恢复。请注意，如果在 -L 中使用 -n 或 -t 等过滤开关，它们还会进一步限制被恢复的项目。
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 选项混淆，那里 “schema” 一词的含义不同。）
-S username--superuser=username指定在禁用触发器时要使用的超级用户用户名。仅当使用 --disable-triggers 时才相关。
-t table--table=table仅恢复指定表的定义和/或数据。这里的 “table” 包括视图、物化视图、 序列和外部表。可以通过多次指定 -t 来选择多个表。 此选项可以与 -n 选项结合使用，以指定特定模式中的表。
当指定 -t 时，pg_restore 不会尝试恢复所选表可能依赖的任何其他数据库对象。因此，不能保证将特定表恢复到一个空数据库中一定会成功。
此标志与 pg_dump 的 -t 标志并不完全相同。 pg_restore 目前不支持通配符匹配，也不能在其 -t 中包含模式名。而且，虽然 pg_dump 的 -t 标志也会转储所选表的附属对象（例如索引）， pg_restore 的 -t 标志并不包括这些附属对象。
在 PostgreSQL 9.6 之前的版本中，此标志只匹配表， 不匹配其他任何类型的关系。
-T trigger--trigger=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 指定超级用户用户名，或者更好的是，直接以 PostgreSQL 超级用户身份运行 pg_restore。
--enable-row-security此选项仅在恢复启用了行安全性的表内容时才相关。默认情况下， pg_restore 会将 row_security 设置为关闭，以确保所有数据都能恢复到表中。如果用户没有足够的权限绕过行安全性，就会抛出错误。 此参数会指示 pg_restore 改为将 row_security 设置为打开，从而允许用户尝试在启用行安全性的情况下恢复表内容。 如果用户无权将转储中的行插入该表，这仍然可能失败。
请注意，此选项当前还要求转储采用 INSERT 格式， 因为 COPY FROM 不支持行安全性。
--if-exists在 --clean 模式下，使用 DROP ... IF EXISTS 命令删除对象。这会抑制本来可能被报告的 “does not exist” 错误。除非同时指定了 --clean，否则此选项无效。
--no-comments不输出用于恢复注释的命令，即使归档中包含注释。
--no-data-for-failed-tables默认情况下，即使表的创建命令失败（例如因为表已经存在），表数据仍然会被恢复。 使用此选项时，这类表的数据会被跳过。如果目标数据库已经包含所需的表内容， 这种行为会很有用。例如，PostgreSQL 扩展 （如 PostGIS）的辅助表可能已经装载到目标数据库中； 指定此选项可以防止向这些表装载重复或过时的数据。
此选项仅在直接恢复到数据库时有效，而在生成 SQL 脚本输出时无效。
--no-publications不输出用于恢复发布的命令，即使归档中包含它们。
--no-security-labels不输出用于恢复安全标签的命令，即使归档中包含它们。
--no-subscriptions不输出用于恢复订阅的命令，即使归档中包含它们。
--no-tablespaces不输出用于选择表空间的命令。使用此选项后，所有对象都会在恢复期间默认的表空间中创建。
--section=sectionname仅恢复指定部分。部分名称可以是 pre-data、data 或 post-data。可以多次指定此选项来选择多个部分。默认是恢复所有部分。
数据部分包含实际的表数据以及大对象定义。post-data 部分由索引、触发器、规则以及除已验证检查约束之外的约束定义组成。 pre-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 所需的权限，但可以切换到具有所需权限的角色时， 此选项会很有用。有些安装环境禁止直接以超级用户登录，而使用此选项可以在不违反该策略的情况下执行恢复。
PGHOSTPGOPTIONSPGPORTPGUSER默认连接参数
PG_COLOR指定是否在诊断消息中使用颜色。可能的值为 always、 auto 和 never。
与大多数其他 PostgreSQL 工具一样，该工具也使用 libpq 支持的环境变量（见 Section 33.14）。 但是，当未提供数据库名时，它不会读取 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，以便优化器获得有用的统计信息；更多信息请参阅Section 24.1.3和Section 24.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