pg_dump

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

只转储数据，不转储模式（数据定义）或统计信息。会转储表数据、大对象和序列值。

此选项类似于指定 --section=data，但出于历史原因，两者并不完全相同。

在转储中包含大对象。除非指定了 --schema、--table、--schema-only、--statistics-only 或 --no-data，否则这是默认行为。因此，-b 开关只在已经请求了特定模式或表的转储中，需要把大对象再加回来时才有用。注意，大对象被视为数据，因此在使用 --data-only 时会包含，在使用 --schema-only 或 --statistics-only 时则不会包含。

在转储中排除大对象。

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

在输出创建这些对象的命令之前，先输出用于 DROP 所有被转储数据库对象的命令。当恢复要覆盖现有数据库时，此选项很有用。如果目标数据库中某些对象不存在，则在恢复期间会报告可忽略的错误信息，除非还指定了 --if-exists。

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

让输出以创建数据库本身并重新连接到新建数据库的命令开始。（使用这种形式的脚本时，在目标安装中先连接到哪个数据库再运行脚本都无关紧要。）如果还指定了 --clean，则脚本会在重新连接到目标数据库之前先删除并重新创建它。

使用 --create 时，输出还会包含该数据库的注释（如果有），以及该数据库特有的任何配置变量设置，也就是提及该数据库的任何 ALTER DATABASE ... SET ... 和 ALTER ROLE ... IN DATABASE ... SET ... 命令。除非指定了 --no-acl，否则数据库本身的访问权限也会被转储。

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

仅转储与pattern匹配的扩展。当未指定此选项时，将转储目标数据库中的所有非系统扩展。可以通过写多个-e开关来选择多个扩展。pattern 参数按照 psql 的 \d 命令所使用的同样规则进行解释（请参阅模式），因此也可以通过在模式中使用通配符来选择多个扩展。使用通配符时，如有需要请小心为模式加引号，以防止 shell 展开通配符。

由 pg_extension_config_dump 注册的任何配置关系，如果其所属扩展由 --extension 指定，也会包含在转储中。

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

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

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

以并行方式运行转储，同时转储 njobs 个表。此选项可能减少执行转储所需的时间，但也会增加数据库服务器的负载。只能在目录输出格式下使用此选项，因为只有这种输出格式允许多个进程同时写入数据。

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

在并行转储运行期间请求数据库对象上的排他锁，可能导致转储失败。原因是 pg_dump 的领导者进程会对稍后由工作进程转储的对象请求共享锁（ACCESS SHARE），以确保在转储运行期间没有人删除这些对象。如果另一个客户端随后请求某个表上的排他锁，该锁不会被授予，而是会排队等待领导者进程释放共享锁。于是，对该表的任何其他访问也都不会被授予，并会排在该排他锁请求之后，其中包括试图转储该表的工作进程。如果没有任何预防措施，这就会形成一个经典的死锁场景。为检测这种冲突，pg_dump 工作进程会使用 NOWAIT 选项再请求一个共享锁。如果工作进程拿不到这个共享锁，就说明这期间已经有人请求了排他锁，而此时已经无法继续转储，因此 pg_dump 只能中止转储。

要执行并行转储，数据库服务器需要支持同步快照。这一特性是在 PostgreSQL 9.2 中为主库引入的，在 10 中为备库引入。有了这个特性，数据库客户端即使使用不同连接，也能保证看到相同的数据集。pg_dump -j 会使用多个数据库连接：它会先由领导者进程连接数据库一次，然后每个工作任务再各连一次。若没有同步快照特性，就无法保证各个工作任务在各自连接中看到相同的数据，这可能导致备份不一致。

只转储匹配 pattern 的模式；这既会选择模式本身，也会选择其中包含的所有对象。未指定此选项时，将转储目标数据库中的所有非系统模式。可以通过写多个 -n 开关来选择多个模式。pattern 参数按照 psql 的 \d 命令所使用的同样规则进行解释（见模式），因此也可以通过在模式中使用通配符来选择多个模式。使用通配符时，如有需要请小心为模式加引号，以防止 shell 展开通配符；见下文的示例。

不转储任何匹配 pattern 的模式。该模式按照与 -n 相同的规则解释。-N 可以给出多次，以排除匹配所给模式中任意一个的模式。

当同时给出 -n 和 -N 时，其行为是只转储至少匹配一个 -n 开关但不匹配任何 -N 开关的模式。如果出现 -N 而没有 -n，那么匹配 -N 的模式会从原本的正常转储中排除。

