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文件。有关更多信息，请参阅第 34.16 节。

选项

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

-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 OWNER 或 SET 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

禁止转储访问权限（授予/撤消命令）。

--binary-upgrade

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

--column-inserts
--attribute-inserts

以带有显式列名的 INSERT 命令转储数据（INSERT INTO table (column, ...) VALUES ...）。这会使恢复非常缓慢；它主要用于生成可加载到非 PostgreSQL 数据库中的转储。

--disable-dollar-quoting

此选项禁用对函数体的美元引用，并强制使用 SQL 标准字符串语法对其进行引用。

--disable-triggers

此选项仅在创建仅数据转储时相关。它指示 pg_dumpall 在恢复数据时包含在目标表上暂时禁用触发器的命令。如果您在表上具有引用完整性检查或其他触发器，而您不希望在数据恢复期间调用这些触发器，请使用此选项。

目前，为 --disable-triggers 发出的命令必须作为超级用户执行。因此，您还应该使用 -S 指定一个超级用户名称，或者最好小心地以超级用户身份启动结果脚本。

--exclude-database=pattern

不转储名称与 pattern 匹配的数据库。可以通过编写多个 --exclude-database 开关来排除多个模式。 pattern 参数根据 psql 的 \d 命令使用的相同规则解释为模式（请参见 模式），因此还可以通过在模式中编写通配符来排除多个数据库。在使用通配符时，请小心引用模式（如果需要），以防止 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

转储表分区的数据时，让 COPY 或 INSERT 语句针对包含该分区的分区层次结构的根，而不是分区本身。这会导致在加载数据时为每一行重新确定适当的分区。当在服务器上还原数据时，如果行并不总是位于与原始服务器相同的分区中，这可能很有用。例如，如果分区列的类型为文本，并且两个系统对用于对分区列进行排序的校对有不同的定义，则可能会发生这种情况。

--lock-wait-timeout=timeout

不要无限期地等待在转储开始时获取共享表锁。相反，如果无法在指定的 timeout 内锁定表，则失败。超时可以使用 SET statement_timeout 接受的任何格式指定。

--no-comments

不要转储注释。

--no-publications

不要转储发布。

--no-role-passwords

不要转储角色的密码。还原时，角色将具有空密码，并且密码验证在设置密码之前将始终失败。由于在指定此选项时不需要密码值，因此从目录视图 pg_roles 而不是 pg_authid 读取角色信息。因此，如果某些安全策略限制了对 pg_authid 的访问，此选项也有帮助。

--no-security-labels

不要转储安全标签。

--no-subscriptions

不要转储订阅。

--no-sync

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

--no-table-access-method

不要输出用于选择表访问方法的命令。使用此选项，所有对象都将使用还原期间的默认表访问方法创建。

--no-tablespaces

不要输出用于创建表空间或为对象选择表空间的命令。使用此选项，所有对象都将在还原期间的默认表空间中创建。

--no-toast-compression

不要输出用于设置压缩方法的命令。使用此选项，所有列都将使用默认压缩设置还原。

--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

指定用于连接到服务器的参数，作为连接字符串；这些参数将覆盖任何冲突的命令行选项。

该选项称为 --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

指定是否在诊断消息中使用颜色。可能的值为 always、auto 和 never。

此实用程序与大多数其他PostgreSQL实用程序一样，也使用libpq支持的环境变量（请参阅第 34.15 节）。

注释

由于pg_dumpall在内部调用pg_dump，因此一些诊断消息将引用pg_dump。

即使您打算将转储脚本还原到新集群中，--clean选项也可能很有用。使用--clean授权脚本删除并重新创建内置postgres和template1数据库，确保这些数据库保留与源集群中相同的属性（例如，语言环境和编码）。如果没有此选项，这些数据库将保留其现有的数据库级属性以及任何预先存在的的内容。

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

转储脚本不应被期望完全无错误地运行。特别是，由于脚本将为源集群中存在的每个角色发出CREATE ROLE，因此，除非目标集群使用不同的引导超级用户名称进行初始化，否则肯定会出现引导超级用户的“角色已存在”错误。此错误无害，应予以忽略。使用--clean选项可能会产生有关不存在对象的附加无害错误消息，但可以通过添加--if-exists来最小化这些错误消息。

pg_dumpall要求在还原之前存在所有必需的表空间目录；否则，将为非默认位置的数据库创建失败。

示例

转储所有数据库

$ pg_dumpall > db.out

要从此文件还原数据库，可以使用

$ psql -f db.out postgres

在此连接到哪个数据库并不重要，因为pg_dumpall创建的脚本文件将包含创建和连接到已保存数据库的适当命令。例外情况是，如果您指定了--clean，则必须最初连接到postgres数据库；脚本将尝试立即删除其他数据库，并且对于您连接到的数据库，此操作会失败。

另请参见

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