Question

名称

pg_dump--将一个数据库转储到一个脚本文件或者其它归档文件中

语法

pg_dump [option...] [dbname]

描述

pg_dump 是一个用于备份数据库的工具。它甚至可以在数据库正在使用的时候进行完整一致的备份。pg_dump 并不阻塞其它用户对数据库的访问(读或者写)。

转储格式可以是一个脚本或者归档文件。脚本转储的格式是纯文本，它包含许多 SQL 命令，这些 SQL 命令可以用于重建该数据库并将之恢复到保存成脚本的时候的状态。使用 psql 从这样的脚本中恢复。它们甚至可以用于在其它机器甚至是其它硬件体系的机器上重建该数据库，通过对脚本进行一些修改，甚至可以在其它 SQL 数据库产品上重建该数据库。

归档文件格式必须和 pg_restore 一起使用重建数据库。它们允许 pg_restore 对恢复什么东西进行选择，或者甚至是在恢复之前对需要恢复的条目进行重新排序。归档文件也是设计成可以跨平台移植的。

如果一种候选文件格式和 pg_restore 结合，那么 pg_dump 就能提供一种灵活的归档和传输机制。pg_dump 可以用于备份整个数据库，然后就可以使用 pg_restore 检查这个归档和/或选择要恢复的数据库部分。最灵活的输出文件格式是"custom"(自定义)格式(-Fc)。它允许对归档元素进行选取和重新排列，并且缺省时是压缩的。tar 格式(-Ft)不是压缩的并且在加载的时候不可能重排列，不过它也很灵活；还有，它可以用标准 Unix 工具(比如 tar)进行处理。

在运行 pg_dump 的时候，应该检查输出，看看是否有任何警告存在(在标准错误上打印)，特别是下面列出的限制。

选项

下面的命令行参数控制输出的内容和格式。

dbname

将要转储的数据库名。如果没有声明这个参数，那么使用环境变量 PGDATABASE 。如果那个环境变量也没声明，那么使用发起连接的用户名。

-a
--data-only

只输出数据，不输出模式(数据定义)。

这个选项只是对纯文本格式有意义。对于归档格式，可以在调用 pg_restore 的时候声明该选项。

-b
--blobs

在转储中包含大对象。除非指定了 --schema, --table, --schema-only 开关，否则这是默认行为。因此 -b 开关仅用于在选择性转储的时候添加大对象。

-c
--clean

输出在创建数据库创建命令之前先清理(drop)该数据库对象的命令。

这个选项只是对纯文本格式有意义。对于归档格式，可以在调用 pg_restore 的时候声明该选项。

-C
--create

以一条创建该数据库本身并且与这个数据库连接命令开头进行输出。如果是这种形式的脚本，那么你在运行脚本之前和哪个数据库连接就不重要了。

这个选项只对纯文本格式有意义。对于归档格式，可以在调用 pg_restore 的时候声明该选项。

-d
--inserts

将数据输出为的 INSERT 命令(而不是 COPY)。这样会导致恢复非常缓慢。这个选项主要用于制作那种可以用于其它非 PostgreSQL 数据库的转储。由于这个选项为每条记录都生成一条命令，因此如果其中某一行命令出错，那么将仅有该行数据丢失，而不是整个表的数据丢失。请注意，如果你重新排列了字段顺序，那么恢复可能会完全失败。-D 更安全，但是也更慢。

-D
--column-inserts
--attribute-inserts

把数据转储为带有明确字段名的 INSERT 命令(INSERT INTO table (column, ...) VALUES ...)。这样会导致恢复非常缓慢，它主要用于制作那种可以用于其它非 PostgreSQL 数据库的转储。由于这个选项为每条记录都生成一条命令，因此如果其中某一行命令出错，那么将仅有该行数据丢失，而不是整个表的数据丢失。

-E encoding
--encoding=encoding