不输出用于把对象所有权设置成与原始数据库一致的命令。默认情况下，pg_dump 会发出 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置新建数据库对象的所有权。除非脚本由超级用户（或拥有脚本中所有对象的同一用户）启动，否则这些语句会在运行脚本时报错。若要创建一个可由任意用户恢复、并让该用户拥有所有对象的脚本，请指定 -O。

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

这个选项已经过时，但仍然被接受以保持向后兼容性。

只转储对象定义（模式），不转储数据或统计信息。

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

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

要只排除数据库中某些表的表数据，请参见 --exclude-table-data。

指定在禁用触发器时要使用的超级用户名。这只在使用 --disable-triggers 时相关。（通常最好省略它，而是以超级用户身份运行生成的脚本。）

只转储名称匹配 pattern 的表。可以通过写多个 -t 开关来选择多个表。pattern 参数按照 psql 的 \d 命令所使用的同样规则进行解释（见模式），因此也可以通过在模式中使用通配符来选择多个表。使用通配符时，如有需要请小心为模式加引号，以防止 shell 展开通配符；见下文的示例。

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

使用 -t 时，-n 和 -N 选项不生效，因为 -t 选中的表无论如何都会被转储，而非表对象不会被转储。

不转储任何匹配 pattern 的表。该模式按照与 -t 相同的规则解释。-T 可以给出多次，以排除匹配所给模式中任意一个的表。

当同时给出 -t 和 -T 时，其行为是只转储至少匹配一个 -t 开关但不匹配任何 -T 开关的表。如果出现 -T 而没有 -t，那么匹配 -T 的表会从原本的正常转储中排除。

指定详细模式。这会使 pg_dump 将详细的对象注释、开始/停止时间写入转储文件，并把进度消息写到标准错误。重复该选项会让更多调试级别消息出现在标准错误中。

打印 pg_dump 的版本并退出。

不转储访问权限（grant/revoke 命令）。

指定要使用的压缩方法和/或压缩级别。压缩方法可以设置为 gzip、lz4、zstd 或 none（表示不压缩）。也可以选择指定压缩细节字符串。如果细节字符串是一个整数，则表示压缩级别；否则，它应是一个用逗号分隔的项列表，每项形如 keyword 或 keyword=value。目前支持的关键字是 level 和 long。

如果未指定压缩级别，将使用默认级别。如果只指定级别而未指定算法，则级别大于 0 时使用 gzip 压缩，级别为 0 时不压缩。

对于 custom 和 directory 归档格式，此选项指定对各个表数据段的压缩，默认是使用中等级别的 gzip 进行压缩。对于纯文本输出，设置非零压缩级别会导致整个输出文件被压缩，就像它经过了 gzip、lz4 或 zstd 一样；但默认是不压缩。使用 zstd 压缩时，long 模式可能提高压缩比，但代价是内存使用增加。

tar 归档格式目前完全不支持压缩。

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

将数据转储为带有显式列名的INSERT命令（INSERT INTO table (column, ...) VALUES ...）。这会使恢复变得非常缓慢；它主要用于生成可装入非 PostgreSQL 数据库的转储文件。恢复期间发生的任何错误都只会导致有问题的 INSERT 所包含的行丢失，而不会导致整个表内容丢失。

此选项禁用对函数体的美元引用，并强制用 SQL 标准字符串语法对它们加引号。

此选项只在创建包含数据但不包含模式的转储时才相关。它指示 pg_dump 在输出中包含一些命令，以便在恢复数据时临时禁用目标表上的触发器。如果这些表上存在不希望在数据恢复期间触发的引用完整性检查或其他触发器，请使用此选项。

目前，为 --disable-triggers 输出的这些命令必须由超级用户执行。因此，还应通过 -S 指定一个超级用户名，或者更好的做法是谨慎地以超级用户身份运行生成的脚本。

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

此选项只在转储启用了行安全的表内容时才相关。默认情况下，pg_dump 会将row_security设置为 off，以确保把表中的所有数据都转储出来。如果用户没有足够的权限绕过行安全，则会抛出错误。该参数会指示 pg_dump 改为将row_security设置为 on，从而允许用户只转储其有权访问的那部分表内容。

请注意，如果当前使用此选项，通常还会希望让转储采用 INSERT 格式，因为恢复期间的 COPY FROM 不支持行安全。

