Postgresql 中文操作指南

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

仅转储数据，而不是架构（数据定义）。表数据、大对象和序列值将被转储。

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

在转储中包括大对象。除了指定了 —​schema 、 —​table 或 —​schema-only 之外，这是默认行为。因此， -b 开关仅对向已请求特定架构或表的转储添加大对象有用。请注意，大对象被视为数据，因此在使用 —​data-only 时将包括大对象，而在使用 —​schema-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 开关，选择多个扩展。会根据 psql \d 命令使用的相同规则，将 pattern 参数解释为模式（请参见 Patterns ），因此也可以通过在模式中编写通配符的方式选择多个扩展。当使用通配符时，请注意需要时引号模式，以防止 Shell 展开通配符。

如果 pg_extension_config_dump 注册了任何配置关系，当它的扩展由 —​extension 指定时，就会将其包含在转储中。

以指定字符集编码创建转储。默认情况下，转储会使用数据库编码创建。另一种获得相同结果的方式是将 PGCLIENTENCODING 环境变量设置为所需的转储编码。 Section 24.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 开关，选择多个模式。会根据 psql \d 命令使用的相同规则，将 pattern 参数解释为模式（请参见 Patterns ），因此也可以通过在模式中编写通配符的方式选择多个模式。当使用通配符时，请注意需要时引号模式，以防止 Shell 展开通配符；请参见下面的 Examples 。

不转储任何与 pattern 匹配的模式。模式会根据与 -n 相同的规则进行解释。可以多次指定 -N 以排除与多个模式匹配的模式。

当同时指定 -n 和 -N 时，行为是只转储至少与一个 -n 开关匹配但没有 -N 开关匹配的模式。如果 -N 出现在没有 -n 的情况下，则与 -N 匹配的模式将从通常的转储中排除。

不输出命令来设置对象的属主，以匹配原始数据库。默认情况下，pg_dump 会发出 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置创建的数据库对象的属主。当该脚本未由超级用户（或该脚本中所有对象的属主）启动时，这些语句将会失败。要创建可以由任何用户还原但是将会给该用户所有对象的属主的脚本，请指定 -O 。

在发出存档（非文本）输出文件时忽略此选项。对于存档格式，您可以在调用 pg_restore 时指定该选项。

此选项已过时，但仍然接受它，以保持向后兼容性。

仅转储对象定义（模式），而不是数据。

此选项是 —​data-only 的反向选项。它与指定 —​section=pre-data --section=post-data 类似，但在历史原因上并不相同。

（不要将此与 —​schema 选项混淆， —​schema 选项的“模式”一词有不同的含义。）

要只排除数据库中部分表格的表格数据，请参见 —​exclude-table-data 。

在禁用触发器时指定要使用的超级用户用户名。这仅在使用 —​disable-triggers 时相关。（通常，最好省略此项，而改以超级用户身份启动生成的脚本。）

只转储名称与 pattern 匹配的表格。可通过编写多条 -t 开关，选择多个表格。会根据 psql \d 命令使用的相同规则，将 pattern 参数解释为模式（请参见 Patterns ），因此也可以通过在模式中编写通配符的方式选择多个表格。当使用通配符时，请注意需要时引号模式，以防止 Shell 展开通配符；请参见下面的 Examples 。

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

当使用 -t 时， -n 和 -N 开关不起作用，因为由 -t 选择的表格将无论这些开关如何都将被转储，且非表格对象不会被转储。

不转储任何与 pattern 匹配的表格。模式会根据与 -t 相同的规则进行解释。可以多次指定 -T 以排除与多个模式匹配的表格。

当同时指定 -t 和 -T 时，行为是只转储至少与一个 -t 开关匹配但没有 -T 开关匹配的表格。如果 -T 出现在没有 -t 的情况下，则与 -T 匹配的表格将从通常的转储中排除。

指定冗余模式。这将导致 pg_dump 将详细的对象注释和启动/停止时间输出到转储文件，并将进度消息输出到标准错误。重复该选项将导致在标准错误中显示额外的调试级别消息。

打印 pg_dump 版本并退出。

防止转储访问权限（授予/撤消命令）。

指定要使用的压缩方法和/或压缩级别。如果要执行无压缩，则可以将压缩方法设置为 gzip 、 lz4 、 zstd 或 none 。可以选择指定压缩详细信息字符串。如果详细信息字符串是整数，则它指定压缩级别。否则，它应当是以 keyword 或 keyword=value 形式出现的已逗号分隔的项目列表。目前，受支持的关键字是 level 和 long 。

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

对于自定义和目录存档格式，这指定单个表数据段的压缩，并且默认使用 gzip 中等程度压缩。对于纯文本输出，设置非零压缩级别会导致整个输出文件被压缩，就像通过 gzip、lz4 或 zstd 供给数据一样；但是，默认是不压缩。使用 zstd 压缩， long 模式可能会以增加内存使用的代价提高压缩率。

tar 存档格式当前根本不支持压缩。

此选项供就地升级实用程序使用。不建议或不支持将其用于其他用途。此选项的行为可能会在未来版本中不经通知而改变。

以带有明确列名 ( INSERT INTO _table ( column , …​) VALUES …​) 的 _INSERT 命令形式转储数据。这会使还原非常缓慢；它主要用于制作可以加载到非 PostgreSQL 数据库中的转储。还原期间发生的任何错误将仅导致有问题的 INSERT 中的行丢失，而不是整个表的内容。

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

