↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 命令行工具 / 客户端程序

pg_restore

pg_restore — 从由 pg_dump 创建的归档文件恢复 PostgreSQL 数据库

当前查看 PostgreSQL 18.6。

说明

pg_restore — 从由 pg_dump 创建的归档文件恢复 PostgreSQL 数据库

手册中的可执行程序
pg_restore
程序版本
18.6
参考清单
客户端程序
选项定义组
53

用法

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

手册中的选项

选项与参数说明
-a --data-only仅恢复数据，不恢复模式（数据定义）或统计信息。如果归档中包含，则会恢复表数据、大对象和序列值。
-c --clean在恢复数据库对象之前，发出 DROP 命令以删除将要恢复的所有对象。此选项适用于覆盖现有数据库。如果目标数据库中有任何对象不存在，则会报告可忽略的错误消息，除非同时指定了 --if-exists 。
-C --create在向其中恢复之前先创建数据库。如果同时指定了 --clean ，则会在连接到目标数据库之前先删除并重新创建它。
-d dbname --dbname= dbname连接到数据库 dbname ，并直接恢复到该数据库中。 dbname 可以是一个 连接字符串 。如果是这样，连接字符串参数会覆盖任何冲突的命令行选项。
-e --exit-on-error如果在向数据库发送 SQL 命令时遇到错误，则退出。默认行为是继续执行，并在恢复结束时显示错误计数。
-f filename --file= filename指定生成脚本的输出文件，或者在与 -l 一起使用时指定列表输出文件。使用 - 表示 stdout 。
-F format --format= format指定归档格式。不必指定格式，因为 pg_restore 会自动确定格式。如果指定，可以是以下格式之一：
-I index --index= index仅恢复指定名称的索引的定义。可以通过多次指定 -I 来恢复多个索引。
-j number-of-jobs --jobs= number-of-jobs将 pg_restore 中最耗时的步骤，也就是装载数据、创建索引或创建约束，最多使用 number-of-jobs 个并发会话并行执行。此选项可以显著缩短将大型数据库恢复到运行在多处理器机器上的服务器所需的时间。当生成脚本而不是直接连接到数据库服务器时，此选项会被忽略。
-l --list列出归档的目录。此操作的输出可用作 -L 选项的输入。注意，如果将 -n 或 -t 等筛选选项与 -l 一起使用，它们会限制所列出的项目。
-L list-file --use-list= list-file只恢复 list-file 中列出的归档元素，并按照它们在文件中出现的顺序恢复。注意，如果将 -n 或 -t 等筛选选项与 -L 一起使用，它们会进一步限制所恢复的项目。
-n schema --schema= schema仅恢复位于指定模式中的对象。可以通过多次指定 -n 来指定多个模式。这可以与 -t 选项结合使用，只恢复特定表。
-N schema --exclude-schema= schema不恢复位于指定模式中的对象。可以通过多次指定 -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仅恢复模式（数据定义），不恢复数据，前提是归档中存在模式条目。
-S username --superuser= username指定在禁用触发器时要使用的超级用户用户名。仅当使用 --disable-triggers 时才相关。
-t table --table= table仅恢复指定表的定义和/或数据。这里的 “ 表 ” 包括视图、物化视图、序列和外部表。可以通过多次指定 -t 来选择多个表。此选项可以与 -n 选项结合使用，以指定特定模式中的表。
-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 在恢复数据期间发出命令，临时禁用目标表上的触发器。如果你不希望在恢复数据期间触发表上的引用完整性检查或其他触发器，请使用此选项。
--enable-row-security此选项仅在恢复启用了行安全性的表内容时才相关。默认情况下， pg_restore 会将 row_security 设置为 off，以确保所有数据都能恢复到表中。如果用户没有足够的权限绕过行安全性，就会抛出错误。此参数会指示 pg_restore 改为将 row_security 设置为 on，从而允许用户尝试在启用行安全性的情况下恢复表内容。如果用户无权将转储中的行插入该表，这仍然可能失败。
--filter= filename指定一个文件名，从中读取恢复时要排除或包含的对象匹配模式。这些模式按照与下列选项相同的规则解释： -n / --schema 用于包含某个模式中的对象， -N / --exclude-schema 用于排除某个模式中的对象， -P / --function 用于恢复指定函数， -I / --index 用于恢复指定索引， -t / --table 用于恢复指定表，以及 -T / --trigger 用于恢复触发器。要从 STDIN 读取，请使用 - 作为文件名。 --filter 选项可以与上面列出的包含或排除对象的选项结合使用，也可以为了指定多个过滤文件而多次给出。
--if-exists使用 DROP ... IF EXISTS 命令在 --clean 模式下删除对象。这会抑制原本可能报告的 “ does not exist ” 错误信息。除非同时指定了 --clean ，否则此选项无效。
--no-comments不输出用于恢复注释的命令，即使归档中包含注释。
--no-data不输出用于恢复数据的命令，即使归档中包含数据。
--no-data-for-failed-tables默认情况下，即使表的创建命令失败（例如因为表已经存在），表数据仍然会被恢复。使用此选项时，这类表的数据会被跳过。如果目标数据库已经包含所需的表内容，这种行为会很有用。例如， PostgreSQL 扩展（如 PostGIS ）的辅助表可能已经装载到目标数据库中；指定此选项可以防止向这些表装载重复或过时的数据。
--no-policies不输出用于恢复行安全性策略的命令，即使归档中包含它们。
--no-publications不输出用于恢复发布的命令，即使归档中包含它们。
--no-schema不输出用于恢复模式（数据定义）的命令，即使归档中包含它们。
--no-security-labels不输出用于恢复安全标签的命令，即使归档中包含它们。
--no-statistics不输出用于恢复统计信息的命令，即使归档中包含它们。
--no-subscriptions不输出用于恢复订阅的命令，即使归档中包含它们。
--no-table-access-method不输出用于选择表访问方法的命令。使用此选项时，所有对象在恢复时都会使用当时默认的表访问方法创建。
--no-tablespaces不输出用于选择表空间的命令。使用此选项时，所有对象在恢复时都会创建在当时默认的表空间中。
--restrict-key= restrict_key在转储输出中使用提供的字符串作为 psql \restrict 键。这只能用于 SQL 脚本输出，也就是使用 --file 选项时。如果未指定该键， pg_restore 会按需随机生成一个。键只能包含字母数字字符。
--section= sectionname仅恢复指定部分。部分名称可以是 pre-data 、 data 或 post-data 。可以多次指定此选项来选择多个部分。默认是恢复所有部分。
--statistics如果归档中包含统计信息，则输出用于恢复统计信息的命令。这是默认行为。
--statistics-only仅恢复统计信息，不恢复模式（数据定义）或数据。
--strict-names要求每个模式限定符（ -n / --schema ）和表限定符（ -t / --table ）至少匹配待恢复文件中的一个模式/表。
--transaction-size= N将恢复作为一系列事务执行，每个事务最多处理 N 个数据库对象。此选项隐含 --exit-on-error 。
--use-set-session-authorization输出符合 SQL 标准的 SET SESSION AUTHORIZATION 命令，而不是使用 ALTER OWNER 命令来确定对象所有权。这样会使转储结果更符合标准，但根据转储中对象的历史，可能无法正确恢复。
-? --help显示关于 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 在连接数据库之前提示输入密码。
--role= rolename指定执行恢复时要使用的角色名。此选项会使 pg_restore 在连接数据库后发出 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少 pg_restore 所需的权限，但可以切换到具有所需权限的角色时，此选项会很有用。有些安装环境禁止直接以超级用户登录，而使用此选项可以在不违反该策略的情况下执行恢复。

