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

SYNOPSIS

pg_dump [ option...] [ dbname]

DESCRIPTION 描述

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

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

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

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

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

OPTIONS 选项

下面的命令行参数用于控制输出格式。

dbname

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

-a

--data-only

只输出数据，不输出结构（表定义）。

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

-b

--blobs

在转储中包含大对象。

-c

--clean

输出在创建数据库创建命令之前先清理（删除）该数据库对象的命令。

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

-C

--create

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

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

-d

--inserts

将数据输出为的 INSERT 命令（而不是 COPY）。这样会导致恢复非常缓慢。但却令归档更容易移植到其它 SQL 数据库。

-D

--column-inserts

--attribute-inserts

把数据转储为带有明确字段名的 INSERT 命令。（INSERT INTO table(column, ...) VALUES ...）。这样会导致恢复非常缓慢，但是如果你想重新排列字段的顺序，那么它是必须的。

-f file

--file=file

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

-F format

--format=format

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

p: 输出纯文本SQL脚本文件（缺省）
t: 输出适合输入到 pg_restore 里的tar归档文件。使用这个归档允许在恢复数据库时重新排序和/或把表结构排除在外。同时也可能可以在恢复的时候限制对哪些数据进行恢复。
c: 输出适于给 pg_restore 用的客户化归档。这是最灵活的格式，它允许对装载的数据和纲要元素进行重新排列。这个格式缺省的时候是压缩的。

-i

--ignore-version

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

pg_dump 可以处理来自以前版本的PostgreSQL 的数据库，但是太老的版本则不被支持了（目前是支持到 7.0）。
如果你需要跨越版本检查时才使用这个选项（而且如 pg_dump 失效，别说我没警告你）。

-n namespace

--schema=schema

只转储 schema 的内容。如果没有声明这个选项，所有目标数据库中的非系统模式都会被转储出来。

: Note: 注意: 在这个模式里，pg_dump 并不试图转储任何其它选定模式可能依赖的数据库对象。
因此，系统不保证单一的一个模式的转储就可以成功地恢复到一个干净的数据库中去。

-o

--oids

为每个表都输出对象标识（OID）。如果你的应用在某种程度上引用了OID字段的话，（比如，在外键约束中用到）。那么使用这个选项。否则，不应该使用这个选项。

-O

--no-owner

不把对象的所有权设置为对应源数据库。 By default, pg_dump issues SET SESSION
AUTHORIZATION statements to set ownership of created schema elements. These
statements will fail when the script is run unless it is started by a superuser
(or the same user that owns all of the objects in the script). To make a script
that can be restored by any user, but will give that user ownership of all the
objects, specify -O.

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

-R

--no-reconnect

这个选项已经过时，但是出于向下兼容的考虑，仍然接受这个选项。

-s

--schema-only

只输出表纲要（定义），不输出数据。

-S username

--superuser=username

声明关闭触发器时需要用到的超级用户名。它只有使用了 --disable-triggers 的时候才有关系。（通常，我们最好不要输入这个参数，而是用超级用户启动生成的脚本。）

-t table

--table=table

只输出表 table 的数据。很可能是在不同模式里面有多个同名表；如果这样，那么所有匹配的表都将被转储出来。同时声明 --schema 和 --table 则只选择一个表。

: Note:

注意: 在这个模式里，pg_dump 并不试图转储任何其它选定表可能依赖的数据库对象。因此，系统不保证单一的一个表的转储就可以成功地恢复到一个干净的数据库中去。

-v

--verbose

声明冗余模式。这样将令 pg_dump 在标准错误上打印进度信息。

-x

--no-privileges

--no-acl

避免输出 ACL（赋予/撤消命令）和表的所有者关系信息。

-X use-set-session-authorization

--use-set-session-authorization

这个选项废弃了，保留它是为了向下兼容。 pg_dump 现在表现得总是想正式选取了这个选项一样。

-X disable-triggers

--disable-triggers

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

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

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

-Z 0..9

--compress=0..9

声明在那些支持压缩的格式中使用的压缩级别。（目前只有客户化格式支持压缩）。

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

-h host
--host=host: 声明运行服务器的机器的主机名。如果数值以斜扛开头，则它被用做到 Unix 域套接字的路径。缺省是从 PGHOST 环境变量中取得的，如果设置了这个环境变量的话，否则，尝试一个 Unix 域套接字连接。
-p port
--port=port: 声明服务器正在侦听并等待联接的 TCP 端口或本地 Unix 主控套接字文件句柄。缺省时使用环境变量 PGPORT 的值（如果存在），或者是编译时的缺省值。
-U username: 以给出用户身分联接。
-W: 强制口令提示。如果服务器需要口令认证，那么这个动作应该自动发生。

ENVIRONMENT 环境

PGDATABASE
PGHOST
PGPORT
PGUSER: 缺省连接参数

DIAGNOSTICS 诊断

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

NOTES 注意

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

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump 有几个限制：

*: 在转储一个表或者作为纯文本转储时，pg_dump 无法操作大对象。大对象必须整数据库地使用非文本归档格式之一进行转储。
*: 在进行纯数据转储时，并且使用了选项 --disable-triggers 的时候，pg_dump 发出一些查询先关闭在用户表上面的触发器，然后插入数据，数据插入完成后再发出查询打开触发器。如果恢复动作在中间停止，那么系统表可能就会处于一种错误状态。

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

恢复完之后，我们建议在每个已恢复的对象上运行 ANALYZE。这样优化器就可以得到有用的统计。

EXAMPLES 例子

转储一个数据库：

$ pg_dump mydb > db.out

重载这个数据库：

$ psql -d database -f db.out

输出一个叫 mydb 的包含BLOB 的数据库到一个 tar 文件：

$ pg_dump -Ft -b mydb > db.tar

把这个数据库（连同BLOB）一起恢复到一个现有的叫 newdb 的数据库：

$ pg_restore -d newdb db.tar