PostgreSQL pg_dumpall
pg_dumpall — 将一个PostgreSQL数据库集簇抽取到一个脚本文件中
大纲
pg_dumpall
[connection-option
...] [option
...]
描述
pg_dumpall工具可以一个集簇中所有的PostgreSQL数据库写出到(“转储”)一个脚本文件。该脚本文件包含可以用作psql的输入 SQL命令来恢复数据库。它会对集簇中的每个数据库调用pg_dump来完成该工作。pg_dumpall还转储对所有数据库公用的全局对象( pg_dump 不保存这些对象),也就是说数据库角色和表空间都会被转储。 目前这包括适数据库用户和组、表空间以及适合所有数据库的访问权限等属性。
因为pg_dumpall从所有数据库中读取表,所以你很可能需要以一个数据库超级用户的身份连接以便生成完整的转储。同样,你也需要超级用户特权执行保存下来的脚本,这样才能增加角色和组以及创建数据库。
SQL 脚本将被写出到标准输出。使用 -f
/--file
选项或者 shell 操作符可以把它重定向到一个文件。
pg_dumpall需要多次连接到PostgreSQL服务器(每个数据库一次)。如果你使用口令认证,可能每次都会要求口令。这种情况下使用一个~/.pgpass
会比较方便。详见第 33.15 节。
选项
下列命令行选项用于控制输出的内容和格式。
-a
--data-only
-
只转储数据,不转储模式(数据定义)。
-c
--clean
-
包括在重建数据库之前清除(移除)它们的 SQL 命令。角色和表空间的
DROP
命令也会被加入进来。 -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
命令使用的相同规则 (请参见下面的 Patterns),因此,通过在模式中编写通配符也可以排除多个数据库。 使用通配符时,请谨慎的引用模式,如果需要防止shell通配符扩展。 --extra-float-digits=
ndigits
-
在转储浮点数据时使用extra_float_digits规定的值,而不是最大可用精度。备份目的进行的常规转储不使用此选项。
--if-exists
-
时间条件性命令(即增加一个
IF EXISTS
子句)来清除数据库和其他对象。 只有同时指定了--clean
时,这个选项才可用。 --inserts
-
将数据转储为
INSERT
命令(而不是COPY
)。这将使得恢复非常慢,这主要用于使转储能够被载入到非PostgreSQL数据库中。注意如果你已经重新安排了列序,该恢复可能会一起失败。--column-inserts
选项对于列序改变是安全的,但是会更慢。 --load-via-partition-root
-
在为一个分区表转储数据时,让
COPY
语句或者INSERT
语句把包含它的分区层次的根而不是分区自身作为目标。这导致在数据被装载时,会为每一个行重新确定合适的分区。如果在一台服务器上重新装载数据时会出现行并不是总是落入到和原始服务器上相同的分区中的情况,这个选项就很有用。例如,如果分区列是文本类型并且两个系统中用于排序分区列的排序规则有着不同的定义,就会发生这种情况。 --lock-wait-timeout=
timeout
-
在转储的开始从不等待共享表锁的获得。而是在指定的
timeout
内不能锁定一个表时失败。超时时长可以用SET statement_timeout
接受的任何格式指定(允许的值根据你从其转出的服务器版本变化,但是从 7.3 以来的所有版本都接受一个整数表示的毫秒数。如果从 7.3 以前的服务器转出,这个选项会被忽略。)。 --no-comments
-
不转储注释。
--no-publications
-
不转储publication。
--no-role-passwords
-
不为角色转储口令。在恢复完后,角色的口令将是空口令,并且在设置口令之前口令认证都不会成功。由于指定这个选项时并不需要口令值,角色信息将从目录视图
pg_roles
而不是pg_authid
中读出。因此,如果对pg_authid
的访问被某条安全性策略所限制,那么这个选项也会有所帮助。 --no-security-labels
-
不转储安全标签。
--no-subscriptions
-
不转储subscription。
--no-sync
-
默认情况下,
pg_dumpall
将等待所有文件被安全地写入到磁盘。这个选项会让pg_dumpall
不做这种等待而返回,这样会更快,但是意味着后续的操作系统崩溃可能留下被损坏的转储。通常来说,这个选项对测试有用,但不应该在从生产安装中转储数据时使用。 --no-tablespaces
-
不要输出选择表空间的命令。通过这个选项,在恢复期间所有的对象都会被创建在任何作为默认的表空间中。
--no-unlogged-table-data
-
不转储非日志记录表的内容。这个选项对于表定义(模式)是否被转储没有影响,它只会限制转储表数据。
--on-conflict-do-nothing
-
添加
ON CONFLICT DO NOTHING
到INSERT
命令。 除非--inserts
或--column-inserts
也被规定,否则此选项不生效。 --quote-all-identifiers
-
强制引用所有标识符。在从一个与pg_dumpall主版本不同的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(见第 33.14 节)支持的环境变量。
注解
因为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。