2025年9月25日: PostgreSQL 18 发布!
支持的版本: 当前 (18) / 17 / 16 / 15 / 14 / 13
开发版本: devel
不支持的版本: 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0 / 8.4 / 8.3 / 8.2 / 8.1 / 8.0 / 7.4 / 7.3 / 7.2 / 7.1

pg_dump

pg_dump — 将 PostgreSQL 数据库导出为 SQL 脚本或其他格式

概要

pg_dump [连接选项...] [选项...] [数据库名]

描述

pg_dump 是一个用于导出 PostgreSQL 数据库的实用程序。即使数据库正在被并发使用,它也能进行一致性的导出。pg_dump 不会阻止其他用户访问数据库(读或写)。请注意,除了简单情况外,pg_dump 通常不适合用于定期备份生产数据库。有关更多讨论,请参阅 第 25 章

pg_dump 只能转储单个数据库。要导出整个集群,或导出集群中所有数据库的全局对象(如角色和表空间),请使用 pg_dumpall

转储可以以脚本或归档文件格式输出。脚本转储是纯文本文件,包含重新构建数据库到转储时状态所需的 SQL 命令。要从这样的脚本恢复,请将其提供给 psql。脚本文件可用于在其他机器和其他架构上重新构建数据库;稍作修改,甚至可以在其他 SQL 数据库产品上使用。

替代的归档文件格式必须与 pg_restore 一起使用来重建数据库。它们允许 pg_restore 选择性地恢复,甚至可以在恢复前重新排序项目。归档文件格式设计为跨架构可移植。

当与归档文件格式之一结合使用并与 pg_restore 结合使用时,pg_dump 提供了一种灵活的归档和传输机制。pg_dump 可用于导出整个数据库,然后 pg_restore 可用于检查归档或/和选择要恢复的数据库部分。最灵活的输出文件格式是“自定义”格式(-Fc)和“目录”格式(-Fd)。它们允许选择和重新排序所有归档项,支持并行恢复,并且默认情况下是压缩的。“目录”格式是唯一支持并行转储的格式。

在运行 pg_dump 时,应检查输出中的任何警告(打印在标准错误流上),尤其要考虑到下面列出的限制。

警告

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

选项

以下命令行选项控制输出的内容和格式。

dbname

指定要转储的数据库名称。如果未指定,则使用环境变量 PGDATABASE。如果该变量未设置,则使用连接指定的用户名称。

-a
--data-only

仅转储数据,而不转储模式(数据定义)或统计信息。转储表数据、大对象和序列值。

此选项与指定 --section=data 类似,但由于历史原因并不完全相同。

-b
--large-objects
--blobs (已弃用)

在转储中包含大对象。这是默认行为,除非指定了 --schema--table--schema-only--statistics-only--no-data。因此,-b 开关仅在请求了特定模式或表时用于将大对象添加到转储中。请注意,大对象被视为数据,因此在使用 --data-only 时会包含它们,但在使用 --schema-only--statistics-only 时不会。

-B
--no-large-objects
--no-blobs (已弃用)

排除转储中的大对象。

当同时给出 -b-B 时,行为是在转储数据时输出大对象,请参阅 -b 的文档。

-c
--clean

在输出创建它们的命令之前,输出用于 DROP 所有转储的数据库对象的命令。当恢复时需要覆盖现有数据库时,此选项非常有用。如果目标数据库中不存在任何对象,则在恢复期间将报告可忽略的错误消息,除非还指定了 --if-exists

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

-C
--create

在输出开始时添加一个创建数据库本身的命令,并重新连接到已创建的数据库。(使用此形式的脚本,在运行脚本之前连接到目标安装中的哪个数据库并不重要。)如果还指定了 --clean,则脚本将先删除目标数据库,然后再重新创建它,之后再重新连接。

使用 --create 时,输出还包括数据库的注释(如果存在),以及特定于此数据库的任何配置变量设置,即任何提及此数据库的 ALTER DATABASE ... SET ...ALTER ROLE ... IN DATABASE ... SET ... 命令。数据库本身的访问权限也会被转储,除非指定了 --no-acl

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

-e 模式
--extension=模式

