NAME

       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

HISTORY 历史

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

SEE ALSO 参见

       pg_dumpall(1), pg_restore(1), psql(1)

译者

       Postgresql 中文网站 何伟平 <laser@pgsqldb.org>