pg_dump

Extracts a database into a single script file or other archive file.

概要

  1. pg_dump [connection-option ...] [dump_option ...] [dbname]
  3. pg_dump -? | --help
  5. pg_dump -V | --version

描述

pg_dump是用于备份数据库的标准PostgreSQL工具，在Greenplum数据库中也受支持。 它创建一个（非并行）转储文件。 对于Greenplum数据库的常规备份，最好使用Greenplum数据库备份工具gpbackup以获得最佳性能。

如果要将数据迁移到另一个数据库供应商的系统或具有不同segment配置的另一个Greenplum数据库系统（例如，如果要迁移的系统具有更多或更少的segment实例）， 请使用pg_dump。 要还原，必须使用相应的pg_restore工具（如果转储文件为归档格式）， 或者可以使用诸如psql之类的客户端程序（如果转储文件为纯文本格式）。

由于pg_dump与常规PostgreSQL兼容，因此可以用于将数据迁移到Greenplum数据库中。 Greenplum数据库中的pg_dump工具与PostgreSQL pg_dump工具非常相似，但有以下例外和限制：

  • 如果使用pg_dump备份Greenplum数据库数据库，请记住，对于大型数据库，转储操作可能需要很长时间（几个小时）。 另外，必须确保您有足够的磁盘空间来创建转储文件。
  • 如果要将数据从一个Greenplum数据库系统迁移到另一个系统， 请使用--gp-syntax命令行选项在CREATE TABLE语句中包括DISTRIBUTED BY子句。 这样可以确保在还原时使用正确的分发键列分发Greenplum数据库表数据。

即使同时使用数据库，pg_dump也会进行一致的备份。 pg_dump不会阻止其他用户访问数据库（读或写）。

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

Note: --ignore-version选项已弃用，在以后的版本中将被删除。

选项

dbname

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

转储选项

-a | —data-only

仅转储数据，而不转储模式（数据定义）。表数据和序列值将转储。

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

-b | —blobs

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

Note: Greenplum数据库不支持PostgreSQL大对象工具来流存储在大对象结构中的用户数据。

-c | —clean

在输出用于创建数据库对象的命令之前，将命令添加到文本输出文件中以清理（删除）数据库对象。 （如果目标数据库中不存在任何对象，则恢复可能会生成一些无害的错误消息。） 请注意，在转储操作开始之前不会删除对象，但是会将DROP命令添加到DDL转储输出文件中， 以便在使用这些文件时要还原文件，要先执行DROP命令，再执行CREATE命令。 此选项仅对纯文本格式有意义。 对于归档格式，可以在调用pg_restore时指定该选项。

-C | —create

从命令开始输出，以创建数据库本身并重新连接到创建的数据库。 （使用这种形式的脚本，在运行脚本之前连接到目标安装中的哪个数据库都没有关系。） 如果还指定了--clean，则脚本会删除并在重新连接目标数据库之前重新创建它。 此选项仅对纯文本格式有意义。 对于归档格式，可以在调用pg_restore时指定该选项。

-E encoding | —encoding=encoding

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

-f file | —file=file

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

-F p|c|d|t | —format=plain|custom|directory|tar

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

p | plain — 输出纯文本SQL脚本文件（默认）。

c | custom — 输出适合输入到pg_restore的自定义存档。 与目录输出格式一起使用时，这是最灵活的输出格式，因为它允许在还原过程中手动选择和重新排序已归档的项目。 默认情况下，此格式为压缩格式，并且还支持并行转储。

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

t | tar — 输出适合输入到pg_restore的tar格式的存档。 tar格式与目录格式兼容；提取tar格式的存档会生成有效的目录格式的存档。 但是，tar格式不支持压缩。 同样，在使用tar格式时，在还原过程中不能更改表数据项的相对顺序。

-i | —ignore-version

Note: 此选项已被弃用，并将在以后的版本中删除。

忽略pg_dump和数据库服务器之间的版本不匹配。 pg_dump可以从运行早期版本的Greenplum数据库（或PostgreSQL）的服务器中转储，但是可能不再支持非常旧的版本。 如果您需要覆盖版本检查，请使用此选项。

