选择 打开 改范围 完整检索页
受支持版本: 当前版本 (18) / 17 / 16 / 15 / 14
开发版本: 19 / devel
不受支持的版本: 13 / 12 / 11 / 10
当前 PostgreSQL 版本不在支持生命周期内。
您可以参阅当前版本的对应页面,或其他在上面列出的活跃大版本。

pg_dumpall

pg_dumpall — 将一个PostgreSQL数据库集簇转储为脚本文件

Synopsis

pg_dumpall [connection-option...] [option...]

描述

pg_dumpall是一个实用程序,用于写出(转储)一个集簇中的所有PostgreSQL数据库到一个脚本文件中。该脚本文件包含SQL命令,可作为psql的输入来恢复这些数据库。它通过对集簇中的每个数据库调用pg_dump来实现这一点。pg_dumpall还会转储所有数据库共有的全局对象,即数据库角色、表空间以及配置参数的权限授予。 (pg_dump不会保存这些对象。)

由于pg_dumpall会读取所有数据库中的表,因此通常必须以数据库超级用户身份连接,才能生成完整的转储。另外,要执行保存的脚本,也需要具备超级用户权限,这样才能添加角色并创建数据库。

SQL 脚本将写入标准输出。使用-f/--file选项或 shell 操作符将其重定向到文件。

pg_dumpall需要多次连接到PostgreSQL服务器(每个数据库一次)。如果使用密码认证,它每次都会提示输入密码。在这种情况下准备一个~/.pgpass文件会比较方便。详见Section 33.15

Warning

恢复转储会导致目标系统执行由源超级用户所选择的任意代码。部分转储和部分恢复也无法限制这一点。如果不信任源超级用户,则在恢复前必须检查转储出的 SQL 语句。注意,执行转储和恢复的客户端并不需要信任源超级用户或目标超级用户。

选项

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

-a
--data-only

只转储数据,不转储模式(数据定义)或统计信息。

-c
--clean

在重新创建之前,输出用于DROP所有已转储数据库、角色和表空间的 SQL 命令。当恢复需要覆盖现有集簇时,此选项很有用。如果目标集簇中不存在某些对象,则恢复期间会报告可忽略的错误消息,除非还指定了--if-exists

-E encoding
--encoding=encoding

在指定的字符集编码中创建转储。默认情况下,转储将以数据库编码创建。(获得相同结果的另一种方法是将PGCLIENTENCODING环境变量设置为所需的转储编码。)

-f filename
--file=filename

将输出发送到指定文件。如果省略此选项,则使用标准输出。

-g
--globals-only

只转储全局对象(角色和表空间),不转储数据库。

-O
--no-owner

不要输出用于将对象所有权设置为与原始数据库一致的命令。默认情况下,pg_dumpall会发出ALTER OWNERSET SESSION AUTHORIZATION语句,以设置已创建模式元素的所有权。除非该脚本由超级用户(或拥有脚本中全部对象的同一用户)启动,否则这些语句在运行时会失败。若要创建一个可由任意用户恢复、并让该用户获得所有对象所有权的脚本,请指定-O

-r
--roles-only

只转储角色,不转储数据库或表空间。

-s
--schema-only

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

-S username
--superuser=username

指定在禁用触发器时要使用的超级用户名。只有在使用--disable-triggers时才相关。(通常更好的做法是省略此选项,而以超级用户身份运行生成的脚本。)

-t
--tablespaces-only

只转储表空间,不转储数据库或角色。

-v
--verbose

指定详细模式。这会让pg_dumpall把开始/停止时间写入转储文件,并将进度消息输出到标准错误。它还会启用pg_dump的详细输出。

-V
--version

打印pg_dumpall的版本并退出。

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

阻止转储访问权限(GRANT/REVOKE 命令)。

--binary-upgrade

此选项供就地升级工具使用。不建议也不支持将其用于其他用途。该选项的行为在将来的发行版中可能会在不另行通知的情况下发生变化。

--column-inserts
--attribute-inserts

将数据转储为带有显式列名的INSERT命令 (INSERT INTO table (column, ...) VALUES ...)。这会使恢复变得非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。

--disable-dollar-quoting

此选项禁用函数体中的 dollar quoting,并强制改用 SQL 标准字符串语法对它们进行引用。

--disable-triggers

此选项只在创建包含数据但不包含模式的转储时才相关。它指示pg_dumpall在输出中包含一些命令,以便在恢复数据时临时禁用目标表上的触发器。如果这些表上存在不希望在数据恢复期间触发的引用完整性检查或其他触发器,请使用此选项。

