kingbase sys_restore命令详解

sys_restore — 从一个由 sys_dump 创建的归档文件恢复 KingbaseES 数据库。

sys_restore 用来从 sys_dump 创建的非文本格式归档恢复 KingbaseES 数据库的工具。它将发出必要的命令把该数据库重建成它被保存时的状态。这些归档文件还允许 sys_restore 选择恢复哪些内容或者在恢复前对恢复项重排序。这些归档文件被设计为可以在不同的架构之间迁移。

sys_restore 可以在两种模式下操作。如果指定了数据库名称，sys_restore 会连接那个数据库并且把归档内容直接恢复到该数据库中。否则，会创建一个脚本，其中包含着重建该数据库所必要的 SQL 命令，它会被写入到一个文件或者标准输出。这个脚本输出等效于 sys_dump 的纯文本输出格式。因此，一些控制输出的选项与 sys_dump 的选项类似。

sys_restore无法恢复不在归档文件中的信息。例如，如果归档使用“以INSERT命令转储数据”选项创建，sys_restore 将无法使用COPY语句装载数据。

命令行参数

sys_restore [ connection-option ...] [ option ...] [ filename ]

参数说明

sys_restore 接受下列命令行参数。

filename

指定要恢复的归档文件（对于一个目录格式的归档则是目录）的位置。如果没有指定，则使用标准输入。

-a --data-only

只恢复数据，不恢复模式（数据定义）。如果在归档中存在，将恢复表数据、大对象和序列值。

这个选项类似于指定--section=data，但是由于历史原因两者不完全相同。

-c --clean

在重新创建数据库对象之前清除（丢弃）它们（除非使用了--if-exists，否则如果有对象在目标数据库中不存在，这可能会生成一些无害的错误消息）。

-C --create

在恢复一个数据库之前先创建它。如果还指定了--clean，在连接到目标数据库之前丢弃并且重建它。

如果使用--create，sys_restore 还会恢复数据库的注释（如果有）以及与其相关的配置变量设置，也就是任何提到过这个数据库的ALTER DATABASE … SET …和ALTER ROLE … IN DATABASE … SET …命令。不管是否指定--no-acl，都会恢复数据库本身的访问权限。

在使用这个选项时，-d提到的数据库只用于发出初始的DROP DATABASE和CREATE DATABASE命令。所有要恢复到该数据库名中的数据都出现在归档中。

-d dbname --dbname=dbname

连接到数据库dbname并且直接恢复到该数据库中。

-e --exit-on-error

在发送 SQL 命令到该数据库期间如果碰到一个错误就退出。默认行为是继续并且在恢复结束时显示一个错误计数。

-E --skip-errors

使用复制时跳过错误行。

-f filename --file=filename

为生成的脚本或列表（当使用-l时）指定输出文件。 为 stdout 则使用中划线-。

-F format --format=format

指定归档的格式。并不一定要指定该格式，因为 sys_restore 将会自动决定格式。如果指定，可以是下列之一：

• c custom

  归档采用 sys_dump 的自定义格式。

• d directory

  归档是一个目录归档。

• t tar

  归档是一个tar归档。

--feedback=NUM

该参数用来指明在 sys_restore 导入表数据的过程中每间隔多少行打印一次进度信息，默认为零只打印导入表的总行数，和 -v 参数共用时才会打印。

-I index --index=index

只恢复命名索引的定义。可以通过写多个-I开关指定多个索引。

-j number-of-jobs --jobs=number-of-jobs

使用并发任务运行 sys_restore 中最耗时的部分 — 载入数据、创建索引或者创建约束。对于一个运行在多处理器机器上的服务器，这个选项能够大幅度减少恢复一个大型数据库的时间。

每一个任务是一个进程或者一个线程，这取决于操作系统，它们都使用一个独立的服务器连接。

这个选项的最佳值取决于服务器、客户端以及网络的硬件设置。因素包括 CPU 的内核数量和磁盘设置。一个好的建议是将该值设置为服务器上 CPU 的内核数量，但是在很多情况下，更大的值也能导致更快的恢复时间。当然，过高的值会由于超负荷反而导致性能降低。

