Note

pg_dump

pg_dump —将 PostgreSQL 数据库提取到脚本文件或其他归档文件中

Synopsis

pg_dump [ connection-option ...] [ option ...] [ dbname ]

Description

pg_dump 是用于备份 PostgreSQL 数据库的 Util。即使同时使用数据库，它也会进行一致的备份。 pg_dump 不会阻止其他用户访问数据库(读取器或写入器)。

pg_dump 只转储一个数据库。要备份群集中所有数据库通用的全局对象(例如角色和表空间)，请使用pg_dumpall。

转储可以脚本或存档文件格式输出。脚本转储是纯文本文件，其中包含将数据库重建到保存时所处状态所需的 SQL 命令。要从此类脚本还原，请将其提供给psql。脚本文件甚至可用于在其他机器和其他体系结构上重建数据库；进行了一些修改，甚至在其他 SQL 数据库产品上也是如此。

备用存档文件格式必须与pg_restore一起使用才能重建数据库。它们允许 pg_restore 对恢复什么有选择性，甚至可以在恢复之前对项目进行重新排序。存档文件格式设计为可跨体系结构移植。

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

在运行 pg_dump 时，应该检查输出是否有任何警告(按标准错误打印)，尤其是考虑到以下列出的限制。

Options

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

• dbname

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

• -a
--data-only

  • 仅转储数据，而不转储模式(数据定义)。表数据，大对象和序列值将被转储。

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

• -b
--blobs

  • 在转储中包括大对象。这是默认行为，除非指定了--schema，--table或--schema-only。因此，-b开关仅用于将大型对象添加到已请求特定模式或表的转储中。请注意，blob 被视为数据，因此，当使用--data-only 时将包括这些 blob，但在使用--schema-only 时则不包括。

• -B
--no-blobs

  • 排除转储中的大对象。

同时提供-b和-B时，行为是输出大对象，转储数据时，请参见-b文档。

• -c
--clean

  • 在输出用于创建数据库对象的命令之前，先输出命令以清理(删除)数据库对象。 (除非还指定了--if-exists，否则如果目标数据库中不存在任何对象，则还原可能会生成一些无害的错误消息.)

此选项仅对纯文本格式有意义。对于存档格式，可以在调用pg_restore时指定选项。

• -C
--create

  • 从命令开始输出，以创建数据库本身并重新连接到创建的数据库。 (使用这种形式的脚本，在运行脚本之前连接到目标安装中的哪个数据库都没有关系.)如果还指定了--clean，则脚本将删除并重新创建目标数据库，然后再重新连接至该目标数据库。

此选项仅对纯文本格式有意义。对于存档格式，可以在调用pg_restore时指定选项。

• -E encoding
--encoding=encoding

  • 以指定的字符集编码创建转储。默认情况下，转储以数据库编码创建。 (获得相同结果的另一种方法是将PGCLIENTENCODING环境变量设置为所需的转储编码.)

• -f file
--file=file

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

• -F format
--format=format

  • 选择输出格式。 * format *可以是以下之一：

• p
plain

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

  • c
custom

    • 输出适合 Importing 到 pg_restore 的自定义格式的存档。与目录输出格式一起使用时，这是最灵活的输出格式，因为它允许在还原过程中手动选择和重新排序已归档的项目。默认情况下，此格式也被压缩。

  • d
directory

    • 输出适合于 Importingpg_restore 的目录格式 Files。这将创建一个目录，其中包含要转储的每个表和 blob 的一个文件，以及一个所谓的目录文件，该表以 pg_restore 可以读取的机器可读格式描述了转储的对象。目录格式归档文件可以使用标准的 Unix 工具进行处理。例如，可以使用 gzip 工具压缩未压缩 Files 中的文件。默认情况下，此格式为压缩格式，并且还支持并行转储。

  • t
