OB-租户(Tenant)管理

概述

租户的概念类似于传统数据库的数据库实例。租户下可以建立数据库，在租户的数据库下可以建立表。

支持租户级别的转储、租户级别的分区主切换和租户级别的扩容缩容

支持两种类型租户

MySQL 租户
Oracle 租户

OceanBase 集群初始内置了一个系统租户 sys，可以用来管理 OceanBase 集群。

新建租户

只有用 root 用户连接到 sys 租户（root@sys）才能执行 CREATE TENANT 命令去创建租户。创建新租户后，可以指定创建租户的类型和白名单。

语法

CREATE TENANT [IF NOT EXISTS] tenantname 
     [tenant_characteristic_list] [opt_set_sys_var]

tenant_characteristic_list: 
tenant_characteristic [, tenant_characteristic...]

tenant_characteristic: 
COMMENT 'string'  
|{CHARACTER SET | CHARSET} [=] charsetname 
|COLLATE [=]  collationname
|REPLICA_NUM [=] num 
|ZONE_LIST [=] (zone [, zone…]) 
|PRIMARY_ZONE [=] zone  
|DEFAULT TABLEGROUP [=] {NULL | tablegroup}
|RESOURCE_POOL_LIST [=](poolname [, poolname…])
|LOGONLY_REPLICA_NUM [=] num
|LOCALITY [=] 'locality description'

opt_set_sys_var:
{ SET | SET VARIABLES | VARIABLES } system_var_name = expr [,system_var_name = expr] ...

说明

如果要创建的租户名已存在，并且没有指定 IF NOT EXISTS，则会出现错误。
租户名的合法性和变量名一致，最长 30 个字符，字符只能是大小写英文字母、数字和下划线，而且必须以字母或下划线开头，并且不能是 OceanBase 数据库的关键字。
在租户下可以指定资源池。
RESOURCE_POOL_LIST 为创建租户时的必填项。
CREATE TENANT 命令中的 RESOURCE_POOL_LIST 中，暂时仅支持一个资源池。

示例

配置说明

primary_zone 指该租户的表的分区 Leader 所在的 Zone ，例如，primary_zone ='zone1; zone2, zone3' 表示该租户的表的分区 Leader 在 zone1 上，这时通过分号来分隔。
zone2 和 zone3 通过逗号分割，表示 zone2 和 zone3 是同一优先级，但是比 zone1 优先级低。
primary_zone 设置时，其值可以为 RANDOM（必须大写），表示随机选择最高优先级内的任一一个 Zone 作为 Primary Zone。

创建mysql租户

创建名为 test_tenant 的一个 3 副本的 MySQL 租户（创建新租户默认是 MySQL 租户）

CREATE TENANT IF NOT EXISTS test_tenant charset='utf8mb4', replica_num=3, zone_list=('zone1','zone2','zone3'), primary_zone='zone1;zone2,zone3', resource_pool_list=('pool1');

-- 设置远程访问客户端
ALTER TENANT test_tenant SET VARIABLES ob_tcp_invited_nodes='%';

创建oracle租户

创建名为 test_tenant 的一个 3 副本 Oracle 租户。通过参数 ob_compatibility_mode 设置租户模式，并且必须使用 OBClient 或 ODC 连接 Oracle 租户进行创建。

CREATE TENANT IF NOT EXISTS test_tenant charset='utf8mb4', replica_num=3, zone_list=('zone1','zone2','zone3'), primary_zone='zone1;zone2,zone3', resource_pool_list=('pool1') SET ob_compatibility_mode='oracle';

创建可从远程客户端IP地址访问OceanBase数据库的租户

创建租户后，直接通过修改变量 ob_tcp_invited_nodes 的值为 % 以便允许任何客户端 IP 连接该租户。如果不调整 ob_tcp_invited_nodes 的值，则默认租户的连接方式为只允许本机的 IP 连接数据库。

CREATE TENANT IF NOT EXISTS test_tenant charset='utf8mb4', replica_num=3, zone_list=('zone1','zone2','zone3'), primary_zone='zone1;zone2,zone3', resource_pool_list=('pool1') SET ob_tcp_invited_nodes='%';

注意事项

普通租户的内存最小规格必须大于等于 5 GB，否则创建租户失败。如果希望建立租户进行非常简单的功能测试，可以修改参数 alter system __min_full_resource_pool_memory 的值为 1073741824 来允许以最小 1 GB 内存的规格创建租户。

alter system __min_full_resource_pool_memory=1073741824;

查看租户信息

在 OBClient 中使用 sys 租户登录集群

查看当前集群的租户信息

SELECT * FROM oceanbase.gv$tenant;

查看当前租户

SHOW TENANT;

查看租户白名单

系统变量 ob_tcp_invited_nodes 用于设置租户的 IP 白名单，是租户全局的白名单限制参数。默认值为 127.0.0.1,::1，表示仅允许本机的 IP 连接该租户。

查看该变量确认白名单设置

SHOW VARIABLES LIKE 'ob_tcp_invited_nodes';

值为 %，表示允许任何客户端 IP 连接该租户

系统变量配置规则

ob_tcp_invited_nodes 用于设置租户的 IP 白名单，支持百分号（%）、短横线（_）和 IP（多个 IP 之间用逗号分隔），支持 IP 列表匹配、掩码匹配和模糊匹配。

租户会话管理

查看租户会话