仅转储与 模式 匹配的扩展。当未指定此选项时,将转储目标数据库中的所有非系统扩展。可以通过编写多个 -e 开关来选择多个扩展。模式 参数被解释为与 psql\d 命令使用的规则相同的模式(请参阅 模式),因此通过在模式中写入通配符也可以选择多个扩展。使用通配符时,请务必引用模式(如果需要),以防止 shell 扩展通配符。

通过 pg_extension_config_dump 注册的任何配置关系都将包含在转储中,如果其扩展由 --extension 指定。

注意

当指定 -e 时,pg_dump 不会尝试转储所选扩展可能依赖的任何其他数据库对象。因此,无法保证仅将特定扩展转储的结果成功还原到干净的数据库中。

-E 编码
--encoding=编码

以指定的字符集编码创建转储。默认情况下,转储以数据库编码创建。(获得相同结果的另一种方法是将 PGCLIENTENCODING 环境变量设置为所需的转储编码。)支持的编码在 第 23.3.1 节 中描述。

-f 文件
--file=文件

将输出发送到指定的文件。对于基于文件的输出格式,可以省略此参数,在这种情况下将使用标准输出。但是,对于目录输出格式,必须提供此参数,在这种情况下,它指定目标目录而不是文件。在这种情况下,目录将由 pg_dump 创建,并且必须预先不存在。

-F format
--format=format

选择输出的格式。格式 可以是以下之一

p
plain

输出纯文本SQL脚本文件(默认)。

c
custom

输出适合输入到 pg_restore 的自定义格式归档。与目录输出格式一起,这是最灵活的输出格式,因为它允许在恢复期间手动选择和重新排序归档项。此格式默认也已压缩。

d
directory

输出适合输入到 pg_restore 的目录格式归档。这将创建一个目录,其中每个表和大对象都有一个对应的文件,还有一个所谓的目录文件(Table of Contents),以机器可读的格式描述了转储的对象,pg_restore 可以读取它。目录格式归档可以使用标准的 Unix 工具进行操作;例如,未压缩归档中的文件可以使用 gziplz4zstd 工具进行压缩。此格式默认使用 gzip 压缩,并且还支持并行转储。

t
tar

输出适合输入到 pg_restoretar 格式归档。tar 格式与目录格式兼容:提取 tar 格式归档会产生一个有效的目录格式归档。但是,tar 格式不支持压缩。此外,在使用 tar 格式时,表数据项的相对顺序在恢复期间无法更改。

-j njobs
--jobs=njobs

通过同时转储 njobs 个表来并行运行转储。此选项可以减少转储所需的时间,但也会增加数据库服务器的负载。只能将此选项与目录输出格式一起使用,因为这是唯一允许多个进程同时写入其数据的输出格式。

pg_dump 将打开 njobs + 1 个到数据库的连接,因此请确保您的 max_connections 设置足够高,可以容纳所有连接。

在并行转储运行时请求数据库对象的独占锁可能会导致转储失败。原因是 pg_dump 领导者进程请求要转储的对象上的共享锁(ACCESS SHARE),以确保在转储运行时没有人删除它们。如果另一个客户端随后请求表的独占锁,该锁将不会被授予,而是排队等待领导者进程的共享锁被释放。因此,对表的任何其他访问都将不会被授予,并将排队在独占锁请求之后。这包括尝试转储表的辅助进程。在没有任何预防措施的情况下,这会是一个经典的死锁情况。为了检测此冲突,pg_dump 辅助进程请求另一个共享锁,使用 NOWAIT 选项。如果辅助进程未能获得此共享锁,则意味着此时必须有人请求了独占锁,并且无法继续转储,因此 pg_dump 别无选择,只能中止转储。

要执行并行转储,数据库服务器需要支持同步快照,这是在 PostgreSQL 9.2 的主服务器和 10 的备用服务器中引入的功能。通过此功能,数据库客户端可以确保它们看到相同的数据集,即使它们使用不同的连接。pg_dump -j 使用多个数据库连接;它使用领导者进程连接一次数据库,并为每个辅助作业连接一次。如果没有同步快照功能,则不能保证不同的辅助作业会在每个连接中看到相同的数据,这可能导致不一致的备份。

-n 模式
--schema=模式

仅转储与 模式 匹配的模式;这将同时选择模式本身及其包含的所有对象。当未指定此选项时,将转储目标数据库中的所有非系统模式。可以通过编写多个 -n 开关来选择多个模式。模式 参数被解释为与 psql\d 命令使用的规则相同的模式(请参阅 模式),因此通过在模式中写入通配符也可以选择多个模式。使用通配符时,请务必引用模式(如果需要),以防止 shell 扩展通配符;请参阅下面的 示例

