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 使用 -
。
--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
第一个关键字指定与模式匹配的对象是包含还是排除。第二个关键字指定按模式过滤的对象类型
函数
:函数,其作用类似于 -P
/--function
选项。此关键字只能与 include
关键字一起使用。
索引
:索引,其作用类似于 -I
/--indexes
选项。此关键字只能与 include
关键字一起使用。
架构
:架构,其作用类似于 -n
/--schema
和 -N
/--exclude-schema
选项。
表
:表,其作用类似于 -t
/--table
选项。此关键字只能与 include
关键字一起使用。
触发器
:触发器,其作用类似于 -T
/--trigger
选项。此关键字只能与 include
关键字一起使用。
以 #
开头的行被视为注释,且会被忽略。也可以将注释添加到对象模式行后面。空行也会被忽略。有关如何在模式中进行引用的信息,请参见 Patterns。
-F format
--format=format
指定归档文件的格式。不必指定格式,因为 pg_restore
会自动确定格式。如果指定了格式,格式可以是以下格式之一
c
自定义
归档文件采用 pg_dump
的自定义格式。
d
目录
归档文件是一个目录归档文件。
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
选项混淆,后者以不同的含义使用单词 “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
指定详细模式。这会使 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
模式下删除对象。这会禁止可能会报告的 “does not exist” 错误。除非还指定了 --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
)限定符至少匹配备份文件中一个架构/表格。
--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 的局限性。
还原完成后,建议针对每个还原的表运行 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