-- 查看租户当前会话
SHOW PROCESSLIST;

终止租户会话

KILL session_id;
-- 或者
KILL CONNECTION session_id;

修改租户

可以通过 SQL 语句修改租户的信息，包括修改租户名、副本数、Zone 列表、主 Zone 以及系统变量值等。

语法

ALTER TENANT {tenant_name | ALL}
    [SET] [tenant_option_list] [opt_global_sys_vars_set]

tenant_option_list:
    tenant_option [, tenant_option ...]

tenant_option:
            COMMENT [=]'string' 
            |{CHARACTER SET | CHARSET} [=] charsetname 
            |COLLATE [=]  collationname 
            |REPLICA_NUM [=] num 
            |ZONE_LIST [=] (zone [, zone…]) 
            |PRIMARY_ZONE [=] zone 
            |RESOURCE_POOL_LIST [=](poolname [, poolname…]) 
            |DEFAULT TABLEGROUP [=] {NULL | tablegroupname}
            |{READ ONLY | READ WRITE}
      |LOGONLY_REPLICA_NUM [=] num
      |LOCALITY [=] 'locality description'
      |LOCK|UNLOCK;
      
opt_global_sys_vars_set:
      VARIABLES system_var_name = expr [,system_var_name = expr] ...

锁定租户

租户被锁定后，不能在该租户上创建新的连接，已有的链接保持不变。

语法

ALTER TENANT tenant_name LOCK;

删除租户

删除租户后，租户下的数据库和表也同时被删除。但是租户使用的资源配置不会被删除。资源配置可以继续给其他租户使用。

对于主备库配置场景，仅支持在主集群上删除租户，不支持在备集群上执行租户删除操作。

语法

DROP TENANT tenant_name [FORCE]
-- 或者
DROP TENANT tenant_name PURGE;

说明

对于 DROP TENANT 操作：
- 当租户开启回收站功能时，DROP TENANT 操作表示删除的租户会进入回收站。租户实际占用的空间并没有释放，只是不能再向该租户建立新的连接。对于回收站中的租户，后续您可以通过租户级回收站功能进一步删除或恢复该租户
  - 执行 FLASHBACK 时，可以使用租户原始的名称，也可以使用回收站中的名称，回收站中的名称全局唯一，因此使用回收站中的名称，可以明确恢复的是哪个租户。当多个租户存在相同的原始名称时，此时恢复的租户是这些租户中最后进入回收站中的租户。
```
-- 查看回收站中租户信息
SHOW RECYCLEBIN;

--将系统租户回收站中的 tenant_name 闪回为正常租户
FLASHBACK TENANT <tenant_name> TO BEFORE DROP;
```
  - 执行 PURGE TENANT 时，同样可以使用原始名称和回收站中的名称。与 FLASHBACK 不同，PURGE TENANT 时，如果多个原始名称相同，则删除的是最早进入回收站中的租户。
```
-- 将租户 tenant_name 从回收站中彻底清除
PURGE TENANT tenant_name;

-- 将回收站中的全部对象全部彻底清除
PURGE RECYCLEBIN;
```
- 当租户关闭回收站功能时，DROP TENANT 操作表示延迟删除租户，后台线程会进行 GC（Garbage Collection）动作，租户的信息仍然可以通过内部表查询。租户具体延迟删除的时间由配置项 schema_history_expire_time 控制，默认为 7 天
DROP TENANT PURGE 操作表示仅延迟删除租户，且无论回收站功能是否开启，删除的租户均不进入回收站。
FORCE 参数表示无论回收站功能是否开启，均可以立刻删除租户。

示例

延迟删除租户 `t1`，删除的租户可进入回收站

 DROP TENANT t1;

延迟删除租户 `t1`，删除的租户不进入回收站

DROP TENANT t1 PURGE;

立刻删除租户 `t1`

DROP TENANT t1 FORCE;

管理变量

查看变量

查询 Session/Global 级别变量语句的语法

SHOW [GLOBAL] VARIABLES [SHOW_VARIABLES_OPTS]

SHOW_VARIABLES_OPTS:
[LIKE 'pattern' | WHERE expr]

示例

SHOW VARIABLES LIKE 'ob_query_timeout';
SHOW GLOBAL VARIABLES WHERE variable_name LIKE 'ob_query_timeout';

sys 租户可以通过内部表 __all_virtual_sys_variable查询其他所有普通租户的 Global 变量。

select * from __all_virtual_sys_variable;

如果连接 sys 租户后再切换到普通租户，此时查询的 Session 级别变量仍然是 sys 租户的 Session 级别的变量。查询的 Global 级别的变量是切换后普通租户的 Global 级别变量。

设置变量

设置 Session 级别的变量仅对当前 Session 有效，对其他 Session无效。设置 Global 级别的变量对当前 Session 无效，需要重新登录建立新的 Session 才会生效。

语法

SET [GLOBAL] VARIABLE_NAME = 'VALUE'

示例

SET ob_query_timeout = 20000000;
SET GLOBAL ob_query_timeout = 20000000;

说明

变量中类型为 INT, 并且在 SHOW VARIABLE命令中显示 ON/OFF或者 True/False的变量，可以通过如下任意方法设置值：

SET @@foreign_key_checks = ON;

SET @@foreign_key_checks = 1;

SET @@foreign_key;

以上三种方式的 Session 级别变量的设置是等效的。