注意

当指定 -n 时,pg_dump 不会尝试转储所选模式可能依赖的任何其他数据库对象。因此,无法保证仅将特定模式转储的结果成功还原到干净的数据库中。

注意

当指定 -n 时,不会转储大对象等非模式对象。您可以使用 --large-objects 开关将大对象添加回转储中。

-N 模式
--exclude-schema=模式

不要转储与 模式 匹配的任何模式。模式的解释方式与 -n 相同。-N 可以多次给出,以排除与多个模式中的任何一个匹配的模式。

当同时给出 -n-N 时,行为是仅转储至少匹配一个 -n 开关但不匹配任何 -N 开关的模式。如果 -N 出现在没有 -n 的情况下,那么与 -N 匹配的模式将从正常的转储中排除。

-O
--no-owner

不要输出命令来设置对象的所有权以匹配原始数据库。默认情况下,pg_dump 会发出 ALTER OWNERSET SESSION AUTHORIZATION 语句来设置创建的数据库对象的所有权。除非脚本由超级用户(或拥有脚本中所有对象的同一用户)启动,否则运行脚本时这些语句将失败。要创建一个任何用户都可以还原的脚本,但会给予该用户所有对象的权限,请指定 -O

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

-R
--no-reconnect

此选项已过时,但仍接受以向后兼容。

-s
--schema-only

仅转储对象定义(模式),不转储数据或统计信息。

此选项不能与 --data-only--statistics-only 一起使用。它与指定 --section=pre-data --section=post-data 类似,但由于历史原因并不完全相同。

(不要将其与 --schema 选项混淆,后者在不同含义上使用了“schema”一词。)

要仅排除数据库中一部分表的表数据,请参阅 --exclude-table-data

-S username
--superuser=username

指定在使用禁用触发器时要使用的超级用户用户名。这仅在使用了 --disable-triggers 时才相关。(通常,最好省略此项,而是以超级用户身份启动生成的脚本。)

-t 模式
--table=模式

仅转储名称与 模式 匹配的表。可以通过编写多个 -t 开关来选择多个表。模式 参数被解释为与 psql\d 命令使用的规则相同的模式(请参阅 模式),因此通过在模式中写入通配符也可以选择多个表。使用通配符时,请务必引用模式(如果需要),以防止 shell 扩展通配符;请参阅下面的 示例

除了表之外,此选项还可用于转储匹配的视图、物化视图、外部表和序列的定义。它不会转储视图或物化视图的内容,并且只有在使用 --include-foreign-data 指定了相应的外部服务器时,才会转储外部表的内容。

当使用 -t 时,-n-N 开关无效,因为无论这些开关如何,都会转储由 -t 选择的表,而不会转储非表对象。

注意

当指定 -t 时,pg_dump 不会尝试转储所选表可能依赖的任何其他数据库对象。因此,无法保证仅将特定表转储的结果成功还原到干净的数据库中。

-T 模式
--exclude-table=模式

不要转储与 模式 匹配的任何表。模式的解释方式与 -t 相同。-T 可以多次给出,以排除与多个模式中的任何一个匹配的表。

当同时给出 -t-T 时,行为是仅转储至少匹配一个 -t 开关但不匹配任何 -T 开关的表。如果 -T 出现在没有 -t 的情况下,那么与 -T 匹配的表将从正常的转储中排除。

-v
--verbose

指定详细模式。这将导致 pg_dump 将详细的对象注释和开始/停止时间输出到转储文件,并将进度消息输出到标准错误流。重复该选项将导致额外的调试级别消息出现在标准错误流上。

-V
--version

打印 pg_dump 版本并退出。

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

阻止转储访问权限(GRANT/REVOKE 命令)。

-Z 级别
-Z 方法[:细节]
--compress=级别
--compress=方法[:细节]

指定要使用的压缩方法和/或压缩级别。压缩方法可以设置为 gziplz4zstdnone(无压缩)。可以选择性地指定压缩详细信息字符串。如果详细信息字符串是整数,则指定压缩级别。否则,它应该是一个由逗号分隔的项目列表,每个项目形式为 关键字关键字=值。目前,支持的关键字是 levellong

