pg_dumpall
pg_dumpall — 将一个 PostgreSQL 数据库集簇转储为脚本文件
大纲
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 文件会比较方便。详见第 33.15 节。
选项
以下命令行选项控制输出的内容和格式。
-a--data-only只转储数据,不转储模式(数据定义)。
-c--clean包含用于在重新创建数据库之前清理(删除)数据库的 SQL 命令。也会添加用于角色和表空间的
DROP命令。-ffilename--file=filename将输出发送到指定文件。如果省略此选项,则使用标准输出。
-g--globals-only只转储全局对象(角色和表空间),不转储数据库。
-o--oids将对象标识符(OID)作为每个表的数据的一部分进行转储。如果应用程序以某种方式引用 OID 列(例如在外键约束中),请使用此选项。否则,不应使用此选项。
-O--no-owner不要输出用于将对象所有权设置为与原始数据库一致的命令。默认情况下,pg_dumpall 会发出
ALTER OWNER或SET SESSION AUTHORIZATION语句,以设置已创建模式元素的所有权。除非该脚本由超级用户(或拥有脚本中全部对象的同一用户)启动,否则这些语句在运行时会失败。若要创建一个可由任意用户恢复、并让该用户获得所有对象所有权的脚本,请指定-O。-r--roles-only只转储角色,不转储数据库或表空间。
-s--schema-only只转储对象定义(模式),不转储数据。
-Susername--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)。这会使恢复变得非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。table(column, ...) VALUES ...--disable-dollar-quoting此选项禁用对函数体的美元引用,并强制用 SQL 标准字符串语法对它们加引号。
--disable-triggers此选项只在创建仅数据转储时才相关。它指示 pg_dumpall 在输出中包含一些命令,以便在恢复数据时临时禁用目标表上的触发器。如果这些表上存在不希望在数据恢复期间触发的引用完整性检查或其他触发器,请使用此选项。
目前,为
--disable-triggers输出的这些命令必须由超级用户执行。因此,还应通过-S指定一个超级用户名,或者更好的做法是谨慎地以超级用户身份运行生成的脚本。--if-exists使用条件命令(即添加
IF EXISTS子句)来清理数据库和其他对象。只有同时指定--clean,此选项才有效。--inserts将数据转储为
INSERT命令(而不是COPY)。这会使恢复非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。注意,如果重新安排了列顺序,恢复可能会彻底失败。--column-inserts选项可以避免列顺序变化带来的问题,但速度更慢。--lock-wait-timeout=timeout在转储开始时,不要无限等待获取共享表锁。如果无法在指定的
timeout内锁定某个表,就让转储失败。超时可以用SET statement_timeout接受的任意格式指定。允许的值因被转储的服务器版本而异,但从 7.3 起,所有版本都接受以毫秒为单位的整数。对 7.3 之前的服务器进行转储时,此选项会被忽略。--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 的表的内容。此选项不影响是否转储表定义(模式);它只会抑制转储表数据。
--quote-all-identifiers强制为所有标识符加引号。当从其 PostgreSQL 主版本与 pg_dumpall 不同的服务器转储数据库时,或者当输出打算装入另一主版本服务器中时,建议使用此选项。默认情况下,pg_dumpall 只会给在其自身主版本中属于保留字的标识符加引号。处理其他版本服务器时,这有时会带来兼容性问题,因为它们的保留字集合可能略有不同。使用
--quote-all-identifiers可以避免这类问题,但代价是转储脚本更难阅读。--use-set-session-authorization输出符合 SQL 标准的
SET SESSION AUTHORIZATION命令,而不是用ALTER OWNER命令来确定对象所有权。这会让转储更符合标准,但根据转储中对象的历史,可能无法正确恢复。-?--help显示关于 pg_dumpall 命令行参数的帮助信息,并退出。
以下命令行选项控制数据库连接参数。
-dconnstr--dbname=connstr以连接字符串形式指定用于连接服务器的参数;这些参数将覆盖任何冲突的命令行选项。
该选项名为
--dbname,是为了与其他客户端应用程序保持一致;但由于 pg_dumpall 需要连接多个数据库,连接字符串中的数据库名将被忽略。请使用-l选项指定初始连接所用的数据库名,该连接将用于转储全局对象并发现还应转储哪些数据库。-hhost--host=host指定运行数据库服务器的机器的主机名。如果该值以斜杠开头,则将其用作 Unix 域套接字的目录。默认值取自
PGHOST环境变量(如果已设置);否则会尝试使用 Unix 域套接字连接。-ldbname--database=dbname指定用于转储全局对象并发现还应转储哪些数据库的连接数据库名。如果未指定,则使用
postgres数据库;如果该数据库不存在,则使用template1。-pport--port=port指定服务器正在监听连接的 TCP 端口,或本地 Unix 域套接字文件扩展名。默认值取自
PGPORT环境变量(如果已设置),否则使用编译时默认值。-Uusername--username=username用于连接的用户名。
-w--no-password绝不发出密码提示。如果服务器要求密码认证,而又无法通过
.pgpass文件等其他方式获得密码,则连接尝试将失败。在没有用户在场输入密码的批处理作业和脚本中,此选项很有用。-W--password强制 pg_dumpall 在连接数据库之前提示输入密码。
此选项从来都不是必需的,因为如果服务器要求密码认证,pg_dumpall 会自动提示输入密码。不过,pg_dumpall 会浪费一次连接尝试来发现服务器需要密码。在某些情况下,键入
-W以避免这次额外的连接尝试是值得的。注意,对每个要转储的数据库都会再次提示输入密码。通常,最好设置一个
~/.pgpass文件,而不是依赖手工输入密码。--role=rolename指定一个角色名,用于创建转储。此选项会使 pg_dumpall 在连接数据库后发出
SET ROLErolename命令。当已认证用户(由-U指定)缺少 pg_dumpall 所需权限,但可以切换到具备所需权限的角色时,这很有用。有些安装环境不允许直接以超级用户身份登录,而使用此选项可以在不违反该策略的情况下完成转储。
注意
由于 pg_dumpall 在内部调用 pg_dump,因此某些诊断消息会提到 pg_dump。
恢复完成后,最好对每个数据库运行 ANALYZE,以便优化器获得有用的统计信息。也可以运行 vacuumdb -a -z 来分析所有数据库。
pg_dumpall 要求在恢复之前,所有必需的表空间目录都已经存在;否则,位于非默认位置的数据库在创建时将会失败。
示例
要转储所有数据库:
$pg_dumpall > db.out
要从此文件重新装载数据库,可以使用:
$psql -f db.out postgres
(这里连接哪个数据库并不重要,因为 pg_dumpall 创建的脚本文件会包含适当的命令,用于创建并连接到已保存的数据库。)
另见
有关可能出现的错误情况,请参见 pg_dump。