金仓数据库KingbaseES客户端应用参考手册--12. sys_dumpall

目录

12.1. 简介 ¶

12.2. 命令行参数 ¶

12.3. 参数说明 ¶

12.4. 环境变量 ¶

12.5. 错误信息诊断 ¶

12.6. 示例 ¶

12.7. 备注 ¶

12.8. 参考 ¶

12.1. 简介 ¶

sys_dumpall — 将一个KingbaseES数据库集群抽取到一个脚本文件中

sys_dumpall工具可以将一个集群中所有的KingbaseES数据库写出到（“转储”）一个脚本文件。该脚本文件包含可以用作 ksql 的输入SQL命令来恢复数据库。

它会对集群中的每个数据库调用 sys_dump 来完成该工作。sys_dumpall还转储对所有数据库公用的全局对象（ sys_dump 不保存这些对象），包括数据库用户和组、表空间以及适合所有数据库的访问权限等属性。

因为sys_dumpall从所有数据库中读取表，所以需要以数据库超级用户的身份连接以便生成完整的转储。同样，也需要超级用户特权执行保存下来的脚本，这样才能增加角色和组以及创建数据库。

SQL 脚本将被写出到标准输出。使用 -f / --file 选项或者 shell 操作符可以把它重定向到一个文件。

sys_dumpall需要多次连接到KingbaseES服务器（每个数据库一次）。如果你使用口令认证，可能每次都会要求口令，这种情况下使用一个 ~/.kbpass 或 ~/.encpwd 文件会比较方便。

12.2. 命令行参数 ¶

sys_dumpall [ connection-option ...] [ option ...]

12.3. 参数说明 ¶

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

-a --data-only

只转储数据，不转储模式（数据定义）。

-c --clean

包含在重建数据库之前清除（移除）它们的 SQL 命令。角色和表空间的 DROP 命令也会被加入进来。

-E encoding --encoding=encoding

用指定的字符集编码创建转储。默认情况下，转储使用数据库的编码创建（另一种得到相同结果的方法是设置 KCICLIENTENCODING 环境变量为想要的转储编码）。

-f filename --file=filename

将输出指定到文件中。如果省略，将使用标准输出。

-g --globals-only

只转储全局对象（角色和表空间），而不转储数据库。

-O --no-owner

不输出用于设置符合原始数据库对象所有权的命令。默认情况下，sys_dumpall通过 ALTER OWNER 或 SET SESSION AUTHORIZATION 语句来设置被创建的模式元素的所有权，除非脚本是由一个超级用户（或者是拥有脚本中所有对象的同一个用户）运行，否则这些语句在脚本运行时会失败。要使得一个脚本能被任意用户恢复，但又不想给予该用户所有对象的所有权，可以指定 -O 。

-r --roles-only

只转储角色，不转储数据库和表空间。

-s --schema-only

只转储对象定义（模式），不转储数据。

-S username --superuser=username

指定要在禁用触发器时使用的超级用户。只有使用 --disable-triggers 时，这个选项才有效（通常，最好省去这个选项，而作为超级用户来启动结果脚本来取而代之）。

-t --tablespaces-only

只转储表空间，不转储数据库和角色。

-v --verbose

指定细节模式。这将导致sys_dumpall向标准错误输出详细的对象注释以及转储文件的开始/停止时间、进度消息，同时也会启用sys_dump中的细节输出。

-V --version

打印sys_dumpall版本并退出。

-x --no-privileges

--no-acl

防止转储访问特权（授予/收回命令）。

--binary-upgrade

这个选项用于本地升级功能，只能由升级工具使用,不能把它用于其他目的。这个选项在未来的发行中可能被改变而不做通知。

--column-inserts --attribute-inserts

将数据转储为带有显式列名的 INSERT 命令（ INSERT INTO table ( column , ...) VALUES ...）。这将使得恢复过程非常慢，这主要用于使转储能够被载入到非KingbaseES数据库中。

--disable-dollar-quoting

这个选项禁止在函数体中使用美元符号引用，并且强制它们使用 SQL 标准字符串语法被引用。

--disable-triggers

只有在创建一个仅转储数据的转储时，这个选项才相关。它指示sys_dumpall在转储文件中包含数据被重新载入时能够临时禁用目标表上的触发器的命令。如果表上有引用完整性检查或其他触发器，并且在数据重新载入期间不想调用它们，请使用这个选项。

当前，为 --disable-triggers 发出的命令必须作为超级用户来执行。因此，你还应当使用 -S 指定一个超级用户名，或者使用一个超级用户启动结果脚本。

--extra-float-digits=ndigits