如果未指定压缩级别,则将使用默认压缩级别。如果仅指定级别而未提及算法,则当级别大于 0 时将使用 gzip 压缩,当级别为 0 时则不进行压缩。

对于自定义和目录归档格式,此选项指定对各个表数据段进行压缩,默认使用 gzip 以中等级别进行压缩。对于纯文本输出,设置非零压缩级别将导致整个输出文件被压缩,如同通过 gziplz4zstd 进行过管道传输一样;但默认情况下不进行压缩。使用 zstd 压缩时,long 模式可能会提高压缩率,但会增加内存使用。

tar 归档格式目前根本不支持压缩。

--binary-upgrade

此选项供就地升级实用程序使用。不推荐或不支持将其用于其他目的。该选项的行为可能在未来的版本中更改,恕不另行通知。

--column-inserts
--attribute-inserts

以带有显式列名的 INSERT 命令(INSERT INTO (, ...) VALUES ...)的形式转储数据。这将使恢复速度非常慢;它主要用于制作可以加载到非 PostgreSQL 数据库中的转储。恢复期间的任何错误只会导致有问题的 INSERT 中的行丢失,而不是整个表内容丢失。

--disable-dollar-quoting

此选项禁用函数体中使用美元引号,并强制使用 SQL 标准字符串语法对其进行引用。

--disable-triggers

此选项仅在创建包含数据但不包含模式的转储时相关。它指示 pg_dump 在恢复数据期间包含临时禁用目标表上触发器的命令。如果您在表上有参照完整性检查或其他触发器,但不想在数据恢复期间调用它们,请使用此选项。

目前,为 --disable-triggers 发出的命令必须以超级用户身份执行。因此,您还应使用 -S 指定超级用户名,或者最好注意以超级用户身份启动生成的脚本。

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

--enable-row-security

此选项仅在转储具有行安全策略的表的内容时相关。默认情况下,pg_dumprow_security 设置为关闭,以确保从表中转储所有数据。如果用户没有足够的权限绕过行安全策略,则会引发错误。此参数指示 pg_dumprow_security 设置为开启,从而允许用户转储他们有权访问的表内容的各个部分。

请注意,如果您使用此选项,您可能还希望转储为 INSERT 格式,因为 COPY FROM 在恢复期间不支持行安全策略。

--exclude-extension=模式

不要转储与 模式 匹配的任何扩展。模式的解释方式与 -e 相同。--exclude-extension 可以多次给出,以排除与多个模式中的任何一个匹配的扩展。

当同时给出 -e--exclude-extension 时,行为是仅转储至少匹配一个 -e 开关但不匹配任何 --exclude-extension 开关的扩展。如果 --exclude-extension 出现在没有 -e 的情况下,那么与 --exclude-extension 匹配的扩展将从正常的转储中排除。

--exclude-table-and-children=模式

这与 -T/--exclude-table 选项相同,但它还排除了与 模式 匹配的表及其任何分区或继承的子表。

--exclude-table-data=模式

不要转储与 模式 匹配的任何表的任何数据。模式的解释方式与 -t 相同。--exclude-table-data 可以多次给出,以排除与多个模式中的任何一个匹配的表。此选项对于在需要某个特定表的定义但不需要其中数据时非常有用。

要排除数据库中所有表的 D数据,请参阅 --schema-only--statistics-only

--exclude-table-data-and-children=模式

这与 --exclude-table-data 选项相同,但它还排除了与 模式 匹配的表以及这些表的任何分区或继承的子表的数据。

--extra-float-digits=数字

转储浮点数据时使用指定的 extra_float_digits 值,而不是最大可用精度。常规转储以用于备份目的不应使用此选项。

--filter=filename

指定一个文件名,从中读取要包含或排除在转储中的对象的模式。模式的解释方式与相应选项相同:-t/--table--table-and-children-T/--exclude-table--exclude-table-and-children 用于表,-n/--schema-N/--exclude-schema 用于模式,--include-foreign-data 用于外部服务器上的数据,--exclude-table-data--exclude-table-data-and-children 用于表数据,以及 -e/--extension--exclude-extension 用于扩展。要从 STDIN 读取,请使用 - 作为文件名。--filter 选项可以与上述用于包含或排除对象的选项结合使用,并且可以多次指定以用于多个过滤器文件。

文件每行列出一个对象模式,格式如下