以指定的字符集编码创建转储。缺省时，转储是按照数据库编码创建的。另外一个获取同样结果的方法是将 PGCLIENTENCODING 环境变量设置为期望的转储编码。

-f file
--file=file

把输出发往指定的文件。如果忽略，则使用标准输出。

-F format
--format=format

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

p
plain

纯文本 SQL 脚本文件(缺省)

c
custom

适合输入到 pg_restore 里的自定义归档。这是最灵活的格式，它允许对加载的数据和对象定义进行重新排列。这个格式缺省的时候是压缩的。

t
tar

适合输入到 pg_restore 里的 tar 归档文件。使用这个归档允许在恢复数据库时重新排序和/或把数据库对象排除在外。同时也可以在恢复的时候限制对哪些数据进行恢复。

-i
--ignore-version

忽略在 pg_dump 和数据库服务器之间的版本差别。

pg_dump 可以处理来自以前版本的 PostgreSQL 数据库转储，但是太老的版本则不被支持了(目前是支持到 7.0)。但是 pg_dump 对于来自更新版本的转储则无法处理。仅在你需要跳过版本检查时才使用这个选项(而且如果 pg_dump 失效，别说我没警告过你)。

-n schema
--schema=schema

只转储匹配 schema 的模式内容，包括模式本身以及其中包含的对象。如果没有声明这个选项，所有目标数据库中的非系统模式都会被转储出来。可以使用多个 -n 选项指定多个模式。同样，schema 参数将按照 psql 的 \d 命令的规则(参见匹配模式)被解释为匹配模式，因此可以使用通配符匹配多个模式。在使用通配符的时候，最好用引号进行界定，以防止 shell 将通配符进行扩展。

【注意】如果指定了 -n ，那么 pg_dump 将不会转储那些模式所依赖的其他数据库对象。因此，无法保证转储出来的内容一定能够在另一个干净的数据库中恢复成功。

【注意】非模式对象(比如大对象)不会在指定 -n 的时候被转储出来。你可以使用 --blobs 明确要求转储大对象。

-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

只输出对象定义(模式)，不输出数据。

-S username
--superuser=username

指定关闭触发器时需要用到的超级用户名。它只有使用了 --disable-triggers 的时候才有影响。一般情况下最好不要输入这个参数，而是用超级用户启动生成的脚本。

-t table
--table=table

只转储出匹配 table 的表、视图、序列。可以使用多个 -t 选项匹配多个表。同样，table 参数将按照 psql 的 \d 命令的规则(参见匹配模式)被解释为匹配模式，因此可以使用通配符匹配多个模式。在使用通配符的时候，最好用引号进行界定，以防止 shell 将通配符进行扩展。

使用了 -t 之后，-n 和 -N 选项就失效了。因为被 -t 选中的表将无视 -n 和 -N 选项而被转储，同时除了表之外的其他对象不会被转储。

【注意】如果指定了 -t ，那么 pg_dump 将不会转储任何选中的表不依赖的其它数据库对象。因此，无法保证转储出来的表能在一个干净的数据库中成功恢复。

【注意】-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 输出详细的对象评注以及转储文件的启停时间和进度信息到标准错误上。

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

禁止转储访问权限(grant/revoke 命令)

--disable-dollar-quoting

这个选项关闭使用美元符界定函数体。强制它们用 SQL 标准的字符串语法的引号包围。

--disable-triggers

这个选项只是和创建仅有数据的转储相关。它告诉 pg_dump 包含在恢复数据时临时关闭目标表上触发器的命令。如果在表上有参照完整性检查或者其它触发器，而恢复数据的时候不想重载他们，那么就应该使用这个选项。

目前，为 --disable-triggers 发出的命令必须以超级用户来执行。因此，你应该同时用 -S 声明一个超级用户名，或者最好是用一个超级用户的身份来启动这个生成的脚本。

这个选项只对纯文本格式有意义。对于归档格式，可以在调用 pg_restore 的时候声明这个选项。

