pg_dump

Name

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

Synopsis

pg_dump [option...] [dbname]

描述

pg_dump 是一个用于备份 PostgreSQL 数据库的工具。它甚至可以在数据库正在并发使用的时候进行完整一致的备份。 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

在转储中包含大对象。必须选择一种非文本输出格式。

-c
--clean

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

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

-C
--create

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

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

-d
--inserts

将数据输出为的INSERT命令(而不是 COPY)。 这样会导致恢复非常缓慢。 这个选项主要用于制作那种可以用于其它非 PostgreSQL 数据库的转储。 请注意,如果你重新排列了字段顺序,那么恢复可能会完全失败。 -D 更安全,但是也更慢。

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

把数据转储为带有明确字段名的 INSERT 命令。 (INSERT INTO table(column, ...) VALUES ...)。 这样会导致恢复非常缓慢,它主要用于制作那种可以用于其它非 PostgreSQL 数据库的转储。

-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 的内容。 如果没有声明这个选项,所有目标数据库中的非系统模式都会被转储出来。

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

-o
--oids

作为数据的一部分,为每个表都输出对象标识(OID)。 如果你的应用在某种程度上引用了OID字段的话,(比如,在外键约束中用到)。 那么使用这个选项。否则,不应该使用这个选项。

-O
--no-owner

不把对象的所有权设置为对应源数据库。 通常, pg_dump 发出(psql特有的) ALTER OWNER 或者 SET SESSION AUTHORIZATION 语句以设置创建的数据库对象的所有权。 又见 -R-X use-set-session-authorization 选项。 请注意 -O 并不防止所有对数据库的重新联接, 只是防止那些为调整权限进行的排它联接。

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

-R
--no-reconnect

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

-s
--schema-only

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

-S username
--superuser=username

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

-t table
--table=table

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

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

-v
--verbose

声明冗余模式。 这样将令 pg_dump 输出详细的对象评注以及转储文件的启停时间和进度信息到标准输出上。

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

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

-X disable-dollar-quoting
--disable-dollar-quoting

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

-X disable-triggers
--disable-triggers

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

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

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

-X use-set-session-authorization
--use-set-session-authorization

输出 SQL 标准 SET SESSION AUTHORIZATION 命令而不是 OWNER TO 命令。 这样的转储结果更加复合标准,但是依赖转储中的对象的历史,可能不能正确恢复。

-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 有几个限制:

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

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

例子

转储一个数据库:

$ 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

历史

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

又见

pg_dumpall, pg_restore, psql