pg_dumpall — 将一个PostgreSQL数据库集簇抽取到一个脚本文件中
pg_dumpall
[connection-option
...] [option
...]
pg_dumpall是一个用于将集群中所有PostgreSQL数据库 写入(“dumping”)到一个脚本文件的实用程序。脚本文件包含 可以作为输入传递给psql以恢复数据库的SQL命令。 它通过为集群中的每个数据库调用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
防止访问权限的泄露(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
指定一个超级用户名称,或者最好小心地
以超级用户身份启动生成的脚本。
--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
当为表分区转储数据时,使COPY
或INSERT
语句
指向包含它的分区层次结构的根,而不是分区本身。这会导致在加载数据时为每一行重新确定适当的分区。
当在一个服务器上恢复数据时,这可能很有用,因为行不总是落入与原始服务器上相同的分区中。
例如,如果分区列是文本类型,并且两个系统对用于对分区列进行排序的排序规则的定义不同。
--lock-wait-timeout=timeout
不要在转储开始时永远等待获取共享表锁。相反,如果在指定的timeout
内无法锁定表,则失败。
超时可以以SET statement_timeout
接受的任何格式指定。
--no-comments
不要转储注释。
--no-publications
不要转储publication。
--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仅引用其自身主版本中的保留字标识符。
这有时会导致与其他版本服务器处理时出现兼容性问题,可能具有稍有不同的保留字集。
使用--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
数据库,如果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_dump在连接到数据库后发出一个SET ROLE
rolename
命令。当已认证用户(由-U
指定)缺少pg_dump所需的特权但是能够切换到一个具有所需权利的角色时,这个选项很有用。一些安装有针对直接作为超级用户登录的策略,使用这个选项可以让转储在不违反该策略的前提下完成。
PGHOST
PGOPTIONS
PGPORT
PGUSER
默认连接参数
PG_COLOR
规定在诊断消息中是否使用颜色。可能的值为always
、 auto
、never
。
和大部分其他PostgreSQL工具相似,这个工具也使用libpq(见第 34.15 节)支持的环境变量。
因为pg_dumpall在内部调用pg_dump,所以, 一些诊断消息可以参考pg_dump。
即使当用户的目的是把转储脚本恢复到一个空的集簇中,--clean
选项也有用武之地。--clean
的使用让该脚本删除并且重建内建的postgres
和template1
数据库,确保这两个数据库保持与源集簇中相同的属性(例如locale和编码)。如果不用这个选项,这两个数据库将保持它们现有的数据库级属性以及任何已有的内容。
一旦恢复,建议在每个数据库上运行ANALYZE
,这样优化器就可以得到有用的统计信息。你也可以运行vacuumdb -a -z
来分析所有数据库。
不应该预期转储脚本运行到结束都不出错。特别是由于脚本将为源集簇中已有的每一个角色发出CREATE ROLE
语句,对于bootstrap超级用户当然会得到一个“role already exists”错误,除非目标集簇用一个不同的bootstrap超级用户名完成的初始化。这种错误是无害的并且应该被忽略。--clean
选项的使用很可能会产生额外的有关于不存在对象的无害错误消息,不过可以通过加上--if-exists
减少这类错误消息。
pg_dumpall要求所有需要的表空间目录在进行恢复之前就必须存在;否则,数据库创建就会由于在非默认位置创建数据库而失败。
要转储所有数据库:
$
pg_dumpall > db.out
要从此文件还原数据库,您可以使用:
$
psql -f db.out postgres
在这里连接到哪个数据库并不重要,因为由pg_dumpall创建的脚本文件将包含创建和连接到保存的数据库的适当命令。
一个例外是,如果您指定了--clean
,则必须最初连接到postgres
数据库;
脚本将立即尝试删除其他数据库,这将导致您连接的数据库删除失败。
可能的错误情况请查看pg_dump。