这个选项只支持自定义和目录归档格式。输入必须是一个常规文件或目录（例如，不能是一个管道）。当发出一个脚本而不是直接连接到数据库服务器时会忽略这个选项。还有，多任务不能和选项--single-transaction一起用。

-K --key=encryptkey

还原数据时候指定加密秘钥。1.密钥长度不能超过16字节。2.只能用于二进制格式输出。

-l --list

列出归档的内容的表格。这个操作的输出能被用作-L选项的输入。注意如果把-n或-t这样的过滤开关与-l一起使用，它们将会限制列出的项。

-L list-file --use-list=list-file

只恢复在list-file中列出的归档元素，并且按照它们出现在该文件中的顺序进行恢复。注意如果把-n或-t这样的过滤开关与-L一起使用，它们将会进一步限制要恢复的项。

list-file通常是通过编辑一个-l操作的输出来创建。行可以被移动或者移除，并且也可以通过在行首放一个（;）将其注释掉。

-n shcema --schema=schema

只恢复在命名模式中的对象。可以用多个-n开关来指定多个模式。这可以与-t选项组合在一起只恢复一个指定的表。

-N schema --exclude-schema=schema

不恢复指定模式中的对象。可以用多个-N开关指定多个要被排除的模式。

如果-n和-N同时指定了相同的模式，则-N会胜出并且该模式会被排除。

--view-only

只恢复视图。

--recreate-view

最后重新创建视图。

-g namespace --fromSchema=schema

源模式（默认大小写不敏感），恢复源模式中的对象到-G指定的目标模式中去，与-G一起使用。可以用多个-g开关来指定多个源模式。这可以与-t选项组合在一起只恢复一个指定的表。

--from-schema-case-sensitive
设置源模式大小写敏感。

-G namespace --targetSchema=schema

目标模式，恢复-g指定的源模式中的对象到目标模式中，与-g一起使用。可以用多个-G开关来指定多个目标模式。

-O --no-owner

不要输出将对象的所有权设置为与原始数据库匹配的命令。默认情况下，sys_restore 会发出ALTER OWNER或者SET SESSION AUTHORIZATION语句来设置已创建的模式对象的所有权。除非到该数据库的初始连接是一个超级用户（或者拥有脚本中所有对象的同一个用户）建立的，否则这些语句将会失败。通过-O，任何用户名都可以用于初始连接，并且这个用户将会拥有所有创建的对象。

-P function-name(argtype [, ...]) --function=function-name(argtype [, ...])

只恢复命名函数。要注意拼写函数的名称和参数，使它们正好就是出现在转储文件的内容表中的名称和参数。可以使用多个-P开关指定多个函数。

--progress

设置该选项，将会显示 sys_restore 的导入总进度，默认不显示。

-R --no-reconnect

这个选项已废弃，但是出于向后兼容的目的，系统仍然保留。

-s --schema-only

只恢复归档中的模式（数据定义）不恢复数据。

这个选项与--data-only相反。它与指定--section=pre-data --section=post-data相似，但是由于历史原因并不完全相同。

（不要把这个选项和--schema选项弄混，后者把词“schema”用于一种不同的含义）。

-S username --superuser=username

指定在禁用触发器时要用的超级用户名。只有使用--disable-triggers时这个选项才相关。

-t table --table=table

只恢复命名表的定义和数据。table可以是视图、物化视图、序列或外部表。可以写上多个-t开关可以选择多个表。这个选项可以和-n选项结合在一起指定一个特定模式中的表。

-T trigger --trigger=trigger

只恢复命名触发器。可以用多个-T开关指定多个触发器。

-v --verbose

指定冗长模式。

-V --version

打印该 sys_restore 的版本并退出。

-x --no-privileges --no-acl

防止恢复访问权限（授予/收回命令）。

-1 --single-transaction