{ include | exclude } { extension | foreign_data | table | table_and_children | table_data | table_data_and_children | schema } PATTERN

第一个关键字指定要过滤的对象是否要包含或排除。第二个关键字指定要使用模式过滤的对象类型

  • extension:扩展。此功能类似于 -e/--extension--exclude-extension 选项。

  • foreign_data:外部服务器上的数据。此功能类似于 --include-foreign-data 选项。此关键字只能与 include 关键字一起使用。

  • table:表。此功能类似于 -t/--table-T/--exclude-table 选项。

  • table_and_children:表,包括任何分区或继承的子表。此功能类似于 --table-and-children--exclude-table-and-children 选项。

  • table_data:匹配 模式 的任何表的表数据。此功能类似于 --exclude-table-data 选项。此关键字只能与 exclude 关键字一起使用。

  • table_data_and_children:匹配 模式 的任何表的表数据,以及这些表的任何分区或继承的子表的数据。此功能类似于 --exclude-table-data-and-children 选项。此关键字只能与 exclude 关键字一起使用。

  • schema:模式。此功能类似于 -n/--schema-N/--exclude-schema 选项。

# 开头的行被视为注释并被忽略。注释也可以放在对象模式行之后。空行也被忽略。有关如何在模式中进行引用的信息,请参见 模式

示例文件列在下面的 示例 部分。

--if-exists

使用 DROP ... IF EXISTS 命令来删除 --clean 模式中的对象。这会抑制可能报告的“不存在”错误。此选项仅在也指定了 --clean 时才有效。

--include-foreign-data=foreignserver

转储与 foreignserver 模式匹配的任何外部表的表数据。可以通过编写多个 --include-foreign-data 开关来选择多个外部服务器。此外,foreignserver 参数被解释为与 psql\d 命令使用的规则相同的模式(请参阅 模式),因此通过在模式中写入通配符也可以选择多个外部服务器。使用通配符时,请务必引用模式(如果需要),以防止 shell 扩展通配符;请参阅下面的 示例。唯一例外是禁止空模式。

注意

--include-foreign-data 中使用通配符可能会导致访问意外的外部服务器。此外,为了安全地使用此选项,请确保命名的服务器必须拥有受信任的所有者。

注意

当指定 --include-foreign-data 时,pg_dump 不会检查外部表是否可写。因此,无法保证外部表的转储结果能够成功恢复。

--inserts

INSERT 命令(而不是 COPY)的形式转储数据。这将使恢复速度非常慢;它主要用于制作可以加载到非 PostgreSQL 数据库中的转储。恢复期间的任何错误只会导致有问题的 INSERT 中的行丢失,而不是整个表内容丢失。请注意,如果重新排列了列顺序,恢复可能会完全失败。--column-inserts 选项对于列顺序更改是安全的,尽管速度会更慢。

--load-via-partition-root

在转储表分区的 D数据时,使 COPYINSERT 语句指向包含它的分区层次结构的根,而不是分区本身。这会导致在加载数据时为每一行重新确定适当的分区。当在行不总是落入与原始服务器相同的分区中的服务器上恢复数据时,这可能很有用。例如,如果分区列是 text 类型,并且两个系统对用于对分区列进行排序的排序规则有不同的定义,则可能会发生这种情况。

--lock-wait-timeout=超时

不要永远等待在转储开始时获取共享表锁。相反,如果在指定的 超时 内无法锁定表,则失败。超时可以是 SET statement_timeout 接受的任何格式。(允许的格式因您从中转储的服务器版本而异,但所有版本都接受以毫秒为单位的整数。)

--no-comments

不要转储 COMMENT 命令。

--no-data

不要转储 D数据。

--no-policies

不要转储行安全策略。

--no-publications

不要转储发布。

--no-schema

不要转储模式(数据定义)。

--no-security-labels

不要转储安全标签。

--no-statistics

不要转储统计信息。这是默认行为。

--no-subscriptions

不要转储订阅。

--no-sync

默认情况下,pg_dump 将等待所有文件安全地写入磁盘。此选项导致 pg_dump 在不等待的情况下返回,这更快,但意味着后续的操作系统崩溃可能会使转储损坏。通常,此选项对于测试很有用,但不应在从生产安装转储数据时使用。

--no-table-access-method

不输出用于选择表访问方法的命令。使用此选项,所有对象都将使用恢复期间的默认表访问方法创建。

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

