选择 打开 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。

受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
测试与开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10 / 9.6 / 9.5 / 9.4 / 9.3 / 9.2 / 9.1 / 9.0
历史版本PostgreSQL 9.0 已于 2015 年 10 月结束社区维护,本页译文保留供仍在使用旧版本的读者参考。新系统请看当前版本

pg_dump

pg_dump — 将 PostgreSQL 数据库导出为 SQL 脚本或其他格式

大纲

pg_dump [connection-option...] [option...] [dbname]

Description

pg_dump是一个用于备份PostgreSQL数据库的工具。即使数据库正在被并发使用,它也能生成一致的备份。pg_dump不会阻塞其他用户访问数据库(无论读还是写)。

转储可以输出为脚本格式或归档文件格式。脚本转储是纯文本文件,包含把数据库 重建到保存时状态所需的 SQL 命令。要从这样的脚本恢复,只需将其交给 psql。脚本文件甚至可以在其他机器和其他体系结构上 用于重建数据库;经过一些修改后,甚至也可以用于其他 SQL 数据库产品。

另一类归档文件格式必须结合 pg_restore 来重建数据库。 它们允许 pg_restore 有选择地恢复某些内容, 甚至在恢复之前重新排列条目。归档文件格式被设计为可跨体系结构移植。

当使用一种归档文件格式并与pg_restore结合使用时,pg_dump提供了一种灵活的归档和传输机制。pg_dump可以用来备份整个数据库,然后pg_restore可以用来检查归档和/或选择要恢复数据库的哪些部分。最灵活的输出文件格式是custom格式(-Fc)。它允许选择和重新排序所有归档条目,并且默认会被压缩。tar格式(-Ft)不压缩,并且在装载时对数据的重新排序有限制,但在其他方面相当灵活;此外,它可以用标准的 Unix 工具(如tar)来处理。

运行 pg_dump 时,应检查输出中是否有任何警告 (打印到标准错误),尤其要结合下面列出的限制来查看。

Options

下列命令行选项控制输出的内容和格式。

dbname

指定要转储的数据库名称。如果未指定,则使用环境变量PGDATABASE。 如果未设置该变量,则使用连接指定的用户名。

-a
--data-only

只转储数据,不转储模式(数据定义)。

此选项只对纯文本格式有意义。对于归档格式,可以在调用 pg_restore 时指定该选项。

-b
--blobs

在转储中包含大对象。除非指定了 --schema--table--schema-only,否则这是默认行为。因此,-b 开关只在需要把大对象加入选择性转储时才有用。

-c
--clean

Output commands to clean (drop) database objects prior to (the commands for) creating them.

此选项只对纯文本格式有意义。对于归档格式,可以在调用 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 使用的 custom 格式归档。 与目录输出格式一起,这是最灵活的输出格式,因为它允许在恢复时手工 选择并重新排序归档条目。这种格式默认也会压缩。

t
tar

输出一个适合输入到pg_restoretar格式归档。这种输出格式允许在恢复时手工选择和重新排序归档条目,但有一个限制:表数据条目的相对顺序在恢复期间不能改变。此外,tar格式不支持压缩,并且单个表的大小限制为 8 GB。

-i
--ignore-version

一个已弃用、现在会被忽略的选项。

-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 OWNERSET 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 选中的表无论这些开关如何设置 都会被转储,而非表对象则不会被转储。

注意

当指定 -t 时,pg_dump 不会尝试转储所选表可能依赖的任何其他数据库对象。因此,不能保证 特定表转储的结果能够单独成功恢复到一个干净的数据库中。

注意

-t开关的行为与 8.2 之前的PostgreSQL版本并不完全向上兼容。以前,写成-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

指定所用的压缩级别。零表示不压缩。对于自定义格式归档,该选项指定对各个表数据段的压缩,默认以适中的级别压缩。对于纯文本输出,设置非零压缩级别会压缩整个输出文件,就像将其传给gzip处理一样;但默认不压缩。tar 归档格式目前完全不支持压缩。

--binary-upgrade

此选项供就地升级实用程序使用。不建议或支持将其用于其他目的。该选项的行为可能在未来的版本中更改而不另行通知。

--inserts

将数据转储为INSERT命令(而不是COPY)。这会使恢复变得非常缓慢;它主要用于生成可装载到非PostgreSQL数据库的转储。不过,由于此选项为每一行生成单独的命令,重新装载某一行时出错只会导致该行丢失,而不会导致整个表的内容丢失。注意,如果重新排列了列顺序,恢复可能会完全失败。--column-inserts选项不受列顺序变化影响,但会更慢。

--column-inserts
--attribute-inserts

将数据转储为带有显式列名的INSERT命令 (INSERT INTO table (column, ...) VALUES ...)。这会使恢复变得非常缓慢;它主要用于生成可装入 非 PostgreSQL 数据库的转储文件。不过,由于此选项为每一行生成单独的命令,重新装载某一行时出错只会导致该行丢失,而不会导致整个表的内容丢失。

--disable-dollar-quoting

此选项禁用函数体中的 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 所需权限,但可以切换到具有所需权限的 角色时,此选项很有用。有些安装环境有禁止直接以超级用户登录的策略,使用 此选项就可以在不违反该策略的情况下进行转储。

Environment

PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER

默认连接参数。

和大多数其他 PostgreSQL 工具一样,这个工具也使用 libpq 支持的环境变量(见 第 31.13 节)。

Diagnostics

pg_dump 在内部执行 SELECT 语句。如果运行 pg_dump 时遇到问题,请确认能够 例如使用 psql 从数据库中查询信息。此外, libpq 前端库所使用的任何默认连接设置和环境变量 也都会生效。

pg_dump的数据库活动通常会被统计收集器收集。如果不希望如此,你可以通过PGOPTIONSALTER USER命令把参数track_counts设置为 false。

Notes

如果数据库集簇在 template1 数据库中有任何本地添加 的内容,要小心把 pg_dump 的输出恢复到一个真正 空的数据库中;否则很可能因为这些新增对象的重复定义而报错。要创建一个不含 任何本地添加的空数据库,应从 template0 而不是 template1 复制,例如:

CREATE DATABASE foo WITH TEMPLATE template0;

当选择不包含模式的转储并使用 --disable-triggers 选项时, pg_dump 会在插入数据前发出命令禁用用户表上的 触发器,并在数据插入完成后发出命令重新启用它们。如果恢复在中途停止, 系统目录可能会保持在错误状态。

tar 归档的成员被限制为小于 8 GB 的尺寸。(这是 tar 文件格式固有的限制。)因此,如果任何一个表的文本表示超过了这个尺寸,就不能使用这种格式。tar 归档和任何其他输出格式的总大小没有限制,除非操作系统有限制。

pg_dump生成的转储文件不包含优化器用于决定查询计划的统计信息。因此,从转储文件恢复后,最好运行ANALYZE以确保最佳性能;更多信息请参阅第 23.1.3 节第 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的输出能够装载到更旧主版本的服务器中—即使转储正是从该版本的服务器上取得的。把转储文件装载到较旧的服务器时,可能需要手工编辑转储文件,以移除较旧服务器不理解的语法。

Examples

要将名为 mydb 的数据库转储到 SQL 脚本文件中:

$ pg_dump mydb > db.sql

要将这样的脚本重新装载到一个新创建的数据库中,其名称为 newdb

$ psql -d newdb -f db.sql

要把一个数据库转储为 custom 格式归档文件:

$ 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

要转储名称以 eastwest 开头、并且以 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

提交更正

译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。