-j njobs | —jobs=njobs

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

Note: 使用pg_dump的并行转储仅在查询调度程序（master）节点上并行化， 而不是在使用gpbackup时跨查询执行器（segment）节点并行化。

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

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

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

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

-n schema | —schema=schema

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

注意：当指定-n时，pg_dump不会尝试转储所选模式可能依赖的任何其他数据库对象。 因此，不能保证特定模式转储的结果可以自己成功地恢复到干净的数据库中。

Note: 指定-n时，不转储非模式对象（例如blob）。 您可以使用--blobs开关将blob添加回转储。

-N schema | —exclude-schema=schema

不要转储任何与schema匹配的模式。 根据与-n相同的规则解释该模式。 -N可以多次给出，以排除与几种模式中的任何一种匹配的模式。 当同时给出-n和-N时，行为是仅转储与至少一个-n开关匹配但不与-N开关匹配的模式。 如果出现-N而没有-n，则与-N匹配的模式将从正常转储中排除。

-o | —oids

转储对象标识符（OID）作为每个表的数据的一部分。 对于要还原到Greenplum数据库中的文件，建议不要使用此选项。

-O | —no-owner

不要输出命令来设置对象的所有权以匹配原始数据库。 默认情况下，pg_dump发出ALTER OWNER或SET SESSION AUTHORIZATION语句来设置创建的数据库对象的所有权。 除非由超级用户（或拥有脚本中所有对象的同一用户）启动脚本，否则运行脚本时这些语句将失败。 要使脚本可以被任何用户恢复，但将赋予该用户所有对象的所有权，请指定-O。 此选项仅对纯文本格式有意义。 对于归档格式，可以在调用pg_restore时指定该选项。

-s | —schema-only

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

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

（不要将此与--schema选项混淆，该选项以不同的含义使用”schema”一词。）

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

-S username | —superuser=username

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

Note: Greenplum数据库不支持用户定义的触发器。

-t table | —table=table

仅转储与表模式匹配的表（或视图，序列或外部表）。 以schema.table格式指定表。

通过写入多个-t开关可以选择多个表。 而且，根据psql的\d命令使用的相同规则， 将table参数解释为模式，因此也可以通过在模式中写入通配符来选择多个表。 使用通配符时，如果需要请小心引用模式，以防止Shell扩展通配符。 使用-t时-n和-N开关无效， 因为-t选择的表将被转储，而与那些开关无关，并且非表对象也将不被转储。

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

另外，-t不能用于指定子表分区。 要转储分区表，必须指定父表名称。

-T table | —exclude-table=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 0..9 | —compress=0..9

指定要使用的压缩级别。 零表示无压缩。 对于自定义存档格式，此选项指定压缩单个表数据段，并且默认设置为中等压缩。

对于纯文本输出，设置非零压缩级别会使整个输出文件被压缩，就好像它是通过gzip馈送的一样。 但默认设置为不压缩。 tar存档格式当前根本不支持压缩。

--binary-upgrade

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

--column-inserts | —attribute-inserts

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

--disable-dollar-quoting

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

--disable-triggers

仅当创建仅数据转储时，此选项才相关。 它指示pg_dump包含一些命令，以在重新加载数据时临时禁用目标表上的触发器。 如果不想在数据重装期间调用的表上有触发器，请使用此选项。 为--disable-triggers发出的命令必须以超级用户身份执行。 因此，您还应该使用-S指定超级用户名，或者最好小心地以超级用户身份启动生成的脚本。 此选项仅对纯文本格式有意义。 对于归档格式，可以在调用pg_restore时指定该选项。

Note: Greenplum数据库不支持用户定义的触发器。

--exclude-table-data=table

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

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

--if-exists

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

--inserts

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

--lock-wait-timeout=timeout

不要在转储开始时一直等待获取共享表锁。 相反，如果无法在指定的timeout时间内锁定表，则失败。 将timeout指定为毫秒数。

--no-security-labels

不要转储安全标签。

--no-synchronized-snapshots