--no-tablespaces

不要输出选择表空间的命令。使用此选项,所有对象都将在恢复期间默认的表空间中创建。

当发出归档(非文本)输出文件时,此选项将被忽略。对于归档格式,可以在调用 pg_restore 时指定该选项。

--no-toast-compression

不要输出设置TOAST压缩方法的命令。使用此选项,所有列都将以默认压缩设置进行恢复。

--no-unlogged-table-data

不要转储未记录表和序列的内容。此选项对是否转储表和序列定义(模式)没有影响;它仅抑制转储表和序列 D数据。从备用服务器转储时,未记录表和序列中的 D数据始终被排除。

--on-conflict-do-nothing

ON CONFLICT DO NOTHING 添加到 INSERT 命令。此选项无效,除非还指定了 --inserts--column-inserts--rows-per-insert

--quote-all-identifiers

强制引用所有标识符。当从 PostgreSQL 主版本不同于 pg_dump 的服务器转储数据库时,或者当输出旨在加载到不同主版本的服务器时,建议使用此选项。默认情况下,pg_dump 仅引用其自身主版本中的保留字标识符。这有时会在处理具有略有不同的保留字集的其他版本服务器时导致兼容性问题。使用 --quote-all-identifiers 可以防止此类问题,但代价是转储脚本更难阅读。

--restrict-key=restrict_key

使用提供的字符串作为转储输出中的 psql \restrict 键。这只能为纯文本转储指定,即当 --format 设置为 plain 或省略 --format 选项时。如果未指定 restrict 键,pg_dump 将在需要时生成一个随机键。键只能包含字母数字字符。

此选项主要用于测试目的和其他需要可重复输出(例如,比较转储文件)的场景。不建议常规使用,因为带有密钥预知能力的恶意服务器可能能够注入任意代码,这些代码将在运行 psql 并使用转储输出的机器上执行。

--rows-per-insert=行数

INSERT 命令(而不是 COPY)的形式转储数据。控制每个 INSERT 命令的最大行数。指定的值必须是大于零的数字。恢复期间的任何错误只会导致有问题的 INSERT 中的行丢失,而不是整个表内容丢失。

--section=节名

仅转储命名节。节名可以是 pre-datadatapost-data。可以多次指定此选项以选择多个节。默认是转储所有节。

数据节包含实际表数据、大对象内容、序列值以及表、物化视图和外部表的统计信息。后数据项包括索引、触发器、规则、索引统计信息以及除已验证的检查和非空约束之外的约束的定义。预数据项包括所有其他数据定义项。

--sequence-data

在转储中包含序列数据。这是默认行为,除非指定了 --no-data--schema-only--statistics-only

--serializable-deferrable

使用 serializable 事务进行转储,以确保使用的快照与后续数据库状态一致;但通过等待事务流中的一个点来做到这一点,这样就不会有转储失败或导致其他事务回滚的风险 serialization_failure。有关事务隔离和并发控制的更多信息,请参阅 第 13 章

此选项对于仅用于灾难恢复的转储没有好处。它可能有助于用于加载数据库副本以进行报告或其他只读负载共享的转储,同时原始数据库继续被更新。没有它,转储可能反映一个与任何事务的串行执行都不一致的状态。例如,如果使用批处理处理技术,一个批次在转储中可能显示为已关闭,但批次中的所有项都没有出现。

如果没有活动读写事务在 pg_dump 启动时激活,此选项将没有区别。如果存在活动读写事务,转储的开始可能会延迟 indeterminate 时间。一旦运行,无论是否有开关,性能都是相同的。

--snapshot=快照名

在对数据库进行转储时,使用指定的同步快照(请参阅 表 9.100 以获取更多详细信息)。

此选项对于需要将转储与逻辑复制槽(请参阅 第 47 章)或与并发会话同步非常有用。

在并行转储的情况下,将使用此选项定义的快照名称,而不是获取新快照。

--statistics

转储统计信息。

--statistics-only

仅转储统计信息,而不转储模式(数据定义)或 D数据。转储表、物化视图、外部表和索引的统计信息。

--strict-names

要求每个扩展(-e/--extension)、模式(-n/--schema)和表(-t/--table)模式都能匹配数据库中至少一个要转储的扩展/模式/表。这同样适用于与 --filter 一起使用的过滤器。请注意,如果任何扩展/模式/表模式均未找到匹配项,pg_dump 将生成一个错误,即使没有 --strict-names

