pg_dump · PostgreSQL 中文文档 9.3

# pg_dump ## Name pg_dump -- 将一个PostgreSQL数据库转储到一个脚本文件或者其它归档文件中 ## Synopsis `pg_dump` [`_connection-option_`...] [`_option_`...] [`_dbname_`] ## 描述 pg_dump是一个用于备份PostgreSQL 数据库的工具。它甚至可以在数据库正在使用的时候进行完整一致的备份。 pg_dump并不阻塞其它用户对数据库的访问(读或者写)。转储格式可以是一个脚本或者归档文件。脚本转储的格式是纯文本，它包含许多 SQL 命令，这些 SQL 命令可以用于重建该数据库并将之恢复到保存成脚本的时候的状态。使用[psql](#calibre_link-23)从这样的脚本中恢复。它们甚至可以用于在其它机器甚至是其它硬件体系的机器上重建该数据库，通过对脚本进行一些修改，甚至可以在其它 SQL 数据库产品上重建该数据库。归档文件格式必须和[pg_restore](#calibre_link-440)一起使用重建数据库。它们允许pg_restore对恢复什么东西进行选择，或者甚至是在恢复之前对需要恢复的条目进行重新排序。归档文件也是设计成可以跨平台移植的。如果一种候选文件格式和pg_restore结合，那么pg_dump就能提供一种灵活的归档和传输机制。 pg_dump可以用于备份整个数据库，然后就可以使用 pg_restore检查这个归档和/或选择要恢复的数据库部分。最灵活的输出文件格式是"custom"(自定义)格式(`-Fc`)和 "directory"（目录）格式(`-Fd`)。它们允许对归档元素进行选取和重新排列，支持并行恢复并且缺省时是压缩的。 "directory"格式是唯一支持并行转储的格式。在运行pg_dump的时候，应该检查输出，看看是否有任何警告存在(在标准错误上打印)，特别是下面列出的限制。 ## 选项下面的命令行参数控制输出的内容和格式。 `_dbname_` 将要转储的数据库名。如果没有声明这个参数，那么使用环境变量`PGDATABASE`。如果那个环境变量也没声明，那么使用发起连接的用户名。 `-a``--data-only` 只输出数据，不输出模式(数据定义)。转储表数据、大对象和序列值。这个选项类似于声明`--section=data`，但是只是因为历史原因存在并不完全相同。 `-b` `--blobs` 在转储中包含大对象。除非指定了`--schema`, `--table`, `--schema-only`开关，否则这是默认行为。因此`-b` 开关仅用于在选择性转储的时候添加大对象。 `-c` `--clean` 输出命令在输出创建数据库命令之前先清理(drop)该数据库对象。（如果任何对象在目标数据库中不存在，则转储可能生成一些无害的错误信息。）这个选项只是对纯文本格式有意义。对于归档格式，可以在调用`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` 适合输入到pg_restore里的自定义格式归档。加上目录输出格式，这是最灵活的格式，它允许在转储期间对已归档的条目进行手动选择和重新排列。这个格式缺省的时候是压缩的。 `d` `directory` 适合输入到pg_restore里的目录格式归档。这将创建一个目录，该目录包含一个为每个被转储的表和二进制大对象的文件，加上一个号称目录的文件，该文件以pg_restore可读的机器可读格式描述转储的对象。目录格式归档可以用标准Unix工具操作；例如，在非压缩归档中的文件可以用 gzip工具压缩。这个格式缺省的时候是压缩的，并且也支持并行转储。 `t` `tar` 适合输入到pg_restore里的`tar`归档文件。 tar格式兼容目录格式；提取tar格式归档产生一个有效的目录格式归档。不过， tar格式不支持压缩并且限制单独的表为8 GB。还有，表数据条目的相关顺序在转储期间不能更改。 `-i` `--ignore-version` 一个现在已经不用了的废弃选项。 `-j` `_njobs_` `--jobs=``_njobs_` 通过同时转储`_njobs_`表并行运行转储。该选项减少了转储的时间，但是也增加了数据库服务器的负载。可以只将这个选项用于目录输出格式，因为这是多进程可以同时写它们的数据的唯一的输出格式。 pg_dump将打开`_njobs_` + 1个到数据库的连接，所以确保你的[max_connections](#calibre_link-441)设置足够高以适应所有的连接。运行并行转储时在数据库对象上请求排他锁会导致转储失败。原因是pg_dump 主进程在工作进程稍后转储的对象上请求共享锁，这样做是为了确保在转储运行时没有人删除它们或移走它们。如果另一个客户端然后在一个表上请求一个排他锁，该锁将不被授予，但是将会排队等候主进程的共享锁释放。因此，任意其他访问表的请求也将不被授予，并且会在排他锁请求后排队。这包含工作进程尝试转储这个表。没有防范措施这将是一个经典的死锁情况。为了检测这个冲突， pg_dump工作进程请求使用`NOWAIT`选项请求另外一个共享锁。如果没有授予工作进程这个共享锁，那么肯定是另外一个人在此期间请求了一个排他锁，并且没有办法继续进行转储了，所以pg_dump只能退出转储。对于一个一致的备份，数据库服务器需要支持同步快照，这是PostgreSQL 9.2 引入的一个特性。有了这个特性，数据库客户端可以保证他们看到相同的数据设置，即使它们使用不同的连接。 `pg_dump -j`使用多个数据库连接；它与主进程连接到数据库一次，然后再次连接到每个worker工作。没有同步快照特性，不同的worker工作将不会保证在每个连接中看到相同的数据，这将导致一个不一致的备份。如果你想在一个9.2之前的服务器上运行并行转储，那么你需要保证在主进程到最后一个worker工作连接到数据库之间，数据库内容不会改变。最简单的方法是在开始备份之前叫停所有数据修改进程（DDL和DML）访问数据库。你也需要在9.2之前的PostgreSQL服务器上运行`pg_dump -j` 时，声明`--no-synchronized-snapshots`参数。 `-n` `_schema_` `--schema=``_schema_` 只转储匹配`_schema_`的模式内容，包括模式本身以及其中包含的对象。如果没有声明这个选项，所有目标数据库中的非系统模式都会被转储出来。可以使用多个`-n`选项指定多个模式。同样，`_schema_`参数将按照psql 的`\d`命令的规则(参见[_Patterns_](#calibre_link-442)) 被解释为匹配模式，因此可以使用通配符匹配多个模式。在使用通配符的时候，最好用引号进行界定，以防止 shell 将通配符进行扩展。参阅[_例子_](#calibre_link-443)。 > **Note:** 如果指定了`-n`，那么pg_dump 将不会转储那些模式所依赖的其他数据库对象。因此，无法保证转储出来的内容一定能够在另一个干净的数据库中恢复成功。 > **Note:** 非模式对象(比如大对象)不会在指定`-n`的时候被转储出来。你可以使用`--blobs`明确要求转储大对象。 `-N` `_schema_` `--exclude-schema=``_schema_` 不转储任何匹配`_schema_`的模式内容。模式匹配规则与`-n`完全相同。可以指定多个`-N`以排除多种匹配的模式。如果同时指定了`-n`和`-N`，那么将只转储匹配`-n` 但不匹配`-N`的模式。如果出现`-N`但是不出现`-n`，那么匹配`-N`的模式将不会被转储。 `-o` `--oids` 作为数据的一部分，为每个表都输出对象标识(OIDs)。如果你的应用需要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`选项混淆，`--schema`使用不同含义的"schema"。排除表数据只是数据库中表的一个子集，参阅`--exclude-table-data`。 `-S` `_username_` `--superuser=``_username_` 指定关闭触发器时需要用到的超级用户名。它只有使用了`--disable-triggers` 的时候才有影响。一般情况下最好不要输入这个参数，而是用超级用户启动生成的脚本。 `-t` `_table_` `--table=``_table_` 只转储出匹配`_table_`的表（或视图、序列、外表）。可以使用多个`-t`选项匹配多个表。同样，`_table_` 参数将按照psql的`\d`命令的规则(参见 [_Patterns_](#calibre_link-442))被解释为匹配模式，因此可以使用通配符匹配多个模式。在使用通配符的时候，最好用引号进行界定，以防止 shell 将通配符进行扩展。参阅[_例子_](#calibre_link-443)。使用了`-t`之后，`-n`和`-N`选项就失效了。因为被`-t` 选中的表将无视`-n`和`-N`选项而被转储，同时除了表之外的其他对象不会被转储。 > **Note:** 如果指定了`-t`，那么pg_dump 将不会转储任何选中的表依赖的其它数据库对象。因此，无法保证转储出来的表能在一个干净的数据库中成功恢复。 > **Note:** `-t`选项与PostgreSQL 8.2 之前的版本不兼容。之前的`-t tab`将转储所有名为`tab`的表，但是现在只转储在默认搜索路径中可见的表。写成`-t '*.tab'`将等价于老版本的行为。同样，你必须用`-t sch.tab`而不是老版本的`-n sch -t tab`选择特定模式中的表。 `-T` `_table_` `--exclude-table=``_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_` 指定要使用的压缩级别。0表示不压缩。对于自定义归档格式，指定单个表数据段的压缩，并且缺省是中等水平的压缩。对于纯文本输出，设置非零压缩级别会压缩整个输出文件，就像通过gzip反馈回来一样；但是缺省是不压缩的。 tar归档模式当前不支持压缩。 `--binary-upgrade` 此选项用于在线升级工具。不建议也不支持用于其他目的。该选项的行为可能会在将来的版本中改变。 `--column-inserts` `--attribute-inserts` 把数据转储为带有明确字段名的`INSERT`命令 (`INSERT INTO` `_table_` (`_column_`, ...) VALUES ...)。这样会导致恢复非常缓慢，它主要用于制作那种可以用于其它非 PostgreSQL数据库的转储。由于这个选项为每条记录都生成一条命令，因此如果其中某一行命令出错，那么将仅有该行数据丢失，而不是整个表的数据丢失。 `--disable-dollar-quoting` 这个选项关闭使用美元符界定函数体。强制它们用 SQL 标准的字符串语法的引号包围。 `--disable-triggers` 这个选项只是和创建仅有数据的转储相关。它告诉pg_dump 包含在恢复数据时临时关闭目标表上触发器的命令。如果在表上有参照完整性检查或者其它触发器，而恢复数据的时候不想重载他们，那么就应该使用这个选项。目前，为`--disable-triggers`发出的命令必须以超级用户来执行。因此，你应该同时用`-S`声明一个超级用户名，或者最好是用一个超级用户的身份来启动这个生成的脚本。这个选项只对纯文本格式有意义。对于归档格式，可以在调用`pg_restore` 的时候声明这个选项。 `--exclude-table-data=``_table_` 不要转储任何匹配`_table_`模式的表。模式匹配规则与`-t`完全相同。可以给出多个`--exclude-table-data` 以排除多个匹配的表。当你需要指定表的定义时该选项是有用的，即使你不需要表里面的数据。要排除数据库中所有表的数据，参阅`--schema-only`。 `--inserts` 将数据输出为的`INSERT`命令(而不是`COPY`)。这样会导致恢复非常缓慢。这个选项主要用于制作那种可以用于其它非 PostgreSQL数据库的转储。由于这个选项为每条记录都生成一条命令，因此如果其中某一行命令出错，那么将仅有该行数据丢失，而不是整个表的数据丢失。请注意，如果你重新排列了字段顺序，那么恢复可能会完全失败。 `--column-inserts`更安全，但是也更慢。 `--lock-wait-timeout=``_timeout_` 在转储开始的时候不要等待请求一个共享表锁。相反，如果无法在指定的 `_timeout_`内锁住表则失败。 timeout可以用任意`SET statement_timeout`接受的格式声明。（允许的值依赖于你转储的服务器版本，但是自7.3以来，所有的版本都接受毫秒的整数值。当从7.3以前的版本服务器中转储时，省略该选项。） `--no-security-labels` 不转储安全标签。 `--no-synchronized-snapshots` 该选项允许在9.2以前的服务器上运行`pg_dump -j`，参阅`-j` 参数的文档获取更多信息。 `--no-tablespaces` 不要输出选择表空间的命令。有了该选项，所有对象在转储期间都将在缺省的表空间中创建。这个选项只是对纯文本格式有意义。对于归档格式，在调用`pg_restore` 的时候可以声明该选项。 `--no-unlogged-table-data` 不要转储未记录表的内容。该选项对于表定义（模式）是否转储没有影响；它只阻止转储表的数据。当从备用服务器转储时，未记录表中的数据总是排除。 `--quote-all-identifiers` 强制给所有标识符加上引号。这在转储一个数据库到一个可能引入了额外关键字的新版本中时可能是有用的。 `--section=``_sectionname_` 只转储命名的章节。该章节名可以是`pre-data`, `data`, 或 `post-data`。可以多次声明这个选项以选择多个章节。缺省是转储所有章节。数据章节包含实际的表数据、大对象内容和序列值。原始数据项包含索引、触发器、规则和约束（除了验证检查约束）的定义。之前的数据项包含所有其他数据定义项。 `--serializable-deferrable` 为转储使用一个`可串行化`的事务，以保证使用的快照和稍后的数据库状态一致；做这些是通过等待事务流中的一个点，该点没有异常会出现，所以不会有转储失败或导致其他事务 `serialization_failure`而回滚的风险。参阅[Chapter 13](#calibre_link-444) 获取关于事务隔离和并发控制的更多信息。这个选项对于只打算灾难恢复的转储没有益处。对于原始数据库仍然在更新时，加载一个数据库的拷贝作为报告或其他只读加载共享的转储是有帮助的。没有这个选项，转储会反应一个与任何事务最终提交的序列化执行不一致的状态。例如，如果使用了批处理技术，可能会在转储中显示一部分，而不是批处理中的所有条目。在pg_dump开始时，如果没有读写事务在活动，则这个选项没有什么影响。如果有读写事务在活动，那么转储开始时可能会延迟一段不确定的时间。一旦运行，有没有开关的性能是一样的。 `--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 31.1](#calibre_link-445) 获取更多信息。 `-h` `_host_` `--host=``_host_` 指定运行服务器的主机名。如果数值以斜杠开头，则被用作到 Unix 域套接字的路径。缺省从`PGHOST`环境变量中获取(如果设置了的话)，否则，尝试一个 Unix 域套接字连接。 `-p` `_port_` `--port=``_port_` 指定服务器正在侦听的 TCP 端口或本地 Unix 域套接字文件的扩展(描述符)。缺省使用`PGPORT`环境变量(如果设置了的话)，否则，编译时的缺省值。 `-U` `_username_` `--username=``_username_` 连接的用户名。 `-w` `--no-password` 从不发出密码提示问题。如果服务器要求密码认证并且密码不可用于其他意思如 `.pgpass`文件，则连接尝试将会失败。该选项在批量工作和不存在用户输入密码的脚本中很有帮助。 `-W` `--password` 强制pg_dump在连接到数据库之前提示一个密码。这个选项从来不是至关重要的，因为如果服务器需求密码认证，则pg_dump 自动提示一个密码。不过，pg_dump 将在找出服务器想要一个密码上浪费一个连接尝试。在某些情况下，值得输入`-W` 以避免额外的连接尝试。 `--role=``_rolename_` 指定创建转储的角色名。这个选项导致连接到数据库之后pg_dump 发出一个`SET ROLE` `_rolename_`命令。当认证的用户（通过`-U`指定）缺乏pg_dump所需的权限时是很有用的，可以转变成有所需权限的角色。一些安装有反对作为超级用户直接登录的政策，使用这个选项允许转储不违反该政策。 ## 环境变量 `PGDATABASE` `PGHOST` `PGOPTIONS` `PGPORT` `PGUSER` 缺省连接参数。这个功用，类似大多数其他PostgreSQL实用工具，也使用由libpq支持的环境变量（参阅[Section 31.14](#calibre_link-39)）。 ## 诊断 pg_dump在内部使用`SELECT`语句。如果你运行pg_dump时碰到问题，确认你能够使用像 [psql](#calibre_link-23)这样的程序从数据库选取信息。还有，要申请任何libpq前端库要使用的缺省连接设置和环境变量。 pg_dump的数据库活动通常由统计收集器收集。如果不需要，你可以通过`PGOPTIONS` 或 `ALTER USER`命令设置参数`track_counts`为假。 ## 注意如果你的数据库给`template1`数据库增加了任何你自己的东西，那么请注意把pg_dump的输出恢复到一个真正空的数据库中；否则你可能会收到因为重复定义所追加的对象而造成的错误信息。要制作一个没有任何本地附属物的数据库，可以从`template0` 而不是`template1`拷贝，比如： ``` CREATE DATABASE foo WITH TEMPLATE template0; ``` 在进行纯数据转储并且使用了选项`--disable-triggers`的时候， pg_dump发出一些查询先关闭用户表上的触发器，然后插入数据，插入完成后再打开触发器。如果恢复动作在中间停止，那么系统表可能就会处于一种错误状态。 tar 归档的成员的大小限制于 8 GB 。这是 tar 文件格式的固有限制。因此这个格式无法用于任何大小超过这个尺寸的表。 tar 归档和任何其它输出格式的总大小是不受限制的，只是可能会有操作系统的限制。 pg_dump生成的转储文件并不包含优化器用于查询规划决策的统计信息。因此，恢复完之后，建议在每个已恢复的对象上运行`ANALYZE`，以保证最佳的性能；参阅[Section 23.1.3](#calibre_link-446)和[Section 23.1.6](#calibre_link-77) 获取更多信息。转储文件也不包含任何`ALTER DATABASE ... SET`命令；这些设置通过[pg_dumpall](#calibre_link-439)转储，连同数据库用户和其他安装范围的设置。因为pg_dump常用于向新版本的PostgreSQL 中传递数据，所以pg_dump的输出预计可以加载到比 pg_dump的版本更新的PostgreSQL 服务器版本中。pg_dump还可以从比它自身版本老的PostgreSQL 服务器中转储。（当前，支持后退到版本7.0的服务器。）不过，pg_dump 不能从比它自身主版本新的PostgreSQL服务器中转储；它会拒绝尝试，而不是冒险制作一个不可用的转储。另外，它不保证pg_dump 的输出可以加载到一个旧的主版本的服务器中，即使该转储是从那个版本的服务器中而来。加载转储文件到一个旧的服务器可能需要手动编辑转储文件，以删除不被旧版本理解的语法。 ## 例子将`mydb`数据库转储到一个 SQL 脚本文件： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump mydb > db.sql</kbd> ``` 将上述脚本导入一个(新建的)数据库`newdb`： ``` <samp class="literal">$</samp> <kbd class="literal">psql -d newdb -f db.sql</kbd> ``` 将数据库转储为自定义格式的归档文件 ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -Fc mydb > db.dump</kbd> ``` 将数据库转储为目录格式归档： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -Fd mydb -f dumpdir</kbd> ``` 将数据库转储为目录格式归档，并行5个worker工作： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -Fd mydb -j 5 -f dumpdir</kbd> ``` 将归档文件导入一个(新建的)数据库`newdb`： ``` <samp class="literal">$</samp> <kbd class="literal">pg_restore -d newdb db.dump</kbd> ``` 转储一个名为`mytab`的表： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -t mytab mydb > db.sql</kbd> ``` 转储`detroit`模式中所有以`emp`开头的表，但是不包括`employee_log`表： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -t 'detroit.emp*' -T detroit.employee_log mydb > db.sql</kbd> ``` 转储所有以`east`或`west`开头并以`gsm`结尾的模式，但是不包括名字中含有`test`模式： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -n 'east*gsm' -n 'west*gsm' -N '*test*' mydb > db.sql</kbd> ``` 同上，不过这一次使用正则表达式的方法： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -n '(east|west)*gsm' -N '*test*' mydb > db.sql</kbd> ``` 转储所有数据库对象，但是不包括名字以`ts_`开头的表： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -T 'ts_*' mydb > db.sql</kbd> ``` 在`-t`等选项中指定大写字母或大小写混合的名字必须用双引号界定，否则将被自动转换为小写(参见[_Patterns_](#calibre_link-442))。但是因为双引号在 shell 中有特殊含义，所以必须将双引号再放进单引号中。这样一来，要转储一个大小写混合的表名，你就需要像下面这样： ``` <samp class="literal">$</samp> <kbd class="literal">pg_dump -t "\"MixedCaseName\"" mydb > mytab.sql</kbd> ``` ## 又见 [pg_dumpall](#calibre_link-439), [pg_restore](#calibre_link-440), [psql](#calibre_link-23)