tar

    • 输出适合于 Importingpg_restore 的tar格式 Files。 tar 格式与目录格式兼容：提取 tar 格式的存档会生成有效的目录格式的存档。但是，tar 格式不支持压缩。同样，当使用 tar 格式时，在还原过程中不能更改表数据项的相对 Sequences。

• -j njobs
--jobs=njobs

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

pg_dump 将打开* njobs * 1 个与数据库的连接，因此请确保max_connections设置足够高以容纳所有连接。

在运行并行转储时请求对数据库对象的排他锁可能导致转储失败。原因是 pg_dump 主进程对工作进程稍后将要转储的对象请求共享锁，以确保没有人删除它们并在转储运行时使它们消失。如果另一个 Client 端随后请求对表进行排他锁，则该锁将不会被授予，但会排队 await 主进程的共享锁被释放。因此，对该表的任何其他访问也不会被授予，并且将在排他锁定请求之后排队。这包括尝试转储表的工作进程。如果没有任何预防措施，这将是典型的僵局情况。为了检测到该冲突，pg_dump worker 进程使用NOWAIT选项请求另一个共享锁。如果未向工作进程授予该共享锁，则其他人在此期间必须已请求独占锁，并且无法 continue 进行转储，因此 pg_dump 别无选择，只能中止转储。

为了保持一致的备份，数据库服务器需要支持同步快照，这是 PostgreSQL 9.2 中针对主服务器引入的功能，针对备用服务器引入了 10 的功能。使用此功能，即使数据库 Client 端使用不同的连接，也可以确保他们看到相同的数据集。 pg_dump -j使用多个数据库连接；它通过主进程一次连接到数据库，并针对每个工作者作业再次连接到数据库。如果没有同步快照功能，则不能保证不同的工作作业在每个 Connecting 都看到相同的数据，这可能导致备份不一致。

如果要运行 9.2 之前版本服务器的并行转储，则需要确保从主服务器连接到数据库到最后一个工作者作业连接到数据库之间的时间里，数据库内容没有变化。最简单的方法是在开始备份之前，停止所有访问数据库的数据修改过程(DDL 和 DML)。当针对 9.2 之前的 PostgreSQL 服务器运行pg_dump -j时，还需要指定--no-synchronized-snapshots参数。

• -n schema
--schema=schema

  • 仅转储匹配* schema 的模式；这将同时选择模式本身及其所有包含的对象。如果未指定此选项，则将转储目标数据库中的所有非系统架构。通过写入多个-n开关可以选择多个模式。同样， schema *参数根据 psql 的\d命令(参见Patterns)所使用的相同规则解释为模式，因此也可以通过在模式中写入通配符来选择多个模式。使用通配符时，如果需要，请小心引用该模式，以防止 Shell 扩展通配符。参见Examples。

• -N schema
--exclude-schema=schema

  • 不要转储与* schema *模式匹配的任何模式。根据与-n相同的规则解释该模式。可以多次提供-N以排除与多种模式中的任何一种匹配的模式。

当同时提供-n和-N时，行为是仅转储与至少一个-n开关匹配但不与-N开关匹配的架构。如果出现-N时没有-n，则将与-N匹配的模式从正常转储中排除。

• -o
--oids

  • 转储对象标识符(OID)作为每个表的数据的一部分。如果您的应用程序以某种方式(例如，以外键约束)引用 OID 列，请使用此选项。否则，不应使用此选项。

• -O
--no-owner

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

此选项仅对纯文本格式有意义。对于存档格式，可以在调用pg_restore时指定选项。

• -R
--no-reconnect

  • 此选项已过时，但仍向后兼容。

• -s
--schema-only

  • 仅转储对象定义(模式)，而不转储数据。

此选项与--data-only相反。它类似于--section=pre-data --section=post-data，但由于历史原因不同。

(请勿将其与--schema选项混淆，该选项以不同的含义使用“模式”一词.)

要仅排除数据库中一部分表的表数据，请参见--exclude-table-data。

• -S username
--superuser=username

  • 指定禁用触发器时要使用的超级用户名。仅在使用--disable-triggers时才有意义。 (通常，最好不要这样做，而以超级用户身份启动生成的脚本.)

