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文件会比较方便。详见第 31.14 节。
选项
下列命令行选项控制输出的内容和格式。
-a--data-only只转储数据,不转储模式(数据定义)或统计信息。
-c--clean包含用于在重新创建数据库之前清理(删除)数据库的 SQL 命令。也会添加用于角色和表空间的
DROP命令。-ffilename--file=filename将输出发送到指定文件。如果省略此选项,则使用标准输出。
-g--globals-only只转储全局对象(角色和表空间),不转储数据库。
-i--ignore-version一个已废弃的选项,现在会被忽略。
-o--oids将对象标识符(OID)作为每个表的数据的一部分进行转储。如果应用程序以某种方式引用 OID 列(例如在外键约束中),请使用此选项。否则,不应使用此选项。
-O--no-owner不要输出用于将对象所有权设置为与原始数据库一致的命令。默认情况下,pg_dumpall 会发出
ALTER OWNER或SET SESSION AUTHORIZATION语句,以设置已创建模式元素的所有权。除非该脚本由超级用户(或拥有脚本中全部对象的同一用户)启动,否则这些语句在运行时会失败。若要创建一个可由任意用户恢复、并让该用户获得所有对象所有权的脚本,请指定-O。--lock-wait-timeout=timeout在转储开始时,不要无限等待获取共享表锁。如果无法在指定的
timeout内锁定某个表,就让转储失败。超时可以用SET statement_timeout接受的任意格式指定。允许的值因被转储的服务器版本而异,但从 7.3 起,所有版本都接受以毫秒为单位的整数。对 7.3 之前的服务器进行转储时,此选项会被忽略。--no-tablespaces不要转储不记录 WAL 的表的内容。此选项不影响是否转储表定义(模式);它只会抑制转储表数据。
-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此选项供就地升级工具使用。不建议也不支持将其用于其他用途。该选项的行为在将来的发行版中可能会在不另行通知的情况下发生变化。
--binary-upgrade此选项供原地升级工具使用。不建议将其用于其他目的,也不支持这样用。该选项的行为可能在未来的版本中不经通知而改变。
--inserts将数据转储为
INSERT命令(而不是COPY)。这会使恢复非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。注意,如果重新安排了列顺序,恢复可能会彻底失败。--column-inserts选项更安全,但速度更慢。--column-inserts--attribute-inserts将数据转储为带有显式列名的
INSERT命令(INSERT INTO)。这会使恢复变得非常缓慢;它主要用于生成可以装入非 PostgreSQL 数据库的转储。table(column, ...) VALUES ...--disable-dollar-quoting此选项禁用函数体中的 dollar quoting,并强制改用 SQL 标准字符串语法对它们进行引用。
--disable-triggers此选项只在创建只包含数据而不包含模式的转储时才相关。它指示 pg_dumpall 在输出中包含一些命令,以便在重新载入数据时临时禁用目标表上的触发器。如果这些表上存在不希望在数据重新载入期间触发的引用完整性检查或其他触发器,请使用此选项。
目前,为
--disable-triggers输出的这些命令必须由超级用户执行。因此,还应通过-S指定一个超级用户名,或者更好的做法是确保以超级用户身份运行生成的脚本。--use-set-session-authorization输出符合 SQL 标准的
SET SESSION AUTHORIZATION命令,而不是用ALTER OWNER命令来确定对象所有权。这会让转储更符合标准,但根据转储中对象的历史,可能无法正确恢复。-?--help显示关于 pg_dumpall 命令行参数的帮助信息,并退出。
下列命令行选项控制数据库连接参数。
-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。