此选项对 --exclude-extension-N/--exclude-schema-T/--exclude-table--exclude-table-data 没有影响。未能匹配任何对象的排除模式不被视为错误。

--sync-method=method

当设置为 fsync(默认值)时,pg_dump --format=directory 将递归打开并同步归档目录中的所有文件。

在 Linux 上,可以使用 syncfs 来要求操作系统同步包含归档目录的整个文件系统。有关使用 syncfs 时需要注意的注意事项,请参阅 recovery_init_sync_method

当使用 --no-sync--format 未设置为 directory 时,此选项无效。

--table-and-children=模式

这与 -t/--table 选项相同,但它还包括与 模式 匹配的表及其任何分区或继承的子表。

--use-set-session-authorization

输出 SQL 标准 SET SESSION AUTHORIZATION 命令,而不是 ALTER OWNER 命令来确定对象所有权。这使得转储更符合标准,但根据转储对象历史,可能无法正确恢复。此外,使用 SET SESSION AUTHORIZATION 的转储肯定需要超级用户权限才能正确恢复,而 ALTER OWNER 需要较低的权限。

-?
--help

显示有关 pg_dump 命令行参数的帮助,然后退出。

以下命令行选项控制数据库连接参数。

-d dbname
--dbname=dbname

指定要连接的数据库名称。这等同于在命令行上将 数据库名 指定为第一个非选项参数。数据库名 可以是 连接字符串。如果是这样,连接字符串参数将覆盖任何冲突的命令行选项。

-h 主机
--host=主机

指定服务器运行所在计算机的主机名。如果值以斜杠开头,则将其用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量(如果已设置),否则尝试 Unix 域套接字连接。

-p 端口
--port=端口

指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认值为 PGPORT 环境变量(如果已设置),或者编译时默认值。

-U 用户名
--username=用户名

要连接的用户。:

-w
--no-password

绝不发出密码提示。如果服务器需要密码身份验证且密码不可用(例如通过 .pgpass 文件),则连接尝试将失败。此选项在没有用户在场输入密码的批处理作业和脚本中很有用。

-W
--password

强制 pg_dump 在连接到数据库之前提示输入密码。

此选项永远不是必需的,因为如果服务器要求密码认证,pg_dump 会自动提示输入密码。但是,pg_dump 会浪费一次连接尝试来确定服务器需要密码。在某些情况下,键入 -W 以避免额外的连接尝试是值得的。

--role=rolename

指定一个角色名,用于创建转储。此选项会导致 pg_dump 在连接到数据库后发出 SET ROLE 角色名 命令。当认证用户(由 -U 指定)缺乏 pg_dump 所需的权限,但可以切换到具有所需权限的角色时,此选项很有用。一些安装有禁止直接以超级用户身份登录的策略,使用此选项可以在不违反策略的情况下进行转储。

环境变量

PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER

默认连接参数。

PG_COLOR

指定是否在诊断消息中使用颜色。可能的值为 alwaysautonever

此实用程序以及大多数其他 PostgreSQL 实用程序也使用 libpq 支持的环境变量(请参阅 第 32.15 节)。

诊断

pg_dump 内部执行 SELECT 语句。如果您在运行 pg_dump 时遇到问题,请确保您能够使用,例如 psql 选择数据库中的信息。此外,libpq 前端库使用的任何默认连接设置和环境变量都将适用。

通常,pg_dump 的数据库活动由累积统计信息系统收集。如果这是不可取的,您可以通过 PGOPTIONSALTER USER 命令将参数 track_counts 设置为 false。

注释

如果您的数据库集群在 template1 数据库中有任何本地添加项,请务必将 pg_dump 的输出还原到一个完全空的数据库;否则,由于重复定义添加的对象,您很可能会遇到错误。要创建一个不包含任何本地添加项的空数据库,请从 template0 而不是 template1 复制,例如

CREATE DATABASE foo WITH TEMPLATE template0;

当选择了不包含模式的转储,并且使用了 --disable-triggers 选项时,pg_dump 会发出命令在插入 D数据之前禁用用户表上的触发器,然后在 D数据插入之后发出命令重新启用它们。如果在中间停止恢复,系统目录可能会处于错误的状态。