• -t table
--table=table

  • 仅转储名称匹配* table 的表。为此，“表”包括视图，实例化视图，序列和外部表。通过写入多个-t开关可以选择多个表。同样， table *参数根据 psql 的\d命令(请参阅Patterns)所使用的相同规则解释为模式，因此也可以通过在模式中写入通配符来选择多个表。使用通配符时，如果需要，请小心引用该模式，以防止 Shell 扩展通配符。参见Examples。

使用-t时-n和-N开关无效，因为-t选择的表将被转储，而与那些开关无关，并且非表对象也将不被转储。

• -T table
--exclude-table=table

  • 不要转储任何与* table *模式匹配的表。根据与-t相同的规则解释该模式。可以多次提供-T以排除与多种模式中的任何一种匹配的表。

当同时提供-t和-T时，行为是仅转储与至少一个-t开关匹配但不与-T开关匹配的表。如果出现-T时没有-t，则与-T匹配的表将从正常转储中排除。

• -v
--verbose

  • 指定详细模式。这将导致 pg_dump 向转储文件输出详细的对象 Comments 和开始/停止时间，并将消息显示为标准错误。

• -V
--version

  • 打印 pg_dump 版本并退出。

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

  • 防止转储访问权限(授予/撤销命令)。

• -Z 0..9
--compress=0..9

  • 指定要使用的压缩级别。零表示无压缩。对于自定义存档格式，此选项指定压缩单个表数据段，并且默认设置为中等压缩。对于纯文本输出，设置非零压缩级别会使整个输出文件被压缩，就好像它是通过 gzip 馈送的一样。但默认设置为不压缩。 tar 存档格式当前根本不支持压缩。

• --binary-upgrade

  • 此选项供就地升级 Util 使用。不建议或不支持将其用于其他目的。该选项的行为在将来的版本中可能会更改，恕不另行通知。

• --column-inserts
--attribute-inserts

  • 将数据作为具有明确列名(INSERT INTO table (column, ...) VALUES ...)的INSERT命令转储。这会使恢复非常缓慢。它主要用于制作可以装入非 PostgreSQL 数据库的转储。但是，由于此选项为每一行生成一个单独的命令，因此在重新加载一行时发生错误只会导致该行丢失，而不是整个表内容丢失。

• --disable-dollar-quoting

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

• --disable-triggers

  • 仅当创建仅数据转储时，此选项才相关。它指示 pg_dump 包含一些命令，以在重新加载数据时临时禁用目标表上的触发器。如果对数据重新加载期间不想调用的表具有参照完整性检查或其他触发器，请使用此选项。

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

此选项仅对纯文本格式有意义。对于存档格式，可以在调用pg_restore时指定选项。

• --enable-row-security

  • 仅当转储具有行安全性的表的内容时，此选项才相关。默认情况下，pg_dump 会将row_security设置为 off，以确保从表中转储所有数据。如果用户没有足够的特权绕过行安全性，那么将引发错误。该参数指示 pg_dump 将row_security设置为 on，从而允许用户转储他们有权访问的表的内容部分。

请注意，如果当前使用此选项，则可能还希望转储为INSERT格式，因为还原期间的COPY FROM不支持行安全性。

• --exclude-table-data=table

  • 不要为与* table *模式匹配的任何表转储数据。根据与-t相同的规则解释该模式。可以多次提供--exclude-table-data以排除与多种模式中的任何一种匹配的表。当您需要特定表的定义时，即使您不需要其中的数据，此选项也很有用。

要排除数据库中所有表的数据，请参见--schema-only。

• --if-exists

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

• --inserts

  • 将数据转储为INSERT个命令(而不是COPY)。这会使恢复非常缓慢。它主要用于制作可以装入非 PostgreSQL 数据库的转储。但是，由于此选项为每一行生成一个单独的命令，因此在重新加载一行时发生错误只会导致该行丢失，而不是整个表内容丢失。请注意，如果您重新排列了列 Sequences，则还原可能会完全失败。 --column-inserts选项可以防止更改列 Sequences，尽管速度甚至更慢。

