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
)。这会使恢复非常缓慢;它主要用于生成可加载到非 PostgreSQL 数据库中的转储。table
(column
, ...) VALUES ...
--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
不要输出用于设置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
指定用于连接到服务器的参数,作为连接字符串;这些参数将覆盖任何冲突的命令行选项。
该选项称为 --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 以了解有关可能错误条件的详细信息。