该选项允许在6.0之前版本的Greenplum数据库服务器上运行pg_dump -j。 有关更多详细信息，请参见-j参数的文档。

--no-tablespaces

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

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

--no-unlogged-table-data

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

--quote-all-identifiers

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

--section=sectionname

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

data节包含实际的表数据和序列值。 post-data项包括索引，触发器，规则和约束的定义，而不是经过验证的检查约束。 pre-data项包括所有其他数据定义项。

--serializable-deferrable

对转储使用可序列化的事务，以确保使用的快照与以后的数据库状态一致； 但这要通过等待事务流中不会出现异常的点来完成，这样就不会存在转储失败或导致其他事务因serialization_failure而回滚的风险。

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

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

Note: 由于Greenplum数据库不支持可序列化的事务，因此--serializable-deferrable选项在Greenplum数据库中无效。

--use-set-session-authorization

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

--gp-syntax | —no-gp-syntax

使用--gp-syntax在CREATE TABLE语句中转储Greenplum数据库语法。 这允许转储Greenplum数据库表的分发策略（DISTRIBUTED BY或DISTRIBUTED RANDOMLY子句）， 这对于还原到其他Greenplum数据库系统很有用。 默认是在连接到Greenplum数据库系统时包括Greenplum数据库语法，而在连接到常规PostgreSQL系统时将其排除。

--function-oids oids

转储对象标识符的oids列表中指定的函数。

Note: 仅提供此选项供其他管理工具使用。 不建议或不支持将其用于任何其他目的。 该选项的行为在将来的版本中可能会更改，恕不另行通知。

--relation-oids oids

转储对象标识符的oids列表中指定的关系。

Note: 仅提供此选项供其他管理工具使用。 不建议或不支持将其用于任何其他目的。 该选项的行为在将来的版本中可能会更改，恕不另行通知。

-? | —help

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

连接选项

-d dbname | —dbname=dbname

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

如果此参数包含\=符号或以有效的URI前缀 （postgresql://或postgres://）开头，则将其视为conninfo字符串。 有关更多信息，请参见PostgreSQL文档中的连接字符串。

-h host | —host=host

运行Greenplum数据库master数据库服务器的计算机的主机名。 如果未指定，则从环境变量PGHOST读取或默认为localhost。

-p port | —port=port

Greenplum master数据库服务器正在侦听连接的TCP端口。 如果未指定，则从环境变量PGPORT读取或默认为5432。

-U username | —username=username

要用作连接的数据库角色名称。 如果未指定，则从环境变量PGUSER读取或默认为当前系统角色名称。

-W | —password

强制输入密码提示。

-w | —no-password

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

--role=rolename

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

注解

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

pg_dump生成的转储文件不包含优化器用于制定查询计划决策的统计信息。 因此，从转储文件还原后运行ANALYZE是明智的，以确保最佳性能。

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

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

示例

将名为mydb的数据库转储到SQL脚本文件中：

  1. pg_dump mydb > db.sql

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

  1. psql -d newdb -f db.sql

以tar文件格式转储Greenplum数据库，并包含分发策略信息：

  1. pg_dump -Ft --gp-syntax mydb > db.tar

要将数据库转储到自定义格式的存档文件中：

  1. pg_dump -Fc mydb > db.dump

要将数据库转储到目录格式的存档中：

  1. pg_dump -Fd mydb -f dumpdir

要将数据库与5个工作作业并行转储到目录格式的存档中，请执行以下操作：

  1. pg_dump -Fd mydb -j 5 -f dumpdir

要将存档文件重新加载到名为newdb的（新创建的）数据库中：

  1. pg_restore -d newdb db.dump

要转储名为mytab的单个表：

  1. pg_dump -t mytab mydb > db.sql

要在-t和相关开关中指定大写或大小写混合的名称，您需要将名称加双引号；否则它将被折叠成小写。 但是双引号对于shell来说是特殊的，因此反过来必须使用双引号。 因此，要转储具有大小写混合名称的单个表，您需要执行以下操作：

  1. pg_dump -t '"MixedCaseName"' mydb > mytab.sql

另见

pg_dumpall, pg_restore, psql