不转储任何匹配 pattern 的扩展。该模式按照与 -e 相同的规则解释。--exclude-extension 可以给出多次，以排除匹配所给模式中任意一个的扩展。

当同时给出 -e 和 --exclude-extension 时，其行为是只转储至少匹配一个 -e 开关、但不匹配任何 --exclude-extension 开关的扩展。如果 --exclude-extension 在没有 -e 的情况下出现，那么匹配 --exclude-extension 的扩展会从原本的正常转储中排除。

这与 -T/--exclude-table 选项相同，只是它还会排除匹配 pattern 的表的任何分区或继承子表。

不转储任何匹配 pattern 的表的数据。该模式按照与 -t 相同的规则解释。--exclude-table-data 可以给出多次，以排除匹配所给模式中任意一个的表。当需要某个特定表的定义、但不需要其中数据时，此选项很有用。

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

这与 --exclude-table-data 选项相同，只是它还会排除匹配 pattern 的表的任何分区或继承子表的数据。

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

指定一个文件名，从中读取要在转储中包含或排除的对象匹配模式。模式按照对应选项的同样规则解释：对于表，使用 -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

第一个关键字指定是包含还是排除与模式匹配的对象。第二个关键字指定要用该模式过滤的对象类型：

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

示例文件见下文的示例一节。

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

转储任何外部表的数据，只要其外部服务器匹配 foreignserver 模式。可以通过写多个 --include-foreign-data 开关来选择多个外部服务器。此外，foreignserver 参数按照 psql 的 \d 命令所使用的同样规则进行解释（见模式），因此也可以通过在模式中使用通配符来选择多个外部服务器。使用通配符时，如有需要请小心为模式加引号，以防止 shell 展开通配符；见下文的示例。唯一的例外是不允许空模式。

把数据转储为 INSERT 命令（而不是 COPY）。这会使恢复非常缓慢；它主要用于生成可装入非 PostgreSQL 数据库的转储。恢复期间发生的任何错误都只会导致有问题的 INSERT 所包含的行丢失，而不会导致整个表内容丢失。注意，如果重新安排了列顺序，恢复可能会彻底失败。--column-inserts 选项可以避免列顺序变化带来的问题，但速度更慢。

当为表分区转储数据时，让 COPY 或 INSERT 语句以包含该分区的分区层次结构根为目标，而不是以该分区本身为目标。这会导致在加载数据时为每一行重新确定适当的分区。当在另一台服务器上恢复数据，而行并不总是落在与原始服务器相同的分区中时，这可能很有用。例如，如果分区列是 text 类型，而两个系统对用于排序该分区列的排序规则定义不同，就可能发生这种情况。

在转储开始时，不要无限等待获取共享表锁。如果无法在指定的 timeout 内锁定某个表，就让转储失败。超时可以用 SET statement_timeout 接受的任意格式指定。（允许的格式因被转储源服务器的版本而异，但所有版本都接受以毫秒为单位的整数。）

不要转储 COMMENT 命令。

不要转储数据。

不要转储行安全性策略。

不要转储发布。

不要转储模式（数据定义）。

不要转储安全标签。

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

不要转储订阅。

默认情况下，pg_dump 会等待所有文件都被安全写入磁盘。该选项会使 pg_dump 立即返回而不等待，这样更快，但意味着随后如果操作系统崩溃，转储可能会损坏。通常，此选项适用于测试，但不应在从生产安装转储数据时使用。

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

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

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

当生成一个归档（非文本）输出文件时，此选项将被忽略。对于归档格式，可以在调用 pg_restore 时指定该选项。

不输出用于设置 TOAST 压缩方法的命令。使用此选项时，所有列都会以默认压缩设置恢复。

不要转储不记录 WAL 的表和序列的内容。此选项不会影响是否转储表和序列的定义（模式）；它只会抑制表和序列数据的转储。从备库转储时，不记录 WAL 的表和序列中的数据始终会被排除。

添加 ON CONFLICT DO NOTHING 到 INSERT 命令中。除非同时指定了 --inserts、--column-inserts 或 --rows-per-insert，否则此选项无效。

强制为所有标识符加引号。当从某个服务器转储数据库，而该服务器的 PostgreSQL 主版本与 pg_dump 不同，或者输出打算装入另一主版本的服务器时，推荐使用此选项。默认情况下，pg_dump 只会为在其自身主版本中属于保留字的标识符加引号。这有时会在处理其他版本服务器时导致兼容性问题，因为这些版本的保留字集合可能略有不同。使用 --quote-all-identifiers 可以防止此类问题，但代价是转储脚本更难阅读。

