Postgresql 中文操作指南

pg_dumpall

pg_dumpall — 将 PostgreSQL 数据库群集提取到脚本文件中

Synopsis

pg_dumpall [ connection-option …​] [ option …​]

Description

pg_dumpall 是一个将群集中的所有 PostgreSQL 数据库写入(“转储”)一个脚本文件的实用程序。脚本文件包含 SQL 命令,这些命令可用作 psql 的输入,以还原数据库。它通过为群集中的每个数据库调用 pg_dump 来执行此操作。pg_dumpall 还会转储所有数据库共有的全局对象,即数据库角色、表空间和配置参数的特权授予。(pg_dump 不会保存这些对象。)

由于 pg_dumpall 需从所有数据库读取表,因此为了生成完整的转储文件,你很可能必须以数据库超级用户的身份连接。此外,你需要超级用户特权才能执行已保存的脚本,以便被允许添加角色和创建数据库。

SQL 脚本将被写到标准输出。使用 -f / —​file 选项或 shell 运维符将它重定向到一个文件中。

pg_dumpall 需要连接到 PostgreSQL 服务器多次(每个数据库一次)。如果你使用密码身份验证,则它每次都会要求输入密码。在这些情况下,使用 ~/.pgpass 文件会比较方便。有关更多信息,请参阅 Section 34.16

Options

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

  • -a_—​data-only_

    • 仅转储数据,不转储架构(数据定义)。

  • -c_—​clean_

    • 发出 SQL 命令以 DROP 在重新创建所有已转储的数据库、角色和表空间之前对其进行还原。当还原需要覆盖现有群集时,此选项非常有用。如果任何对象在目标群集内不存在,则在还原过程中将报告可忽略的错误消息,除非 —​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 将开始/停止时间输出到转储文件,并将进度消息输出到标准错误。重复此选项将导致标准错误上出现更多 debug 级别消息。此选项还会传给 pg_dump。

  • -V_—​version_

    • 打印 pg_dumpall 版本并退出。

  • -x—​no-privileges_—​no-acl_

    • 防止转储访问权限(授予/撤消命令)。

  • —​binary-upgrade

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

  • —​column-inserts_—​attribute-inserts_

    • 将数据转储为具有显式列名( INSERT INTO _table ( column , …​) VALUES …​)的 _INSERT 命令。这将使还原非常缓慢;它主要用于制作可以载入非 PostgreSQL 数据库的转储。

  • —​disable-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 模式删除对象。这会抑制可能报告的“不存在”错误。除非同时指定 —​clean ,否则此选项无效。

  • —​inserts

    • 将数据转储为 INSERT 命令(而不是 COPY )。这将使还原非常缓慢;它主要用于制作可以载入非 PostgreSQL 数据库的转储。请注意,如果你已经重新排列了列的顺序,还原可能会完全失败。 —​column-inserts 选项更安全,但速度更慢。

  • —​load-via-partition-root

    • 转储表分区的数据时,请使 COPYINSERT 语句的目标是包含它的分区层次结构的根,而不是分区本身。这将导致在加载数据时为每行重新确定适当的分区。这在恢复服务器上的数据时可能很有用,因为行不一定总是像在原始服务器上那样分布在相同的分区中。例如,如果分区列的类型为文本,而这两个系统对用于对分区列进行排序的排序规则有不同的定义,则可能会发生这种情况。

  • —​lock-wait-timeout=_timeout_

    • 不要在转储开始时一直等待以获取共享表锁。相反,如果无法在指定的 timeout 中锁定表,则失败。超时可以在 SET statement_timeout 接受的任何格式中指定。

  • —​no-comments

    • Do not dump comments.

  • —​no-publications

    • Do not dump publications.

  • —​no-role-passwords

    • 不要转储角色的密码。恢复后,角色将拥有一个空密码,并且在设置密码之前,密码身份验证将始终失败。由于在此选项指定时不需要密码值,因此角色信息将从目录视图 pg_roles 中读取,而不是 pg_authid 中读取。因此,当对 pg_authid 的访问受某些安全策略限制时,此选项也会提供帮助。

  • —​no-security-labels

    • 不要转储安全标签。

  • —​no-subscriptions

    • Do not dump subscriptions.

  • —​no-sync

    • 默认情况下, pg_dumpall 将等待所有文件安全地写入到磁盘中。此选项导致 pg_dumpall 在不等待的情况下返回,这更快,但意味着随后的操作系统崩溃可能会导致转储损坏。通常,此选项对于测试很有用,但当从生产安装中转储数据时不应使用。

  • —​no-table-access-method

    • 不要输出要选择表访问方法的命令。使用此选项后,所有对象将在恢复时使用默认的表访问方法创建。

  • —​no-tablespaces

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

  • —​no-toast-compression

    • 不要输出要设置 TOAST 压缩方法的命令。使用此选项后,所有列都将使用默认压缩设置恢复。

  • —​no-unlogged-table-data

    • 不要转储未记录表的目录。此选项对是否转储表定义(模式)没有影响;它只禁止转储表数据。

  • —​on-conflict-do-nothing

    • ON CONFLICT DO NOTHING 添加到 INSERT 命令中。只有在还指定了 —​inserts—​column-inserts 时,此选项才有效。

  • —​quote-all-identifiers

    • 强制引用所有标识符。建议在从 PostgreSQL 主版本与 pg_dumpall 不同的服务器转储数据库,或当输出打算加载到不同主版本的服务器时使用此选项。默认情况下,pg_dumpall 仅引用在其自己的主版本中是保留字的标识符。在处理可能包含稍微不同的保留字集的其他版本的服务器时,这有时会导致兼容性问题。使用 —​quote-all-identifiers 可以防止出现此类问题,代价是转储脚本更难阅读。

  • —​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

    • 指定连接到服务器时使用的参数,作为 connection string ;这些参数将覆盖任何冲突的命令行选项。

    • 此选项名为 —​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 所需的权限,但可以切换到具有所需权限的角色,那么此选项很有用。某些安装程序有政策反对以超级用户身份直接登录,使用此选项就可以不违反政策进行备份。