目前,为--disable-triggers输出的这些命令必须由超级用户执行。因此,还应通过-S指定一个超级用户名,或者更好的做法是确保以超级用户身份运行生成的脚本。

--exclude-database=pattern

不转储名称匹配pattern的数据库。可以多次写--exclude-database开关,以排除匹配多个模式的数据库。pattern参数按照psql\d命令所使用的同样规则解释(见Patterns),因此也可以通过在模式中使用通配符来排除多个数据库。使用通配符时,如有需要请小心为模式加引号,以防止 shell 展开通配符。

--extra-float-digits=ndigits

在转储浮点数据时,使用指定的 extra_float_digits 值,而不是最大可用精度。出于备份目的的常规转储不应使用此选项。

--if-exists

使用DROP ... IF EXISTS命令在--clean模式下删除对象。这会抑制原本可能报告的does not exist错误。除非同时指定了--clean,否则此选项无效。

--inserts

将数据转储为INSERT命令(而不是COPY)。这会使恢复非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。注意,如果重新安排了列顺序,恢复可能会彻底失败。--column-inserts选项可以避免列顺序变化带来的问题,但速度更慢。

--load-via-partition-root

当为表分区转储数据时,让COPYINSERT语句以包含该分区的分区层次结构根为目标,而不是以该分区本身为目标。这会导致在加载数据时为每一行重新确定适当的分区。当在另一台服务器上恢复数据,而行并不总是落在与原始服务器相同的分区中时,这可能很有用。例如,如果分区列是 text 类型,而两个系统对用于排序该分区列的排序规则定义不同,就可能发生这种情况。

--lock-wait-timeout=timeout

在转储开始时,不要无限等待获取共享表锁。如果无法在指定的timeout内锁定某个表,就让转储失败。超时可以用SET statement_timeout接受的任意格式指定。允许的值因被转储的服务器版本而异,但从 7.3 起,所有版本都接受以毫秒为单位的整数。对 7.3 之前的服务器进行转储时,此选项会被忽略。

--no-comments

不转储注释。

--no-publications

不要转储发布。

--no-role-passwords

不要转储角色密码。恢复后,角色的密码值将为 null,在设置密码之前,密码认证始终会失败。由于指定此选项时不需要密码值,角色信息将从目录视图pg_roles而不是pg_authid读取。因此,如果某些安全策略限制了对pg_authid的访问,此选项也会有帮助。

--no-security-labels

不要转储安全标签。

--no-subscriptions

不要转储订阅。

--no-sync

默认情况下,pg_dumpall会等待所有文件都被安全写入磁盘。该选项会使pg_dumpall立即返回而不等待,这样更快,但意味着随后如果操作系统崩溃,转储可能会损坏。通常,此选项适用于测试,但不应在从生产安装转储数据时使用。

--no-tablespaces

不输出创建表空间的命令,也不输出用于为对象选择表空间的命令。使用此选项时,所有对象在恢复时都会创建在当时默认的表空间中。

--no-unlogged-table-data

不要转储不记录 WAL 的表的内容。此选项不影响是否转储表定义(模式);它只会抑制转储表数据。

--on-conflict-do-nothing

INSERT命令中添加ON CONFLICT DO NOTHING。除非同时指定了--inserts--column-inserts,否则此选项无效。

--quote-all-identifiers

强制为所有标识符加引号。当从其PostgreSQL主版本与pg_dumpall不同的服务器转储数据库时,或者当输出打算装入另一主版本服务器中时,建议使用此选项。默认情况下,pg_dumpall只会给在其自身主版本中属于保留字的标识符加引号。处理其他版本服务器时,这有时会带来兼容性问题,因为它们的保留字集合可能略有不同。使用--quote-all-identifiers可以避免这类问题,但代价是转储脚本更难阅读。

--restrict-key=restrict_key

在转储输出中,把给定字符串用作psql\restrict键。若未指定限制键,pg_dumpall会按需要随机生成一个。键只能包含字母数字字符。

此选项主要用于测试以及其他需要可重复输出的场景(例如比较转储文件)。一般不建议使用它,因为若恶意服务器事先知道该键,可能注入任意代码,并在运行psql处理转储输出的机器上执行。

--rows-per-insert=nrows

将数据转储为INSERT命令(而不是COPY)。它控制每个INSERT命令的最大行数。指定的值必须是大于零的数字。恢复过程中的任何错误将导致只有属于有问题的INSERT的行丢失,而不是整个表的内容。

--use-set-session-authorization

输出符合 SQL 标准的SET SESSION AUTHORIZATION命令,而不是用ALTER OWNER命令来确定对象所有权。这会让转储更符合标准,但根据转储中对象的历史,可能无法正确恢复。

-?
--help