将恢复作为单一事务执行（即把发出的命令包裹在BEGIN/COMMIT中）。这可以确保要么所有命令完全成功，要么没有任何改变。这个选项隐含了--exit-on-error。

--disable-triggers

只有在执行只恢复数据的恢复时，这个选项才相关。它指示 sys_restore 在装载数据时，执行命令临时禁用目标表上的触发器。如果您在表上有参照完整性检查或者其他触发器，并且您不希望在数据载入期间调用它们时，请使用这个选项。

目前，为--disable-triggers发出的命令必须以超级用户身份完成。因此您还应该用-S指定一个超级用户名，或者更好的方法是以一个 KingbaseES 超级用户的身份运行 sys_restore。

--enable-row-security

只有在恢复具有行安全性的表的内容时，这个选项才相关。默认情况下，sys_restore 将把 row_security 设置为 off 来确保将所有数据恢复到表中。如果用户没有足够绕过行安全性的权限，那么会抛出一个错误。这个参数指示 sys_restore 把 row_security 设置为 on 允许用户尝试恢复启用了行安全性的表的内容。如果用户没有从转储向表中插入行的权限，这仍将失败。

注意当前这个选项还要求转储处于INSERT格式，因为COPY FROM不支持行安全性。

--if-exists

使用条件命令（即增加一个IF EXISTS子句）删除数据库对象。只有指定了--clean时，这个选项才有效。

--no-comments

即便归档中包含注释也不输出恢复注释的命令。

--no-data-for-failed-tables

默认情况下，即便表的创建命令失败（例如因为表已经存在），也会恢复表数据。通过这个选项，将跳过此类表的数据。如果目标数据库已经包含了想要的表内容，则此行为很有用。例如，KingbaseES 扩展（如 KGIS ）的辅助表可能已经被载入到目标数据库中，指定这个选项就能阻止把重复的或者废弃的数据载入到这些表中。

只有当直接恢复到一个数据库中时，这个选项才有效，在产生 SQL 脚本输出时这个选项不会产生效果。

--no-publications

即便归档中包含 publication 也不输出恢复 publication 的命令。

--no-security-labels

不输出恢复安全标签的命令，即使归档中包含安全标签。

--no-subscriptions

即便归档中包含 subscription 也不输出恢复 subscription 的命令。

--no-tablespaces

不输出命令选择表空间。通过这个选项，所有的对象都将创建在恢复时的默认表空间中。

--section=sectionname

只恢复命名的段。段的名称可以是pre-data、data或者post-data。可以多次指定这个选项来选择多个段。默认值是恢复所有段。

数据段包含实际的表数据以及大对象定义。post-data项由索引定义、触发器、规则和除已验证的检查约束之外的约束构成。pre-data项由所有其他数据定义项构成。

--strict-names

要求每一个模式（-n/--schema）以及表（-t/--table）限定词匹配备份文件中至少一个模式/表。

--use-set-session-authorization

输出 SQL 标准的SET SESSION AUTHORIZATION命令取代ALTER OWNER命令来决定对象拥有权。这会让转储更加兼容标准，但是根据该转储中对象的历史记录，可能无法正确恢复。

-? --help

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

sys_restore 也接受下列用于连接参数的命令行参数：

-h host --host=host

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

-p port --port=port

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

-U username --username=username

要作为哪个用户连接。

-w --no-password

不发出密码提示。如果服务器要求密码验证，并且密码不能其他方式获得（例如一个.kbpass文件），那么连接尝试将失败。这个选项对于在没有用户输入密码的批处理任务和脚本中有用。

-W --password

强制 sys_restore 在连接到一个数据库之前提示输入密码。

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

--role=rolename

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

-M --enable_ce

sys_restore恢复密态对象。

环境变量

KINGBASE_HOST

指定要连接的主机名。

KINGBASE_PORT

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

KINGBASE_USER

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

PGOPTIONS

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

SYS_COLOR

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

和大部分其他 KingbaseES 工具相似，这个工具也使用 libkci 支持的环境变量。