在转储输出中，把给定字符串用作 psql 的 \restrict 键。此选项只能用于纯文本转储，也就是 --format 被设置为 plain，或者省略了 --format 选项时。若未指定该键，pg_dump 会按需要随机生成一个。键只能包含字母数字字符。

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

将数据转储为 INSERT 命令（而不是 COPY）。它控制每个 INSERT 命令的最大行数。指定的值必须是大于零的数字。恢复过程中的任何错误将导致只有属于有问题的 INSERT 的行丢失，而不是整个表的内容。

仅转储指定的部分。部分名称可以是 pre-data、data 或 post-data。可以多次指定此选项以选择多个部分。默认情况下是转储所有部分。

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

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

使用 serializable 事务来执行转储，以确保所用快照与后续数据库状态一致；但这是通过等待事务流到达一个不会出现异常的时点来实现的，从而避免转储失败或导致其他事务因 serialization_failure 而回滚。有关事务隔离和并发控制的更多信息，请参见第 13 章。

这个选项对于仅用于灾难恢复的转储没有好处。但对于用来加载数据库副本，以供报表或其他只读负载共享，而原始数据库继续更新的转储，它可能有用。如果不使用它，转储可能反映出一种与最终提交事务的任何串行执行都不一致的状态。例如，如果使用批处理技术，转储中可能显示某个批次已经关闭，但批次中的全部条目却并未出现。

如果在启动 pg_dump 时没有活动的读写事务，此选项不会带来任何差别。如果存在活动的读写事务，转储开始时间可能会被延迟一个不确定的时长。一旦开始运行，使用或不使用该开关的性能都是相同的。

在制作数据库转储时，使用指定的同步快照（详见表 9.100）。

当需要将转储与逻辑复制槽（参见第 47 章）或与并发会话同步时，此选项很有用。

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

转储优化器统计信息。

只转储统计信息，不转储模式（数据定义）或数据。会转储表、物化视图、外部表和索引的优化器统计信息。

要求每个扩展（-e/--extension）、模式（-n/--schema）和表（-t/--table）模式在要转储的数据库中至少匹配一个扩展/模式/表。这也适用于配合 --filter 使用的过滤器。请注意，如果所有扩展/模式/表模式都找不到匹配项，那么 pg_dump 即使在不使用 --strict-names 的情况下也会报错。

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

当设为 fsync 时（这是默认值），pg_dump --format=directory 会递归打开并同步归档目录中的所有文件。

在 Linux 上，也可以改用 syncfs，让操作系统同步包含归档目录的整个文件系统。关于需要注意的问题，请参见recovery_init_sync_method中有关使用 syncfs 的信息。

当使用 --no-sync，或 --format 未设为 directory 时，此选项没有效果。

这与 -t/--table 选项相同，只是它还会包含匹配 pattern 的表的任何分区或继承子表。

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

显示关于 pg_dump 命令行参数的帮助信息，并退出。

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

指定服务器所在机器的主机名。如果值以斜杠开头，则被用作 Unix 域套接字的目录。默认值取自 PGHOST 环境变量（如果已设置），否则尝试使用 Unix 域套接字连接。

指定服务器正在监听连接的 TCP 端口，或本地 Unix 域套接字文件扩展名。默认值取自 PGPORT 环境变量（如果已设置），否则使用编译时默认值。

用于连接的用户名。

绝不发出密码提示。如果服务器要求密码认证，而又无法通过 .pgpass 文件等其他方式获得密码，则连接尝试将失败。在没有用户在场输入密码的批处理作业和脚本中，此选项很有用。

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

这个选项绝非必需，因为如果服务器要求密码认证，pg_dump 会自动提示输入密码。不过，pg_dump 会先浪费一次连接尝试来发现服务器需要密码。在某些情况下值得输入 -W，因为可以避免这次额外的连接尝试。

指定用于创建转储的角色名称。此选项会让 pg_dump 在连接数据库后发出 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少 pg_dump 所需权限，但可以切换到具有所需权限的角色时，此选项很有用。有些安装环境有禁止直接以超级用户登录的策略，使用此选项就可以在不违反该策略的情况下进行转储。

默认连接参数。

指定诊断消息是否使用颜色。可选值为 always、auto和 never。