©
This document uses PHP Chinese website manual Release
pg_dump
Name
pg_dump -- 将一个PostgreSQL数据库转储到一个脚本文件或者其它归档文件中Synopsis
pg_dump [connection-option...] [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 在转储中包含大对象。除非指定了--schema,--table,--schema-only 开关，否则这是默认行为。因此-b开关仅用于在选择性转储的时候添加大对象。
-
-c
--clean -
输出在创建数据库创建命令之前先清理(drop)该数据库对象的命令。
call pg_restore. 这个选项只是对纯文本格式有意义。对于归档格式，可以在调用pg_restore 的时候声明该选项。
-
-C
--create -
以一条创建该数据库本身并且与这个数据库连接命令开头进行输出。如果是这种形式的脚本， 那么你在运行脚本之前和哪个数据库连接就不重要了。
这个选项只对纯文本格式有意义。对于归档格式，可以在调用pg_restore 的时候声明该选项。
-
-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 格式的归档。该输出格式允许手动选择并且在还原期间重排归档项的顺序，但是有一个 限制:表数据项的相关顺序在还原时不能更改。同时，tar格式不支持 压缩并且对独立表的大小限制为8GB。
-
p
-
-i
--ignore-version 一个现在被忽略的弃用选项。
-
-n schema
--schema=schema -
只转储匹配schema的模式内容， 包括模式本身以及其中包含的对象。如果没有声明这个选项，所有目标数据库中的 非系统模式都会被转储出来。可以使用多个-n选项指定多个模式。同样， schema参数将按照psql 的\d命令的规则(参见Patterns) 被解释为匹配模式，因此可以使用通配符匹配多个模式。在使用通配符的时候，最好 用引号进行界定，以防止 shell 将通配符进行扩展。
Note: 如果指定了-n，那么pg_dump将不会转储那些模式 所依赖的其他数据库对象。因此，无法保证转储出来的内容一定能够在另一个干净的数据库 中恢复成功。
Note: 非模式对象(比如大对象)不会在指定-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命令的规则(参见 Patterns)被解释为匹配模式， 因此可以使用通配符匹配多个模式。在使用通配符的时候，最好用引号进行界定，以防止 shell 将通配符进行扩展。
使用了-t之后，-n和-N选项就失效了。因为被-t 选中的表将无视 -n和-N选项而被转储，同时除了表之外的其他对象不会被转储。
Note: 如果指定了-t，那么pg_dump将不会转储任何 选中的表不依赖的其它数据库对象。因此，无法保证转储出来的表能在一个干净的数据库中成功恢复。
Note: -t选项与PostgreSQL8.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
这个选项是通过就地升级工具来使用的。不建议也不支持将其用于其他目的。 该选项的性能可能会在将来的版本中有所改变，而不另行通知。
- --inserts
它像INSERT命令（而不是COPY命令）一样转储数据。 这将使恢复非常缓慢；主要用于可以加载到非PostgreSQL 数据库的转储。然而，因为该选项为每一行生成一个单独的命令，重载一行的错误仅导致 丢失行而不是全部表内容。请注意恢复可能会完全失败，若您已重新安排列顺序。 --column-inserts选项相对于列顺序变化而言是安全的，尽管慢一些。
-
--column-inserts
--attribute-inserts 它像有显式列名的INSERT命令一样转储数据(INSERT INTO table(column, ...) VALUES ...)。这将使恢复非常缓慢；主要用于可以加载到非PostgreSQL 数据库的转储。然而，因为该选项为每一行生成一个单独的命令，重载一行的错误仅导致 丢失行而不是全部表内容。请注意恢复可能会完全失败，若您已重新安排列顺序。 --column-inserts选项相对于列顺序变化而言是安全的，尽管慢一些。
- --disable-dollar-quoting
这个选项关闭使用美元符界定函数体。强制它们用 SQL 标准的字符串语法的引号包围。
- --disable-triggers
-
这个选项只是和创建仅有数据的转储相关。它告诉pg_dump包含 在恢复数据时临时关闭目标表上触发器的命令。如果在表上有参照完整性检查或者其它触发器， 而恢复数据的时候不想重载他们，那么就应该使用这个选项。
目前，发出--disable-triggers的命令必须作为超级用户。所以，你还应该用 -S执行一个超级用户的名称。或者作为一个超级用户最好小心地启动结果脚本。
该选项仅对纯文本格式有意义。对于归档格式，当你调用pg_restore时， 你可以声明该选项。
- --lock-wait-timeout=timeout
不要永远等待在开始转储时获取共享表锁。相反，如果不能在指定的 timeout 中锁住一个表，那么就会失败。在SET statement_timeout接受的任何格式中 都可以声明超时。（允许该值按照您转储的服务器的情况变化，但一个整数的毫秒数却是所有7.3以后 版本都能接受的。当从一个7.3之前的服务器转储时，忽略该选项。）
- --no-tablespaces
-
不输出命令来选择表空间。在该选项内，在转期间当表空间默认时，所有的对象将都会创建。
这个选项只对纯文本格式有意义。对于归档格式，可以在调用pg_restore 的时候声明这个选项。
- --use-set-session-authorization
输出符合 SQL 标准的SET SESSION AUTHORIZATION命令而不是ALTER OWNER 命令。这样令转储更加符合标准，但是如果转储文件中的对象的历史有些问题，那么可能不能正确恢复。 并且，使用SET SESSION AUTHORIZATION的转储需要数据库超级用户的权限才能转储成功， 而ALTER OWNER需要的权限则低得多。
-
-?
--help 显示关于pg_dump命令行参数的帮助，并退出。
下面的命令行参数控制数据库的连接参数。
-
-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支持的 环境变量。
Diagnostics
pg_dump在内部执行SELECT语句。 如果您在运行pg_dump上有问题，确保您可以从使用的数据库中 选择信息，例如:psql。同时，libpq 前端库使用的任意默认连接设置和环境变量都将会适用。
pg_dump的数据库活动通常由统计数据收集器收集。 若这是不可取的，您可以通过PGOPTIONS或者ALTER USER命令 将track_counts设置为false。
注意
如果你的数据库给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和Section 23.1.5获取更多详细信息。 转储文件也不包括任何的ALTER DATABASE ... SET 命令；这些设置通过 pg_dumpall转储，连同数据库用户和其他安装宽度的设置。
因为pg_dump是用来将数据迁移到PostgreSQL 现版本的，pg_dump的输出预计能加载到比 pg_dump版本更新的PostgreSQL服务器版本。 pg_dump也可以从比其自身版本更老的PostgreSQL服务器 转储。（目前，支持后退到7.0版本的服务器。）然而，pg_dump不能转储 比其自身主版本更新的PostgreSQL服务器；它甚至将会拒绝尝试， 而不是冒险做一个无效的转储。同时，不能保证pg_dump事务输出能加载到 一个较旧的主版本—的服务器，即使从一个那个版本的服务器加载也是不可以的。 加载一个转储文件到一个较旧的服务器可能需要手动编辑转储文件来删除较旧的服务器不能 理解的语法。
示例
将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等选项中指定大写字母或大小写混合的名字必须用双引号界定，否则将被自动转 换为小写(参见Patterns)。 但是因为双引号在 shell 中有特殊含义，所以必须将双引号再放进单引号中。这样一来，要转储 一个大小写混合的表名，你就需要像下面这样：
$ pg_dump -t '"MixedCaseName"' mydb > mytab.sql