在转储浮点数据时使用extra_float_digits的指定值控制浮点数据精度，而不是使用最大可用精度。用于备份目的的常规转储不应使用此选项。

--exclude-database=pattern

不要转储名称与 pattern 匹配的数据库。通过编写多个 --exclude-database 开关，可以排除多个数据库。 pattern 参数的解析处理方式与ksql的 \d 命令 pattern 参数的解析方式相同（见 ksql 模式），多个数据库也可以通过编写通配符的模式排除。在使用通配符时，如果需要防止shell通配符展开，请小心引用模式。

--if-exists

时间条件性命令（即增加一个 IF EXISTS 子句）来清除数据库和其他对象。 只有同时指定了 --clean 时，这个选项才可用。

--inserts

将数据转储为 INSERT 命令（而不是 COPY ）。这将使得恢复非常慢，主要用于使转储能够被载入到非KingbaseES数据库中。注意如果列序被改变，该恢复可能会一起失败。 --column-inserts 选项对于列序改变是安全的，但是会更慢。

--load-via-partition-root

在为一个分区表转储数据时，让 COPY 语句或者 INSERT 语句把包含它的分区层次的根作为目标，而不是以分区自身为目标。这导致在数据被装载时，会为每一个行重新确定合适的分区。如果在一台服务器上重新装载数据时出现行并不是总是落入到和原始服务器上相同的分区中的情况，这个选项就很有用。例如，如果分区列是文本类型并且两个系统中用于排序分区列的排序规则有着不同的定义，就会发生这种情况。

--lock-wait-timeout=timeout

在转储开始时指定 timeout 时间内不能锁定一个表时失败。超时时长可以用 SET statement_timeout 接受的格式声明（允许的值根据你从其转出的服务器版本变化，所有版本都接受以为单位毫秒的整数值）。

--no-comments

不转储注释。

--no-publications

不转储publication。

--no-role-passwords

不为角色转储口令。在恢复完后，角色的口令将是空口令，并且在设置口令之前口令认证都不会成功。由于指定这个选项时并不需要口令值，角色信息将从目录视图 sys_roles 而不是 sys_authid 中读出。因此，如果对 sys_authid 的访问被某条安全性策略所限制，那么这个选项也会有所帮助。

--no-security-labels

不转储安全标签。

--no-subscriptions

不转储subscription。

--no-sync

默认情况下， sys_dumpall 将等待所有文件被安全地写入到磁盘后返回。这个选项会让 sys_dumpall 不做这种等待而返回，这样会更快，但是意味着后续的操作系统崩溃可能留下被损坏的转储。通常来说，这个选项对测试有用，但不应该在生产安装环境中转储数据时使用。

--no-tablespaces

不输出选择表空间的命令。通过这个选项，在恢复期间所有的对象都会被创建在任何作为默认的表空间中。

--no-unlogged-table-data

不转储非日志记录表的内容。这个选项对于表定义（模式）是否被转储没有影响，它只会限制转储表数据。

--on-conflict-do-nothing

在 INSERT 命令上添加 ON CONFLICT DO NOTHING 。当使用 --inserts 或 --column-inserts 时此选项有效。

--quote-all-identifiers

强制引用所有标识符。在从一个与sys_dumpall主版本不同的KingbaseES服务器转储数据库时或者要将输出载入到一个不同主版本的服务器时，推荐使用这个选项。默认情况下，sys_dumpall只会对为其主版本中保留词的标识符加上引号。在与其他版本的具有不同保留词集合的服务器交互时，这有时会导致兼容性问题。使用 --quote-all-identifiers 可以阻止这类问题，但是代价是转储脚本会更加难读。

--rows-per-insert=nrows

使用 INSERT 命令转储数据(而非 COPY )。 控制 INSERT 命令每行的最大行数。指定的值必须是一个大于零的数字。在重新加载期间发生的任何错误只会导致有问题的 INSERT 行丢失，而不是整个表的内容。

--use-set-session-authorization

输出SQL标准的 SET SESSION AUTHORIZATION 命令取代 ALTER OWNER 命令来确定对象的所有关系。这让该转储更加兼容标准，但是取决于该转储中对象的历史，该转储可能无法正常恢复。

-? --help

显示有关sys_dumpall命令行参数的帮助并退出。

下列命令行选项控制数据库连接参数。

-d connstr --dbname=connstr

以一个连接字符串的形式，指定用来连接到服务器的参数。

这个选项被称为 --dbname 是为了和其他客户端应用一致，但是因为sys_dumpall需要连接多个数据库，连接字符串中的数据库名将被忽略。使用 -l 选项指定一个数据库，该数据库被用于初始连接，这将转储全局对象并且发现需要转储哪些其他数据库。