该选项仅在创建仅数据转储时相关。它指示 pg_dump 包含在还原数据的同时暂时禁用目标表上触发器的命令。如果您在表上具有您不想在数据还原期间调用的引用完整性检查或其他触发器，请使用此选项。

当前，为 —​disable-triggers 发出的命令必须以超级用户身份执行。因此，你还应与 -S 一起指定一个超级用户名，或最好谨慎地以超级用户身份启动生成的脚本。

在发出存档（非文本）输出文件时忽略此选项。对于存档格式，您可以在调用 pg_restore 时指定该选项。

该选项仅在转储具有行安全性的表的相关内容时相关。默认情况下，pg_dump 将 row_security 设置为关闭，以确保从表中转储所有数据。如果用户没有足够的权限绕过行安全性，则会引发错误。此参数指示 pg_dump 将 row_security 设置为打开，从而允许用户转储其有权访问的表内容部分。

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

这与 -T / —​exclude-table 选项相同，只不过它还排除了与 pattern 匹配的表的所有分区或继承子表。

不要转储与 pattern 匹配的任何表的任何数据。该模式的解释规则与 -t 相同。 —​exclude-table-data 可以给出多次以排除与多个模式匹配的表。在需要特定表的定义（即使不需要其中数据）时，此选项非常有用。

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

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

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

使用 DROP …​ IF EXISTS 命令以 —​clean 模式删除对象。这会抑制可能报告的“不存在”错误。除非同时指定 —​clean ，否则此选项无效。

转储与 foreign server 匹配 foreignserver 模式的任何外键表的任何数据。可以通过编写多个 —​include-foreign-data 交换来选择多个 foreign server。此外， foreignserver 参数的解释规则与 psql 的 \d 命令所使用的规则相同（请参见 Patterns ），因此还可以通过在模式中编写通配符来选择多个 foreign server。在使用通配符时，请小心引用模式（如果需要的话），以防止 shell 展开通配符；请参见下文 Examples 。唯一的例外是不允许出现空模式。

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

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

不要在转储开始时无限期地等待获取共享表锁。如果在指定的 timeout 内无法锁住表，则会失败。超时可以用 SET statement_timeout 接受的任何格式指定。（允许的格式取决于您从中转储的服务器版本，但所有版本都接受以毫秒为单位的整数。）

Do not dump comments.

Do not dump publications.

不要转储安全标签。

Do not dump subscriptions.

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

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

在发出存档（非文本）输出文件时忽略此选项。对于存档格式，您可以在调用 pg_restore 时指定该选项。

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

在发出存档（非文本）输出文件时忽略此选项。对于存档格式，您可以在调用 pg_restore 时指定该选项。

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

不要转储未记录的表和序列的内容。此选项不会影响表和序列定义（模式）是否被转储；它只会阻止转储表和序列数据。从备用服务器转储时，未记录的表和序列中的数据始终会被排除在外。

将 ON CONFLICT DO NOTHING 添加到 INSERT 命令。此选项仅在同时指定 —​inserts 、 —​column-inserts 或 —​rows-per-insert 时才有效。

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

以 INSERT 命令（而不是 COPY ）形式转储数据。控制每条 INSERT 命令的最大行数。指定的数值必须大于零。恢复期间发生的任何错误只会导致有问题的 INSERT 中的行丢失，而不是整个表的目录。

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

数据部分包含实际的表数据、大对象内容和序列值。后数据项包括索引、触发器、规则和除已验证的检查约束以外的其他约束的定义。前数据项包括所有其他数据定义项。

使用 serializable 事务进行转储，以确保所使用的快照与后面的数据库状态一致；但通过等待交易流中不会出现异常的某个点来执行此操作，以便不存在转储失败或导致其他交易因 serialization_failure 而回滚的风险。有关事务隔离和并发控制的更多信息，请参见 Chapter 13 。

此选项对于仅用于灾难恢复的转储没有益处。它可能对用于加载数据库副本以进行报告或其他只读负载平衡的转储有用，而原始数据库将继续更新。如果没有它，转储可能反映出与最终提交的事务的任何串行执行不一致的状态。例如，如果使用批处理技术，一个批次可能在转储中显示为已关闭，而其中包含的所有项目都不显示。

如果 pg_dump 启动时没有活跃的读写事务，此选项将不会产生任何影响。如果活动读写事务，转储的开始可能会延迟不确定时间。一旦运行，带有或不带有此开关的性能是相同的。

在对数据库进行转储时，使用指定的同步快照（有关更多详细信息，请参见 Table 9.94 ）。

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

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

要求每个扩展（ -e / —​extension ）、模式（ -n / —​schema ）和表（ -t / —​table ）模式至少与要转储的数据库中的一个扩展/模式/表匹配。请注意，如果没有任何扩展/模式/表模式找到匹配项，pg_dump 即使没有 —​strict-names 也会生成错误。

此选项对 -N / —​exclude-schema 、 -T / —​exclude-table 或 —​exclude-table-data 无影响。排斥模式未能匹配任何对象不被视为是错误。

这与 -t / —​table 选项相同，不同之处在于，它还包括与匹配 pattern 的表的分区或继承的子表。

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

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

Default connection parameters.

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