显示关于pg_dumpall命令行参数的帮助信息,并退出。

以下命令行选项控制数据库连接参数。

-d connstr
--dbname=connstr

连接字符串形式指定用于连接服务器的参数;这些参数将覆盖任何冲突的命令行选项。

该选项名为--dbname,是为了与其他客户端应用程序保持一致;但由于pg_dumpall需要连接多个数据库,连接字符串中的数据库名将被忽略。请使用-l选项指定初始连接所用的数据库名,该连接将用于转储全局对象并发现还应转储哪些数据库。

-h host
--host=host

指定运行数据库服务器的机器的主机名。如果该值以斜杠开头,则将其用作 Unix 域套接字的目录。默认值取自PGHOST环境变量(如果已设置);否则会尝试使用 Unix 域套接字连接。

-l dbname
--database=dbname

指定用于转储全局对象并发现还应转储哪些数据库的连接数据库名。如果未指定,则使用postgres数据库;如果该数据库不存在,则使用template1

-p port
--port=port

指定服务器监听连接的 TCP 端口,或本地 Unix 域套接字文件扩展名。默认值取自PGPORT环境变量(如果已设置),否则使用编译时默认值。

-U username
--username=username

用于连接的用户名。

-w
--no-password

绝不提示输入密码。如果服务器要求密码认证,而又无法通过.pgpass文件等其他方式获得密码,则连接尝试会失败。该选项适用于批处理作业和脚本,因为这些场景下没有用户可以输入密码。

-W
--password

强制pg_dumpall在连接数据库之前提示输入密码。

此选项从来都不是必需的,因为如果服务器要求密码认证,pg_dumpall会自动提示输入密码。不过,pg_dumpall会浪费一次连接尝试来发现服务器需要密码。在某些情况下,键入-W以避免这次额外的连接尝试是值得的。

注意,对每个要转储的数据库都会再次提示输入密码。通常,最好设置一个~/.pgpass文件,而不是依赖手工输入密码。

--role=rolename

指定一个角色名,用于创建转储。此选项会使pg_dumpall在连接数据库后发出SET ROLE rolename命令。当已认证用户(由-U指定)缺少pg_dumpall所需权限,但可以切换到具备所需权限的角色时,这很有用。有些安装环境不允许直接以超级用户身份登录,而使用此选项可以在不违反该策略的情况下完成转储。

环境

PGHOST
PGOPTIONS
PGPORT
PGUSER

默认连接参数

PG_COLOR

指定是否在诊断消息中使用颜色。可取值为alwaysautonever

与大多数其他PostgreSQL工具一样,此实用程序也使用libpq支持的环境变量(见Section 33.14)。

注解

由于pg_dumpall在内部调用pg_dump,因此某些诊断消息会提到pg_dump

即使目标是将转储脚本恢复到一个全新的集簇中,--clean选项也可能很有用。使用--clean后,脚本可以删除并重新创建内置的postgrestemplate1数据库,从而确保这些数据库保留与源集簇中相同的属性(例如区域设置和编码)。如果不使用此选项,这些数据库将保留其现有的数据库级属性,以及任何预先存在的内容。

恢复完成后,最好对每个数据库运行ANALYZE,以便优化器获得有用的统计信息。也可以运行vacuumdb -a -z来分析所有数据库。

不应指望该转储脚本在执行时完全不出现错误。特别是,由于脚本会为源集簇中存在的每个角色发出CREATE ROLE,因此除非目标集簇使用不同的引导超级用户名初始化,否则一定会遇到针对引导超级用户的role already exists错误。这个错误是无害的,应当忽略。使用--clean还可能产生一些关于不存在对象的额外无害错误消息,不过可以通过添加--if-exists来尽量减少这些消息。

pg_dumpall要求在恢复之前,所有必需的表空间目录都已经存在;否则,位于非默认位置的数据库在创建时将会失败。

通常建议在从pg_dumpall脚本恢复数据库时使用-X--no-psqlrc)选项,以确保恢复过程干净,并避免与非默认psql配置发生潜在冲突。此外,由于pg_dumpall脚本可能包含psql元命令,因此它可能与psql以外的客户端不兼容。

示例

要转储所有数据库:

$ pg_dumpall > db.out

要从此文件恢复数据库,可以使用:

$ psql -X -f db.out -d postgres

这里连接到哪个数据库并不重要,因为由 pg_dumpall 创建的脚本文件会包含适当的命令,用于创建并连接到已保存的数据库。例外是,如果指定了 --clean,就必须首先连接到 postgres 数据库;脚本会立即尝试删除其他数据库,而对于当前连接的数据库,这种操作会失败。

另见

有关可能出现的错误情况,请参见pg_dump