-h host --host=host

指定服务器正在运行的机器的主机名。如果该值开始于一个斜线，它被用作一个 Unix 域套接字的目录。默认是从 KINGBASE_HOST 环境变量中取得（如果被设置），否则将尝试一次 Unix 域套接字连接。

-l dbname --database=dbname

指定要连接到哪个数据库转储全局对象以及发现要转储哪些其他数据库。如果没有指定，将会使用 kingbase 数据库，如果 kingbase 不存在，就使用 template1 。

-p port --port=port

指定服务器正在监听连接的 TCP 端口或本地 Unix 域套接字文件扩展名。默认是放在 KINGBASE_PORT 环境变量中（如果被设置），否则使用编译在程序中的默认值。

-U username --username=username

指定连接数据库的用户。

-w --no-password

不发出口令提示。如果服务器要求口令认证并且没有其他方式提供口令（例如一个 ~/.kbpass 或 ~/.encpwd 文件），那儿连接尝试将失败。这个选项对于批处理任务和脚本有用，因为在其中没有用户来输入口令。

-W --password

强制sys_dumpall在连接到一个数据库之前提示要求一个口令。

这个选项不是必须的，因为如果服务器要求口令认证，sys_dumpall将自动提示要求一个口令。但是，sys_dumpall将浪费一次连接尝试来发现服务器想要一个口令。在某些情况下，值得键入 -W 来避免额外的连接尝试。

注意对每个要被转储的数据库，口令提示都会再次出现。通常，最好设置一个 ~/.kbpass 或 ~/.encpwd 文件来减少口令手工输入。

--role=rolename

指定一个用来创建该转储的角色名。这个选项导致sys_dump在连接到数据库后发出一个 SET ROLE rolename 命令。当已认证用户（由 -U 指定）缺少sys_dump所需的特权但是能够切换到一个具有所需权利的角色时，这个选项很有用。一些安装有针对直接作为超级用户登录的策略，使用这个选项可以让转储在不违反该策略的前提下完成。

12.4. 环境变量 ¶

KINGBASE_HOST

指定要连接的主机名。

KINGBASE_PORT

指定要连接的服务器的端口号。

KINGBASE_USER

指定要使用哪个用户连接数据库。

PGOPTIONS

指定要使用那些参数连接到数据库。

SYS_COLOR

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

和大部分其他KingbaseES工具相似，这个工具也使用libkci。

12.5. 错误信息诊断 ¶

无

12.6. 示例 ¶

要转储所有数据库：

$ sys_dumpall > db.out

仅转储全局对象，不转储数据库：

$ sys_dumpall -g >db.out

仅转储角色，不转储表空间：

$ sys_dumpall -r >db.out

要从这个文件重新载入数据库，你可以使用：

$ ksql -f db.out kingbase

这里你连接哪一个数据库并不重要，因为由sys_dumpall创建的脚本将包含合适的命令来创建和连接到被保存的数据库。一个例外是，如果指定了 --clean ，则开始时必须连接到 kingbase 数据库，该脚本将立即尝试删除其他数据库，并且这种动作对于已连接上的这个数据库将会失败。

12.7. 备注 ¶

因为sys_dumpall在内部调用sys_dump，所以， 一些诊断消息可以参考sys_dump。

即使当用户的目的是把转储脚本恢复到一个空的集群中， --clean 选项也有用武之地。 --clean 的使用让该脚本删除并且重建内建的 kingbase 和 template1 数据库，确保这两个数据库保持与源集群中相同的属性（例如locale和编码）。如果不用这个选项，这两个数据库将保持它们现有的数据库级属性以及任何已有的内容。

一旦恢复，建议在每个数据库上运行 ANALYZE ，这样优化器就可以得到有用的统计信息。你也可以运行 vacuumdb -a -z 来分析所有数据库。

不应该预期转储脚本运行到结束都不出错。特别是由于脚本将为源集群中已有的每一个角色发出 CREATE ROLE 语句，对于初始的超级用户当然会得到一个“role already exists”错误，除非目标集群用一个不同的初始超级用户名完成的初始化。这种错误是无害的并且应该被忽略。 --clean 选项的使用很可能会产生额外的有关于不存在对象的无害错误消息，不过可以通过加上 --if-exists 减少这类错误消息。

sys_dumpall要求所有需要的表空间目录在进行恢复之前就必须存在；否则，数据库创建就会由于在非默认位置创建数据库而失败。

12.8. 参考 ¶

可能的错误情况请查看 sys_dump 。