如果指定了 --statisticspg_dump 将在生成的转储文件中包含大部分优化器统计信息。但是,某些统计信息可能不包含在内,例如使用 CREATE STATISTICS 显式创建的统计信息或扩展添加的自定义统计信息。因此,在从转储文件恢复后运行 ANALYZE 以确保最佳性能可能很有用;有关更多信息,请参阅 第 24.1.3 节第 24.1.6 节

因为 pg_dump 用于将 D数据传输到较新版本的 PostgreSQL,所以 pg_dump 的输出可以加载到比 pg_dump 版本更新的 PostgreSQL 服务器版本中。pg_dump 也可以转储比其自身版本旧的 PostgreSQL 服务器。(目前支持版本 9.2 及以上版本。)但是,pg_dump 不能转储比其自身主版本新的 PostgreSQL 服务器;它会拒绝尝试,以免造成无效转储。此外,不能保证 pg_dump 的输出可以加载到旧主版本的服务器中——即使转储是从该版本服务器获取的。将转储文件加载到旧服务器可能需要手动编辑转储文件以删除旧服务器无法识别的语法。在跨版本情况下,建议使用 --quote-all-identifiers 选项,因为它可以防止不同 PostgreSQL 版本中保留字列表不同而引起的问题。

在转储逻辑复制订阅时,pg_dump 将生成 CREATE SUBSCRIPTION 命令,这些命令使用 connect = false 选项,以便恢复订阅不会建立远程连接以创建复制槽或进行初始表复制。这样,就可以在不需要网络访问远程服务器的情况下恢复转储。然后由用户以适当的方式重新激活订阅。如果涉及的主机已更改,则可能需要更改连接信息。在开始新的完整表复制之前,截断目标表也可能是合适的。如果用户打算在刷新期间复制初始 D数据,则必须使用 two_phase = false 创建槽。初始同步之后,如果订阅最初是使用 two_phase = true 选项创建的,则订阅方会自动启用 two_phase 选项。

通常建议在从纯文本 pg_dump 脚本恢复数据库时使用 -X--no-psqlrc)选项,以确保干净的恢复过程并防止与非默认 psql 配置发生潜在冲突。

示例

要转储名为 mydb 的数据库到 SQL 脚本文件

$ pg_dump mydb > db.sql

要将这样的脚本重新加载到名为 newdb 的(刚创建的)数据库中

$ psql -X -d newdb -f db.sql

要将数据库转储到自定义格式归档文件

$ pg_dump -Fc mydb > db.dump

要将数据库转储到目录格式归档

$ pg_dump -Fd mydb -f dumpdir

以 5 个辅助作业并行转储数据库到目录格式归档

$ pg_dump -Fd mydb -j 5 -f dumpdir

要将归档文件重新加载到名为 newdb 的(刚创建的)数据库中

$ pg_restore -d newdb db.dump

将归档文件重新加载到与转储时相同的数据库中,丢弃该数据库的当前内容

$ pg_restore -d postgres --clean --create db.dump

要转储单个名为 mytab 的表

$ pg_dump -t mytab mydb > db.sql

要转储 detroit 模式下所有名称以 emp 开头的表,但不包括名为 employee_log 的表

$ pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql

要转储所有名称以 eastwest 开头并以 gsm 结尾的模式,但排除名称中包含单词 test 的任何模式

$ pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql

相同,使用正则表达式表示法合并开关

$ pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql

要转储除名称以 ts_ 开头的表之外的所有数据库对象

$ pg_dump -T 'ts_*' mydb > db.sql

要在 -t 和相关开关中指定大写或混合大小写的名称,您需要用双引号括起名称;否则它将被折叠成小写(请参阅 模式)。但是双引号对 shell 来说是特殊的,因此反过来它们也必须被引用。因此,要转储一个混合大小写名称的表,您需要类似以下内容:

$ pg_dump -t "\"MixedCaseName\"" mydb > mytab.sql

要转储所有名称以 mytable 开头的表,但排除表 mytable2,请指定一个过滤器文件 filter.txt,如下所示:

include table mytable*
exclude table mytable2
$ pg_dump --filter=filter.txt mydb > db.sql

另请参阅

pg_dumpall, pg_restore, psql

提交更正

如果您在文档中发现任何不正确、与您对特定功能的体验不符或需要进一步说明的内容,请使用 此表单 报告文档问题。