• --lock-wait-timeout=timeout

  • 不要在转储开始时永远 await 获取共享表锁。如果无法锁定指定* timeout *中的表，则失败。可以以SET statement_timeout接受的任何格式指定超时。 (允许的格式因要转储的服务器版本而异，但所有版本均接受整数毫秒)。

• --no-publications

  • 不要转储出版物。

• --no-security-labels

  • 不要丢弃安全标签。

• --no-subscriptions

  • 不要转储订阅。

• --no-sync

  • 默认情况下，pg_dump将 await 所有文件安全地写入磁盘。此选项使pg_dump不 await 就返回，这更快，但是这意味着随后的 os 崩溃可能会使转储损坏。通常，此选项对于测试很有用，但在从生产安装中转储数据时不应使用。

• --no-synchronized-snapshots

  • 此选项允许在 9.2 之前的服务器上运行pg_dump -j，有关更多详细信息，请参见-j参数的文档。

• --no-tablespaces

  • 不输出命令以选择表空间。使用此选项，将在还原期间的默认表空间中创建所有对象。

此选项仅对纯文本格式有意义。对于存档格式，可以在调用pg_restore时指定选项。

• --no-unlogged-table-data

  • 不要转储未记录表的内容。此选项对是否转储表定义(模式)没有影响。它仅禁止转储表数据。从备用服务器转储时，始终排除未记录表中的数据。

• --quote-all-identifiers

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

• --section=sectionname

  • 仅转储命名部分。部分名称可以是pre-data，data或post-data。可以多次指定此选项以选择多个部分。默认为转储所有部分。

数据部分包含实际表数据，大对象内容和序列值。数据后项目包括索引，触发器，规则和约束的定义，而不是经过验证的检查约束。前置数据项包括所有其他数据定义项。

• --serializable-deferrable

  • 对转储使用serializable事务，以确保使用的快照与以后的数据库状态一致；但这要通过 await 事务流中不会出现异常的点来完成，这样就不会存在转储失败或导致其他事务以serialization_failure回滚的风险。有关事务隔离和并发控制的更多信息，请参见Chapter 13。

此选项对仅用于灾难恢复的转储无益。这对于在原始数据库 continue 更新的同时用于装载数据库副本以进行报告或其他只读负载共享的转储很有用。没有它，转储可能会反映与最终提交的事务的任何串行执行都不相符的状态。例如，如果使用批处理技术，则在转储中批次可能显示为已关闭，而批次中的所有项目都不会出现。

如果在启动 pg_dump 时没有活动的读写事务，则此选项没有任何区别。如果读写事务处于活动状态，则转储的开始可能会延迟不确定的时间长度。运行后，无论有无切换，性能都是相同的。

• --snapshot=snapshotname

  • 转储数据库时，请使用指定的同步快照(有关更多详细信息，请参见Table 9.82)。

当需要将转储与逻辑复制插槽(请参见Chapter 48)或并发会话同步时，此选项很有用。

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

• --strict-names

  • 要求每个架构(-n/--schema)和表(-t/--table)限定符至少匹配要转储的数据库中的一个架构/表。请注意，如果没有一个模式/表限定符找到匹配项，即使没有--strict-names，pg_dump 也会产生一个错误。

此选项对-N/--exclude-schema，-T/--exclude-table或--exclude-table-data无效。无法匹配任何对象的排除模式不视为错误。

• --use-set-session-authorization

  • 输出 SQL 标准的SET SESSION AUTHORIZATION命令而不是ALTER OWNER命令来确定对象所有权。这使转储更加符合标准，但是根据转储中对象的历史记录，可能无法正确还原。同样，使用SET SESSION AUTHORIZATION进行转储肯定需要超级用户权限才能正确还原，而ALTER OWNER则需要较少的权限。