环境变量

变量含义
PGHOST PGOPTIONS PGPORT PGUSER默认连接参数
PG_COLOR指定诊断消息是否使用颜色。可选值为 always 、 auto 和 never 。

手册定义

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 语句装载数据。

警告

恢复转储会导致目标端执行由源超级用户选择的任意代码。部分转储和部分恢复并不会限制这一点。如果源超级用户不可信，则必须在恢复前检查转储得到的 SQL 语句。非纯文本转储可以使用 pg_restore 的 --file 选项进行检查。注意，运行转储和恢复的客户端无需信任源或目标超级用户。

选项

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 或 --statistics-only 一起使用。它类似于指定 --section=pre-data --section=post-data --no-statistics，但由于历史原因并不完全相同。

（不要把它与 --schema 选项混淆，后者中的“schema”一词含义不同。）

-S username
--superuser=username

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

-t 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

指定详细模式。这会使 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 指定超级用户用户名，或者更好的是，直接以 PostgreSQL 超级用户身份运行 pg_restore。

--enable-row-security

此选项仅在恢复启用了行安全性的表内容时才相关。默认情况下，pg_restore 会将row_security设置为 off，以确保所有数据都能恢复到表中。如果用户没有足够的权限绕过行安全性，就会抛出错误。此参数会指示 pg_restore 改为将row_security设置为 on，从而允许用户尝试在启用行安全性的情况下恢复表内容。如果用户无权将转储中的行插入该表，这仍然可能失败。