Environment

  • PGHOST_PGOPTIONS_PGPORT__PGUSER

    • Default connection parameters

  • PG_COLOR

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

此实用程序与大多数其他 PostgreSQL 实用程序一样,还使用 libpq 支持的环境变量(请参阅 Section 34.15 )。

Notes

由于 pg_dumpall 在内部调用了 pg_dump,因此某些诊断消息将引用 pg_dump。

即使您打算将备份脚本恢复到一个全新的群集, —​clean 选项仍然很有用。使用 —​clean 授权脚本删除并重新创建内置的 postgrestemplate1 数据库,以确保这些数据库保留与源群集相同的属性(例如语言环境和编码)。没有这个选项,这些数据库将保留其现有的数据库级别属性,以及所有已存在的数据库内容。

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

不应期望备份脚本完全运行不会出现错误。特别是,由于该脚本将为源群集中存在的每个角色发出 CREATE ROLE ,因此,除非目标群集使用不同的 bootstrap 超级用户名称初始化,否则肯定会获得“角色已存在”错误,这是针对 bootstrap 超级用户来说的。该错误无害,应当予以忽略。使用 —​clean 选项可能会生成有关不存在的对象的其他无害错误消息,但您可以通过添加 —​if-exists 来将这些消息最小化。

在恢复之前,pg_dumpall 要求有所有需要的表空间目录;否则,不在默认位置的数据库的数据库创建将会失败。

Examples

要备份所有数据库:

$ pg_dumpall > db.out

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

$ psql -f db.out postgres

将连接到哪个数据库并不重要,因为由 pg_dumpall 创建的脚本文件将包含适当的命令,以创建并连接到已保存的数据库。例外情况是,如果您指定了 —​clean ,那么您必须首先连接到 postgres 数据库;脚本将尝试立即删除其他数据库,而这对于您已连接到的数据库会失败。

See Also

查看 pg_dump ,了解有关可能错误条件的详细信息。