• -?
--help

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

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

• -d dbname
--dbname=dbname

  • 指定要连接的数据库的名称。这等效于在命令行上将* dbname *指定为第一个非选项参数。

如果此参数包含=符号或以有效的 URI 前缀(postgresql://或postgres://)开头，则将其视为* conninfo *字符串。有关更多信息，请参见Section 33.1。

• -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_dump 在连接数据库之前提示 Importing 密码。

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

• --role=rolename

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

Environment

• PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER

  • 默认连接参数。

与大多数其他 PostgreSQLUtil 一样，该 Util 也使用 libpq 支持的环境变量(请参见Section 33.14)。

Diagnostics

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

pg_dump 的数据库活动通常由统计信息收集器收集。如果不希望这样，可以通过PGOPTIONS或ALTER USER命令将参数track_counts设置为 false。

Notes

如果您的数据库集群对template1数据库进行了本地添加，请注意将 pg_dump 的输出还原到一个 true 的空数据库中；否则，由于添加对象的重复定义，您很可能会出错。要创建没有任何本地添加的空数据库，请从template0而不是template1复制，例如：

CREATE DATABASE foo WITH TEMPLATE template0;

选择仅数据转储并使用选项--disable-triggers时，pg_dump 发出命令，以在插入数据之前禁用用户表上的触发器，然后发出命令，以在插入数据后重新启用它们。如果还原在中间停止，则系统目录可能处于错误状态。

pg_dump 生成的转储文件不包含优化程序用于制定查询计划决策的统计信息。因此，从转储文件还原后运行ANALYZE是明智的，以确保最佳性能。有关更多信息，请参见Section 24.1.3和Section 24.1.6。转储文件也不包含任何ALTER DATABASE ... SET命令； pg_dumpall和数据库用户以及其他安装范围的设置一起转储了这些设置。

因为 pg_dump 用于将数据传输到 PostgreSQL 的较新版本，所以可以预期 pg_dump 的输出将加载到比 pg_dump 的版本新的 PostgreSQL 服务器版本中。 pg_dump 也可以从比它自己的版本旧的 PostgreSQL 服务器中转储。 (当前支持回到 8.0 版的服务器.)但是，pg_dump 不能从 PostgreSQL 服务器上转储比其主要版本更新的服务器。它将拒绝尝试，而不是冒险进行无效的转储。另外，不能保证 pg_dump 的输出可以加载到主版本较旧的服务器上-即使转储是从该版本的服务器上获取的也不行。将转储文件加载到较旧的服务器中可能需要手动编辑转储文件，以删除较旧的服务器无法理解的语法。在跨版本的情况下，建议使用--quote-all-identifiers选项，因为它可以防止由于不同 PostgreSQL 版本中的保留字列表不同而引起的问题。

转储逻辑复制订阅时，pg_dump 会生成使用connect = false选项的CREATE SUBSCRIPTION命令，因此恢复订阅不会构建用于创建复制插槽或初始表副本的远程连接。这样，可以还原转储而无需访问远程服务器的网络。然后由用户以合适的方式重新激活订阅。如果所涉及的主机已更改，则可能必须更改连接信息。在启动新的完整表副本之前，截断目标表也可能是适当的。

Examples

要将名为mydb的数据库转储到 SQL 脚本文件中，请执行以下操作：

$ pg_dump mydb > db.sql

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

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

要转储名为mytab的单个表：

$ pg_dump -t mytab mydb > db.sql

要在detroit模式中转储所有名称以emp开头的表，但名为employee_log的表除外：

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

转储名称以east或west开头并以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和相关的开关中指定大写或大小写混合的名称，您需要将名称双引号；否则它将被折叠为小写(请参阅Patterns)。但是双引号对于 shell 来说是特殊的，因此反过来必须使用双引号。因此，要转储具有大小写混合名称的单个表，您需要

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

See Also

pg_dumpall, pg_restore, psql