--use-set-session-authorization

输出符合 SQL 标准的 SET SESSION AUTHORIZATION 命令而不是 ALTER OWNER 命令。这样令转储更加符合标准，但是如果转储文件中的对象的历史有些问题，那么可能不能正确恢复。并且，使用 SET SESSION AUTHORIZATION 的转储需要数据库超级用户的权限才能转储成功，而 ALTER OWNER 需要的权限则低得多。

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

声明在那些支持压缩的格式中使用的压缩级别。目前只有自定义格式支持压缩。

下面的命令行参数控制数据库的连接参数。

-h host
--host=host

指定运行服务器的主机名。如果数值以斜杠开头，则被用作到 Unix 域套接字的路径。缺省从 PGHOST 环境变量中获取(如果设置了的话)，否则，尝试一个 Unix 域套接字连接。

-p port
--port=port

指定服务器正在侦听的 TCP 端口或本地 Unix 域套接字文件的扩展(描述符)。缺省使用 PGPORT 环境变量(如果设置了的话)，否则，编译时的缺省值。

-U username

连接的用户名

-W

强制口令提示。如果服务器需要口令认证，那么这个动作应该自动发生。

环境变量

PGDATABASE
PGHOST
PGPORT
PGUSER

缺省连接参数

诊断

pg_dump 在内部使用 SELECT 语句。如果你运行 pg_dump 时碰到问题，确认你能够使用像 psql 这样的程序从数据库选取信息。

注意

如果你的数据库给 template1 数据库增加了任何你自己的东西，那么请注意把 pg_dump 的输出恢复到一个真正空的数据库中；否则你可能会收到因为重复定义所追加的对象而造成的错误信息。要制作一个没有任何本地附属物的数据库，可以从 template0 而不是 template1 拷贝，比如：

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump 有一些限制：

• 在进行纯数据转储并且使用了选项 --disable-triggers 的时候，pg_dump 发出一些查询先关闭用户表上的触发器，然后插入数据，插入完成后再打开触发器。如果恢复动作在中间停止，那么系统表可能就会处于一种错误状态。

tar 归档的成员的大小限制于 8 GB 。这是 tar 文件格式的固有限制。因此这个格式无法用于任何大小超过这个尺寸的表。tar 归档和任何其它输出格式的总大小是不受限制的，只是可能会有操作系统的限制。

pg_dump 生成的转储文件并不包含优化器用于查询规划决策的统计信息。因此，恢复完之后，建议在每个已恢复的对象上运行 ANALYZE ，以保证良好的性能。

因为 pg_dump 常用于向新版本的 PostgreSQL 中传递数据，所以 pg_dump 的输出可以被导入到新 PostgreSQL 数据库中。同时 pg_dump 还能读取旧 PostgreSQL 数据库的内容，但是一般无法读取更新的 PostgreSQL 数据库；同时也不能将新数据库中转储出来的内容恢复到旧版本中(硬要这样做可能需要手动修改转储结果)。

例子

将 mydb 数据库转储到一个 SQL 脚本文件：

$ pg_dump mydb > db.sql

将上述脚本导入一个(新建的)数据库 newdb ：

$ psql -d newdb -f db.sql

将数据库转储为自定义格式的归档文件：

$ pg_dump -Fc mydb > db.dump

将上述归档文件导入一个(新建的)数据库 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 等选项中指定大写字母或大小写混合的名字必须用双引号界定，否则将被自动转换为小写(参见模式匹配)。但是因为双引号在 shell 中有特殊含义，所以必须将双引号再放进单引号中。这样一来，要转储一个大小写混合的表名，你就需要像下面这样：

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

历史

pg_dump 工具最早出现在 Postgres95 0.02 版本。非纯文本输出格式在 PostgreSQL 7.1 时引入。

又见

pg_dumpall, pg_restore, psql, 环境变量(节29.12)