请注意，此选项当前还要求转储采用 INSERT 格式，因为 COPY FROM 不支持行安全性。

--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 关键字一起使用。

以 # 开头的行被视为注释并忽略。注释也可以放在对象匹配模式行之后。空白行同样会被忽略。有关如何在匹配模式中加引号，请参见模式。

--if-exists

使用 DROP ... IF EXISTS 命令在 --clean 模式下删除对象。这会抑制原本可能报告的“does not exist”错误信息。除非同时指定了 --clean，否则此选项无效。

--no-comments

不输出用于恢复注释的命令，即使归档中包含注释。

--no-data

不输出用于恢复数据的命令，即使归档中包含数据。

--no-data-for-failed-tables

默认情况下，即使表的创建命令失败（例如因为表已经存在），表数据仍然会被恢复。使用此选项时，这类表的数据会被跳过。如果目标数据库已经包含所需的表内容，这种行为会很有用。例如，PostgreSQL 扩展（如 PostGIS）的辅助表可能已经装载到目标数据库中；指定此选项可以防止向这些表装载重复或过时的数据。

此选项仅在直接恢复到数据库时有效，而在生成 SQL 脚本输出时无效。

--no-policies

不输出用于恢复行安全性策略的命令，即使归档中包含它们。

--no-publications

不输出用于恢复发布的命令，即使归档中包含它们。

--no-schema

不输出用于恢复模式（数据定义）的命令，即使归档中包含它们。

--no-security-labels

不输出用于恢复安全标签的命令，即使归档中包含它们。

--no-statistics

不输出用于恢复统计信息的命令，即使归档中包含它们。

--no-subscriptions

不输出用于恢复订阅的命令，即使归档中包含它们。

--no-table-access-method

不输出用于选择表访问方法的命令。使用此选项时，所有对象在恢复时都会使用当时默认的表访问方法创建。

--no-tablespaces

不输出用于选择表空间的命令。使用此选项时，所有对象在恢复时都会创建在当时默认的表空间中。

--restrict-key=restrict_key

在转储输出中使用提供的字符串作为 psql \restrict 键。这只能用于 SQL 脚本输出，也就是使用 --file 选项时。如果未指定该键，pg_restore 会按需随机生成一个。键只能包含字母数字字符。

此选项主要用于测试以及其他需要可重复输出的场景（例如比较转储文件）。一般不建议使用它，因为若恶意服务器事先知道该键，可能能够注入任意代码，并在运行 psql 处理转储输出的机器上执行。

--section=sectionname

仅恢复指定部分。部分名称可以是 pre-data、data 或 post-data。可以多次指定此选项来选择多个部分。默认是恢复所有部分。

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

--statistics

如果归档中包含统计信息，则输出用于恢复统计信息的命令。这是默认行为。

--statistics-only

仅恢复统计信息，不恢复模式（数据定义）或数据。

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

输出符合 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 支持的环境变量（见第 32.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文档。

默认情况下，如果转储文件中包含优化器统计信息，pg_restore 会恢复它们。如果并非所有统计信息都已恢复，那么对每个已恢复的表执行 ANALYZE 可能会很有帮助，这样优化器就能获得有用的统计信息。更多信息见第 24.1.3 节和第 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

另见

pg_dump, pg_dumpall, psql

相关条目

文档与源码

