Note

pg_restore

pg_restore —从 pg_dump 创建的 Files 文件中恢复 PostgreSQL 数据库

Synopsis

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

Description

pg_restore 是一种 Util，用于从pg_dump创建的非明文格式之一的存档中恢复 PostgreSQL 数据库。它将发出将数据库重建到保存时所处状态的必要命令。存档文件还允许 pg_restore 对恢复的内容具有选择性，甚至可以在恢复之前对项目进行重新排序。存档文件被设计为可跨体系结构移植。

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

显然，pg_restore 无法还原存档文件中不存在的信息。例如，如果存档是使用“将数据作为INSERT命令转储”选项进行的，则 pg_restore 将无法使用COPY语句加载数据。

Options

pg_restore 接受以下命令行参数。

• filename

  • 指定要还原的归档文件(或目录格式的目录)的位置。如果未指定，则使用标准 Importing。

• -a
--data-only

  • 仅还原数据，而不还原架构(数据定义)。如果存档中存在表数据，大对象和序列值，则将还原它们。

此选项类似于--section=data，但由于历史原因不同。

• -c
--clean

  • 在重新创建数据库对象之前，先对其进行清理(删除)。 (除非使用--if-exists，否则如果目标数据库中不存在任何对象，这可能会生成一些无害的错误消息.)

• -C
--create

  • 在还原到数据库之前先创建它。如果还指定了--clean，请先删除并重新创建目标数据库，然后再连接它。

使用此选项时，以-d命名的数据库仅用于发出初始DROP DATABASE和CREATE DATABASE命令。所有数据都将还原到存档中显示的数据库名称中。

• -d dbname
--dbname=dbname

  • 连接到数据库* dbname *并直接还原到数据库中。

• -e
--exit-on-error

  • 如果在将 SQL 命令发送到数据库时遇到错误，则退出。默认设置是 continue 并在还原结束时显示错误计数。

• -f filename
--file=filename

  • 为生成的脚本或与-l一起使用的列表指定输出文件。将-用作标准输出，这也是默认设置。

• -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 中最耗时的部分-那些加载数据，创建索引或创建约束的部分。此选项可以大大减少将大型数据库还原到 multiprocessing 器计算机上运行的服务器的时间。

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

此选项的最佳值取决于服务器，Client 端和网络的硬件设置。影响因素包括 CPU 内核数和磁盘设置。一个很好的起点是服务器上的 CPU 内核数量，但是在许多情况下，大于此数量的值也可以导致更快的还原时间。当然，太高的值会由于抖动而导致性能下降。

此选项仅支持自定义和目录归档格式。Importing 必须是常规文件或目录(而不是管道)。发出脚本而不是直接连接到数据库服务器时，将忽略此选项。另外，不能与--single-transaction选项一起使用多个作业。

• -l
--list

  • 列出 Files 目录。此操作的输出可用作-L选项的 Importing。请注意，如果将-n或-t之类的过滤开关与-l一起使用，它们将限制列出的项目。

• -L list-file
--use-list=list-file

  • 仅还原* list-file *中列出的那些归档元素，并按照它们在文件中出现的 Sequences 进行还原。请注意，如果将-n或-t之类的过滤开关与-L一起使用，它们将进一步限制恢复的项目。

• list-file *通常是通过编辑上一个-l操作的输出来创建的。可以移动或删除行，也可以通过在行的开头放置分号(;)来 Comments 掉行。请参阅下面的示例。

• -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 username
--superuser=username

  • 指定禁用触发器时要使用的超级用户名。仅在使用--disable-triggers时才有意义。

• -t table
--table=table

  • 仅还原命名表的定义和/或数据。为此，“表”包括视图，实例化视图，序列和外部表。通过写入多个-t开关可以选择多个表。该选项可以与-n选项结合使用以指定特定模式中的表。

• -T trigger
--trigger=trigger

  • 仅还原命名触发器。可以通过多个-T开关指定多个触发器。

• -v
--verbose

  • 指定详细模式。

• -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设置为 off，以确保将所有数据还原到表中。如果用户没有足够的特权绕过行安全性，那么将引发错误。该参数指示 pg_restore 改为将row_security设置为 on，从而允许用户尝试在启用行安全性的情况下还原表的内容。如果用户无权将转储中的行插入表中，这可能仍然会失败。

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

• --if-exists

  • 清理数据库对象时，请使用条件命令(即添加IF EXISTS子句)。除非也指定了--clean，否则此选项无效。

• --no-data-for-failed-tables

  • 默认情况下，即使表的创建命令失败(例如，因为它已经存在)，表数据也会被还原。使用此选项，将跳过此类表的数据。如果目标数据库已经包含所需的表内容，则此行为很有用。例如，PostgreSQL 扩展的辅助表(例如 PostGIS)可能已经加载到目标数据库中了。指定此选项可防止将重复或过时的数据加载到其中。

此选项仅在直接还原到数据库中时才有效，而在生成 SQL 脚本输出时才有效。

• --no-publications

  • 即使存档包含出版物，也不要输出命令以还原出版物。

• --no-security-labels

  • 即使存档包含安全标签，也不要输出命令以还原安全标签。

• --no-subscriptions

  • 即使归档中包含预订，也不要输出命令以还原预订。

• --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 域套接字文件 extensions。默认值是PGPORT环境变量(如果已设置)或已编译的默认值。

• -U username
--username=username

  • 连接的用户名。

• -w
--no-password

  • 切勿发出密码提示。如果服务器要求密码验证，而其他方式(例如.pgpass文件)无法使用密码，则连接尝试将失败。该选项在没有用户 Importing 密码的批处理作业和脚本中很有用。

• -W
--password

  • 强制 pg_restore 在连接数据库之前提示 Importing 密码。

这个选项从来都不是必须的，因为如果服务器要求密码认证，pg_restore 会自动提示 Importing 密码。但是，pg_restore 会浪费连接尝试，发现服务器需要密码。在某些情况下，值得 Importing-W以避免额外的连接尝试。

• --role=rolename

  • 指定用于执行还原的角色名称。此选项使 pg_restore 在连接到数据库后发出SET ROLE * rolename *命令。当通过身份验证的用户(由-U指定)缺少 pg_restore 所需的特权，但可以切换到具有所需权限的角色时，此功能很有用。某些安装具有禁止直接以超级用户身份登录的策略，并且使用此选项可以在不违反策略的情况下执行还原。

Environment

• PGHOST
PGOPTIONS
PGPORT
PGUSER

  • 默认连接参数

与大多数其他 PostgreSQLUtil 一样，该 Util 也使用 libpq 支持的环境变量(请参见Section 33.14)。但是，当未提供数据库名称时，它不会读取PGDATABASE。

Diagnostics

当使用-d选项指定直接数据库连接时，pg_restore 在内部执行 SQL 语句。如果您在运行 pg_restore 时遇到问题，请确保您能够使用例如psql从数据库中选择信息。同样，libpq 前端库使用的任何默认连接设置和环境变量都将适用。

Notes

如果您的安装对template1数据库进行了本地添加，请小心将 pg_restore 的输出加载到一个 true 的空数据库中；否则，由于添加对象的重复定义，您很可能会出错。要创建没有任何本地添加的空数据库，请从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。

Examples

假设我们已经将名为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

分号开始 Comments，行首的数字指代分配给每个项目的内部存档 ID。

文件中的行可以被 Comments 掉，删除和重新排序。例如：

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 的 Importing，并且只能按以下 Sequences 恢复项目 10 和 6：

$ pg_restore -L db.list db.dump

See Also

pg_dump, pg_dumpall, psql