来源构建
版本
18.6
构建
https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 17 → 18: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 17
+++ PostgreSQL 18
@@ -11,7 +11,7 @@
   ],
   "options": [
     {
-      "description": "Restore only the data, not the schema (data definitions). Table data, large objects, and sequence values are restored, if present in the archive. This option is similar to, but for historical reasons not identical to, specifying --section=data .",
+      "description": "Restore only the data, not the schema (data definitions) or statistics. Table data, large objects, and sequence values are restored, if present in the archive. This option is similar to, but for historical reasons not identical to, specifying --section=data .",
       "names": [
         "-a",
         "--data-only"
@@ -59,13 +59,6 @@
       "signature": "-f filename --file= filename"
     },
     {
-      "description": "Specify a filename from which to read patterns for objects excluded or included from restore. The patterns are interpreted according to the same rules as -n / --schema for including objects in schemas, -N / --exclude-schema for excluding objects in schemas, -P / --function for restoring named functions, -I / --index for restoring named indexes, -t / --table for restoring named tables or -T / --trigger for restoring triggers. To read from STDIN , use - as the filename. The --filter option can be specified in conjunction with the above listed options for including or excluding objects, and can also be specified more than once for multiple filter files. The file lists one database pattern per row, with the following format: { include | exclude } { function | index | schema | table | trigger } PATTERN The first keyword specifies whether the objects matched by the pattern are to be included or excluded. The second keyword specifies the type of object to be filtered using the pattern: function : functions, works like the -P / --function option. This keyword can only be used with the include keyword. index : indexes, works like the -I / --indexes option. This keyword can only be used with the include keyword. schema : schemas, works like the -n / --schema and -N / --exclude-schema options. table : tables, works like the -t / --table option. This keyword can only be used with the include keyword. trigger : triggers, works like the -T / --trigger option. This keyword can only be used with the include keyword. Lines starting with # are considered comments and ignored. Comments can be placed after an object pattern row as well. Blank lines are also ignored. See Patterns for how to perform quoting in patterns.",
-      "names": [
-        "--filter= filename"
-      ],
-      "signature": "--filter= filename"
-    },
-    {
       "description": "Specify format of the archive. It is not necessary to specify the format, since pg_restore will determine the format automatically. If specified, it can be one of the following: c custom The archive is in the custom format of pg_dump . d directory The archive is a directory archive. t tar The archive is a tar archive.",
       "names": [
         "-F format",
@@ -146,7 +139,7 @@
       "signature": "-R --no-reconnect"
     },
     {
-      "description": "Restore only the schema (data definitions), not data, to the extent that schema entries are present in the archive. This option is the inverse of --data-only . It is similar to, but for historical reasons not identical to, specifying --section=pre-data --section=post-data . (Do not confuse this with the --schema option, which uses the word “ schema ” in a different meaning.)",
+      "description": "Restore only the schema (data definitions), not data, to the extent that schema entries are present in the archive. This option cannot be used with --data-only or --statistics-only . It is similar to, but for historical reasons not identical to, specifying --section=pre-data --section=post-data --no-statistics . (Do not confuse this with the --schema option, which uses the word “ schema ” in a different meaning.)",
       "names": [
         "-s",
         "--schema-only"
@@ -211,7 +204,7 @@
       "signature": "-1 --single-transaction"
     },
     {
-      "description": "This option is relevant only when performing a data-only restore. It instructs pg_restore to execute commands to temporarily disable triggers on the target tables while the data is restored. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data restore. Presently, the commands emitted for --disable-triggers must be done as superuser. So you should also specify a superuser name with -S or, preferably, run pg_restore as a PostgreSQL superuser.",
+      "description": "This option is relevant only when performing a restore without schema. It instructs pg_restore to execute commands to temporarily disable triggers on the target tables while the data is restored. Use this if you have referential integrity checks or other triggers on the tables that you do not want to invoke during data restore. Presently, the commands emitted for --disable-triggers must be done as superuser. So you should also specify a superuser name with -S or, preferably, run pg_restore as a PostgreSQL superuser.",
       "names": [
         "--disable-triggers"
       ],
@@ -225,6 +218,13 @@
       "signature": "--enable-row-security"
     },
     {
+      "description": "Specify a filename from which to read patterns for objects excluded or included from restore. The patterns are interpreted according to the same rules as -n / --schema for including objects in schemas, -N / --exclude-schema for excluding objects in schemas, -P / --function for restoring named functions, -I / --index for restoring named indexes, -t / --table for restoring named tables or -T / --trigger for restoring triggers. To read from STDIN , use - as the filename. The --filter option can be specified in conjunction with the above listed options for including or excluding objects, and can also be specified more than once for multiple filter files. The file lists one database pattern per row, with the following format: { include | exclude } { function | index | schema | table | trigger } PATTERN The first keyword specifies whether the objects matched by the pattern are to be included or excluded. The second keyword specifies the type of object to be filtered using the pattern: function : functions, works like the -P / --function option. This keyword can only be used with the include keyword. index : indexes, works like the -I / --indexes option. This keyword can only be used with the include keyword. schema : schemas, works like the -n / --schema and -N / --exclude-schema options. table : tables, works like the -t / --table option. This keyword can only be used with the include keyword. trigger : triggers, works like the -T / --trigger option. This keyword can only be used with the include keyword. Lines starting with # are considered comments and ignored. Comments can be placed after an object pattern row as well. Blank lines are also ignored. See Patterns for how to perform quoting in patterns.",
+      "names": [
+        "--filter= filename"
+      ],
+      "signature": "--filter= filename"
+    },
+    {
       "description": "Use DROP ... IF EXISTS commands to drop objects in --clean mode. This suppresses “ does not exist ” errors that might otherwise be reported. This option is not valid unless --clean is also specified.",
       "names": [
         "--if-exists"
@@ -239,6 +239,13 @@
       "signature": "--no-comments"
     },
     {
+      "description": "Do not output commands to restore data, even if the archive contains them.",
+      "names": [
+        "--no-data"
+      ],
+      "signature": "--no-data"
+    },
+    {
       "description": "By default, table data is restored even if the creation command for the table failed (e.g., because it already exists). With this option, data for such a table is skipped. This behavior is useful if the target database already contains the desired table contents. For example, auxiliary tables for PostgreSQL extensions such as PostGIS might already be loaded in the target database; specifying this option prevents duplicate or obsolete data from being loaded into them. This option is effective only when restoring directly into a database, not when producing SQL script output.",
       "names": [
         "--no-data-for-failed-tables"
@@ -246,6 +253,13 @@
       "signature": "--no-data-for-failed-tables"
     },
     {
+      "description": "Do not output commands to restore row security policies, even if the archive contains them.",
+      "names": [
+        "--no-policies"
+      ],
+      "signature": "--no-policies"
+    },
+    {
       "description": "Do not output commands to restore publications, even if the archive contains them.",
       "names": [
         "--no-publications"
@@ -253,6 +267,13 @@
       "signature": "--no-publications"
     },
     {
+      "description": "Do not output commands to restore schema (data definitions), even if the archive contains them.",
+      "names": [
+        "--no-schema"
+      ],
+      "signature": "--no-schema"
+    },
+    {
       "description": "Do not output commands to restore security labels, even if the archive contains them.",
       "names": [
         "--no-security-labels"
@@ -260,6 +281,13 @@
       "signature": "--no-security-labels"
     },
     {
+      "description": "Do not output commands to restore statistics, even if the archive contains them.",
+      "names": [
+        "--no-statistics"
+      ],
+      "signature": "--no-statistics"
+    },
+    {
       "description": "Do not output commands to restore subscriptions, even if the archive contains them.",
       "names": [
         "--no-subscriptions"
@@ -295,7 +323,21 @@
       "signature": "--section= sectionname"
     },
     {
-      "description": "Require that each schema ( -n / --schema ) and table ( -t / --table ) qualifier match at least one schema/table in the backup file.",
+      "description": "Output commands to restore statistics, if the archive contains them. This is the default.",
+      "names": [
+        "--statistics"
+      ],
+      "signature": "--statistics"
+    },
+    {
+      "description": "Restore only the statistics, not schema (data definitions) or data.",
+      "names": [
+        "--statistics-only"
+      ],
+      "signature": "--statistics-only"
+    },
+    {
+      "description": "Require that each schema ( -n / --schema ) and table ( -t / --table ) qualifier match at least one schema/table in the file to be restored.",
       "names": [
         "--strict-names"
       ],

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

相关条目

导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。