变更日志流 - OceanBase 数据库 V4.2.5

一个日志流属于一个日志流组，在每个日志流组中，日志流的个数由 Primary Zone 中 Zone 的个数决定。从而 Primary Zone 的 Zone 列表中的每个 Zone 都可以分布着日志流组中一个日志流的 Leader。

用户可以根据需要，对日志流执行变更操作，手动均衡日志流在各个 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）间的分布。

使用限制

对于 V4.2.5 版本，仅 V4.2.5 BP1 及以上版本支持变更日志流操作。
在 V4.x 之前版本中，OceanBase 数据库仅支持租户的同构 Zone 模式。在 V4.2.5 版本中，从 V4.2.5 BP5 版本开始支持租户的异构 Zone 模式。其中：
- 同构 Zone 模式下，可以修改日志流分布的 UNIT_GROUP 以及日志流的 PRIMARY_ZONE。
- 异构 Zone 模式下，可以修改日志流分布的 UNIT_LIST 以及日志流的 PRIMARY_ZONE。
有关同构 Zone 模式和异构 Zone 模式的详细说明，参见数据分布。

注意事项

执行变更日志流操作前，需要注意以下事项：

待变更的日志流必须存在且状态必须为 NORMAL。
待变更日志流的租户其租户状态必须为 NORMAL。

说明

对于 V4.2.5 BP1 版本，要求待变更日志流的租户其租户状态不能是 CREATING 或者 DROPPING。
在主租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求租户的所有日志流当前没有负载均衡任务。
不建议在备租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。由于备租户会自动调整日志流的 UNIT_GROUP/UNIT_LIST 属性，手动修改备租户日志流的 UNIT_GROUP/UNIT_LIST属性可能不生效。
修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求目标 UNIT_GROUP/UNIT_LIST 的状态必须为 ACTIVE。
修改日志流的 PRIMARY_ZONE 时，需要保证修改后的 Zone 在租户的 ZONE_LIST 中。对于日志流而言，设置日志流的 PRIMARY_ZONE 与设置租户的 PRIMARY_ZONE 略有不同，日志流仅允许设置一个 Zone，例如 z1 或z2，不能像租户一样设置 z1,z2、z1; z2 或 RANDOM。
变更日志流时，要求租户级配置项 enable_rebalance 为关闭状态，即值为 False。当 enable_rebalance 为开启状态时，租户的负载均衡模块可能会自动调整日志流的 PRIMARY_ZONE 和 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。
只有广播日志流和系统日志流（1 号日志流）才支持指定 UNIT_GROUP 为 0。
异构 Zone 模式下，用户日志流指定的 UNIT_LIST 不能为空。

步骤一：变更前检查

管理员用户登录到集群的 sys 租户或用户租户。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -A
```

查询待变更日志流的租户的状态，确保租户状态为 NORMAL。

说明

对于 V4.2.5 BP1 版本，要求待变更日志流的租户的状态不是 CREATING 或者 DROPPING。

系统租户

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';

用户租户

MySQL 模式

Oracle 模式

MySQL 模式下，执行以下命令，查询租户状态。

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS;

Oracle 模式下，执行以下命令，查询租户状态。

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM SYS.DBA_OB_TENANTS;

查询结果的示例如下：

+-----------+-------------+--------+-------------+
| TENANT_ID | TENANT_NAME | STATUS | TENANT_ROLE |
+-----------+-------------+--------+-------------+
|      1002 | mq_t1       | NORMAL | PRIMARY     |
+-----------+-------------+--------+-------------+
1 row in set

根据查询结果，租户状态为 NORMAL。

查询租户的日志流当前是否有正在进行的负载均衡任务。在主租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求租户的所有日志流当前没有负载均衡任务。
- 系统租户
```
obclient> SELECT count(*) AS task_cnt FROM oceanbase.CDB_OB_BALANCE_TASKS WHERE TENANT_ID=1002 AND (SRC_LS = 1001 or DEST_LS=1001);
```
- 用户租户
  MySQL 模式
  
  Oracle 模式
  MySQL 模式下，执行以下命令，查询租户的日志流的负载均衡任务状态。
  
  obclient> SELECT count(*) AS task_cnt FROM oceanbase.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
  Oracle 模式下，执行以下命令，查询租户的日志流的负载均衡任务状态。
  
  obclient> SELECT count(*) AS task_cnt FROM SYS.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
查询结果的示例如下：
```
+----------+
| task_cnt |
+----------+
|        0 |
+----------+
1 row in set
```
查询结果为 0，表示租户的日志流当前无正在进行中的负载均衡任务。

查询租户下日志流的相关信息，确保待变更的日志流存在且状态为 NORMAL。如果想要变更广播日志流，还需要确认指定的日志流是否为广播日志流。

查询租户下的日志流信息。

系统租户

obclient> SELECT LS_ID, PRIMARY_ZONE LS_GROUP_ID, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID != 1 AND STATUS = 'NORMAL';

用户租户

MySQL 模式

Oracle 模式

MySQL 模式下，执行以下命令，查询租户下的日志流信息。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID != 1 AND STATUS = 'NORMAL';

Oracle 模式下，执行以下命令，查询租户下的日志流信息。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM SYS.DBA_OB_LS WHERE LS_ID != 1 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1001 | z1;z2,z3     |        1001 | 1001,1002,1003 |
|  1002 | z2;z1,z3     |        1001 | 1001,1002,1003 |
|  1003 | z3;z1,z2     |        1001 | 1001,1002,1003 |
|  1004 | z1;z2,z3     |        1002 | 1004,1005,1006 |
|  1005 | z2;z1,z3     |        1002 | 1004,1005,1006 |
|  1006 | z3;z1,z2     |        1002 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+
6 rows in set

根据查询到的日志流信息，如果需要确认日志流是否为广播日志流，还需要查看日志流 FLAG 列的信息，如果 FLAG 列的值 DUPLICATE，则表示该日志流为广播日志流。
- 系统租户
```
obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID=1003;
```
- 用户租户
  MySQL 模式
  
  Oracle 模式
  MySQL 模式下，执行以下命令，确认日志流是否为广播日志流。
  
  obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID=1003;
  Oracle 模式下，执行以下命令，确认日志流是否为广播日志流。
  
  obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM SYS.DBA_OB_LS WHERE LS_ID=1003;

如果要修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式），需要查询租户的 Unit 信息，并确保目标 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）上的数据盘剩余容量能容纳待变更的日志流。

以下操作需要在系统租户下执行。

执行以下命令，查询租户的 Unit 信息，并确认目标 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）的状态为 ACTIVE。

obclient> SELECT UNIT_GROUP_ID, UNIT_ID, ZONE, SVR_IP, SVR_PORT FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID=1002 AND STATUS = 'ACTIVE' ORDER BY UNIT_GROUP_ID;

查询结果如下：

+---------------+---------+------+----------------+----------+
| UNIT_GROUP_ID | UNIT_ID | ZONE | SVR_IP         | SVR_PORT |
+---------------+---------+------+----------------+----------+
|          1001 |    1001 | z1   | xxx.xx.xxx.198 |     2882 |
|          1001 |    1002 | z2   | xxx.xx.xxx.196 |     2882 |
|          1001 |    1003 | z3   | xxx.xx.xxx.204 |     2882 |
|          1002 |    1004 | z1   | xxx.xx.xxx.194 |     2882 |
|          1002 |    1005 | z2   | xxx.xx.xxx.192 |     2882 |
|          1002 |    1006 | z3   | xxx.xx.xxx.197 |     2882 |
+---------------+---------+------+----------------+----------+
6 rows in set

根据获取到的 UNIT_GROUP_ID、UNIT_ID 以及对应的 SVR_IP 和 SVR_PORT 信息，查询目标 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）对应机器的数据盘的剩余容量。

obclient> SELECT SVR_IP, SVR_PORT, (DATA_DISK_CAPACITY - DATA_DISK_IN_USE) / 1024 / 1024 / 1024 AS REST_DATA_SIZE_IN_GB FROM oceanbase.GV$OB_SERVERS;

查询结果如下：

+----------------+----------+----------------------+
| SVR_IP         | SVR_PORT | REST_DATA_SIZE_IN_GB |
+----------------+----------+----------------------+
| xxx.xx.xxx.196 |     2882 |       4.925781250000 |
| xxx.xx.xxx.198 |     2882 |       4.875000000000 |
| xxx.xx.xxx.204 |     2882 |       4.925781250000 |
| xxx.xx.xxx.194 |     2882 |       4.925781250000 |
| xxx.xx.xxx.192 |     2882 |       4.875000000000 |
| xxx.xx.xxx.197 |     2882 |       4.925781250000 |
+----------------+----------+----------------------+
6 rows in set

查询待变更的日志流对数据盘容量的要求。

obclient> SELECT SVR_IP, SVR_PORT, TENANT_ID, LS_ID, 
SUM(OCCUPY_SIZE)/1024/1024/1024 AS OCCUPY_SIZE_GB, 
SUM(REQUIRED_SIZE)/1024/1024/1024 AS REQUIRED_SIZE_GB 
FROM __ALL_VIRTUAL_TABLET_POINTER_STATUS 
WHERE TENANT_ID=1002 AND LS_ID=1001 
GROUP BY SVR_IP, SVR_PORT, TENANT_ID, LS_ID 
ORDER BY REQUIRED_SIZE_GB;

查询结果如下：

+----------------+----------+-----------+-------+----------------+------------------+
| SVR_IP         | SVR_PORT | TENANT_ID | LS_ID | OCCUPY_SIZE_GB | REQUIRED_SIZE_GB |
+----------------+----------+-----------+-------+----------------+------------------+
| xxx.xx.xxx.198 |     2882 |      1002 |  1001 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.196 |     2882 |      1002 |  1002 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.204 |     2882 |      1002 |  1003 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.194 |     2882 |      1002 |  1004 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.192 |     2882 |      1002 |  1005 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.197 |     2882 |      1002 |  1006 | 0.000007629395 |   0.000007629395 |
+----------------+----------+-----------+-------+----------------+------------------+
6 rows in set

查询结果中，OCCUPY_SIZE_GB 表示 Tablet 的实际数据占用的磁盘空间大小；REQUIRED_SIZE_GB 表示存放 Tablet 所需的磁盘空间大小。将 OCCUPY_SIZE_GB 和 REQUIRED_SIZE_GB 与目标 UNIT_GROUP/UNIT_LIST 上数据盘的剩余容量进行对比，如果 OCCUPY_SIZE_GB 和 REQUIRED_SIZE_GB 的值均小于目标 UNIT_GROUP/UNIT_LIST 上数据盘的剩余容量，则符合要求。

如果要修改日志流的 PRIMARY_ZONE，需要确保修改后的 Zone 在租户的 ZONE_LIST 中。租户的 ZONE_LIST 可以通过租户的 Locality 信息来确认。

系统租户

obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';

用户租户
MySQL 模式

Oracle 模式
MySQL 模式下，执行以下命令，查询租户状态。
obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;
Oracle 模式下，执行以下命令，查询租户状态。
obclient> SELECT PRIMARY_ZONE, LOCALITY FROM SYS.DBA_OB_TENANTS;

查询结果的示例如下：

+--------------+------------------------------------+
| PRIMARY_ZONE | LOCALITY                           |
+--------------+------------------------------------+
| RANDOM       | FULL{1}@z1, FULL{1}@z2, FULL{1}@z3 |
+--------------+------------------------------------+

示例结果中，租户 mq_t1 的 LOCALITY 为 FULL{1}@z1, FULL{1}@z2, FULL{1}@z3，表示租户的 ZONE_LIST 包含 z1、z2、z3 三个 Zone。

检查配置项 enable_rebalance 的值是否为 False。如果值为 True，执行日志流变更操作后，租户的负载均衡模块可能会自动调整日志流的 PRIMARY_ZONE 和 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。
```
obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';
```
如果值不为 False，则需要执行以下命令，将配置项 enable_rebalance 的值设置为 False。
- 系统租户
```
obclient> ALTER SYSTEM SET enable_rebalance = 'False' TENANT = mq_t1;
```
- 用户租户
```
obclient> ALTER SYSTEM SET enable_rebalance = 'False';
```

步骤二：变更日志流

确保各项检查符合要求后，根据业务情况，选择合适的操作，变更日志流。

系统租户修改用户租户的日志流

使用 root 用户登录到集群的 sys 租户。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -A
```
变更日志流。

系统租户下，修改用户租户日志流的 SQL 语句如下：
```
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list) ][,PRIMARY_ZONE [=] 'zone_name'] TENANT [=] 'tenant_name';
```
语句相关说明如下：
- ls_id：待变更的日志流的 ID。
- unit_group_id：指定待变更的日志流的目标 Unit Group 的 ID，仅适用于同构 Zone 模式的租户。unit_group_id 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取。
- unit_id_list：指定待变更的日志流分布的目标 Unit 列表，仅适用于异构 Zone 模式的租户。unit_id_list 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取，每个 Zone 不超过一个 Unit。
- zone_name：目标 Zone 的名称。
- tenant_name：待变更日志流的目标租户的名称。
- 执行变更日志流的操作时，需要至少修改日志流的其中一个属性 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）或 PRIMARY_ZONE。
示例如下：
同构 Zone 模式

异构 Zone 模式
- 仅修改日志流的 UNIT_GROUP
  
  修改租户 mq_t1 的 1002 号日志流的位置到 1002 号的 UNIT_GROUP。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002 TENANT = mq_t1;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 同时修改日志流的 UNIT_GROUP 和 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 日志流的位置到 1002 的 UNIT_GROUP，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 仅修改日志流的 UNIT_LIST
  
  修改租户 mq_t1 的 1002 号日志流的位置到 1004、1005、1006 的 UNIT_LIST 上。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006) TENANT = mq_t1;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 同时修改日志流的 UNIT_LIST 和 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 日志流的位置到 1004、1005、1006 的 UNIT_LIST 上，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1' TENANT = mq_t1;

检查日志流是否变更成功。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID = 1002 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1002 | z1;z2,z3     |        1001 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+

对比变更前与变更后的日志流，如果日志流对应的 UNIT_LIST(同构 Zone 模式下，对应 UNIT_GROUP_ID 相同的一组 Unit)、PRIMARY_ZONE 等与预期一致，则表示变更成功。

用户租户修改本租户的日志流

MySQL 模式租户或 Oracle 模式租户的租户管理员连接数据库。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@mq_t1#obdemo -p***** -A
```
变更日志流。

用户租户修改日志流的 SQL 语句如下：
```
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list) ][,PRIMARY_ZONE [=] 'zone_name'];
```
语句相关说明如下：
- ls_id：待变更的日志流的 ID。
- unit_group_id：指定待变更的日志流的目标 Unit Group 的 ID，仅适用于同构 Zone 模式的租户。unit_group_id 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取。
- unit_id_list：指定待变更的日志流分布的目标 Unit 列表，仅适用于异构 Zone 模式的租户。unit_id_list 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取，每个 Zone 不超过一个 Unit。
- zone_name：目标 Zone 的名称。
- 执行变更日志流的操作时，需要至少修改日志流的其中一个属性 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）或 PRIMARY_ZONE。
示例如下：
同构 Zone 模式

异构 Zone 模式
- 仅修改日志流的 UNIT_GROUP
  
  修改 1002 号日志流的位置到 1002 号的 UNIT_GROUP。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
- 同时修改日志流的 UNIT_GROUP 和 PRIMARY_ZONE
  
  修改 1002 日志流的位置到 1002 的 UNIT_GROUP，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1';
- 仅修改日志流的 UNIT_LIST
  
  修改 1002 号日志流的位置到 1004、1005、1006 的 UNIT_LIST 上。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006);
- 仅修改日志流的 PRIMARY_ZONE
  
  修改 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
- 同时修改日志流的 UNIT_LIST 和 PRIMARY_ZONE
  
  修改 1002 日志流的位置到 1004、1005、1006 的 UNIT_LIST 上，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1';

检查日志流是否变更成功。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID = 1002 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1002 | z1;z2,z3     |        1001 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+

用户可以根据需要，对日志流执行变更操作，手动均衡日志流在各个 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）间的分布。

使用限制

对于 V4.2.5 版本，仅 V4.2.5 BP1 及以上版本支持变更日志流操作。
在 V4.x 之前版本中，OceanBase 数据库仅支持租户的同构 Zone 模式。在 V4.2.5 版本中，从 V4.2.5 BP5 版本开始支持租户的异构 Zone 模式。其中：
- 同构 Zone 模式下，可以修改日志流分布的 UNIT_GROUP 以及日志流的 PRIMARY_ZONE。
- 异构 Zone 模式下，可以修改日志流分布的 UNIT_LIST 以及日志流的 PRIMARY_ZONE。
有关同构 Zone 模式和异构 Zone 模式的详细说明，参见数据分布。

注意事项

执行变更日志流操作前，需要注意以下事项：

待变更的日志流必须存在且状态必须为 NORMAL。
待变更日志流的租户其租户状态必须为 NORMAL。

说明

对于 V4.2.5 BP1 版本，要求待变更日志流的租户其租户状态不能是 CREATING 或者 DROPPING。
在主租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求租户的所有日志流当前没有负载均衡任务。
不建议在备租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。由于备租户会自动调整日志流的 UNIT_GROUP/UNIT_LIST 属性，手动修改备租户日志流的 UNIT_GROUP/UNIT_LIST属性可能不生效。
修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求目标 UNIT_GROUP/UNIT_LIST 的状态必须为 ACTIVE。
修改日志流的 PRIMARY_ZONE 时，需要保证修改后的 Zone 在租户的 ZONE_LIST 中。对于日志流而言，设置日志流的 PRIMARY_ZONE 与设置租户的 PRIMARY_ZONE 略有不同，日志流仅允许设置一个 Zone，例如 z1 或z2，不能像租户一样设置 z1,z2、z1; z2 或 RANDOM。
变更日志流时，要求租户级配置项 enable_rebalance 为关闭状态，即值为 False。当 enable_rebalance 为开启状态时，租户的负载均衡模块可能会自动调整日志流的 PRIMARY_ZONE 和 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。
只有广播日志流和系统日志流（1 号日志流）才支持指定 UNIT_GROUP 为 0。
异构 Zone 模式下，用户日志流指定的 UNIT_LIST 不能为空。

步骤一：变更前检查

管理员用户登录到集群的 sys 租户或用户租户。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -A
```

查询待变更日志流的租户的状态，确保租户状态为 NORMAL。

说明

对于 V4.2.5 BP1 版本，要求待变更日志流的租户的状态不是 CREATING 或者 DROPPING。

系统租户

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';

用户租户

MySQL 模式

Oracle 模式

MySQL 模式下，执行以下命令，查询租户状态。

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS;

Oracle 模式下，执行以下命令，查询租户状态。

obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM SYS.DBA_OB_TENANTS;

查询结果的示例如下：

+-----------+-------------+--------+-------------+
| TENANT_ID | TENANT_NAME | STATUS | TENANT_ROLE |
+-----------+-------------+--------+-------------+
|      1002 | mq_t1       | NORMAL | PRIMARY     |
+-----------+-------------+--------+-------------+
1 row in set

根据查询结果，租户状态为 NORMAL。

查询租户的日志流当前是否有正在进行的负载均衡任务。在主租户上修改日志流的 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）时，要求租户的所有日志流当前没有负载均衡任务。
- 系统租户
```
obclient> SELECT count(*) AS task_cnt FROM oceanbase.CDB_OB_BALANCE_TASKS WHERE TENANT_ID=1002 AND (SRC_LS = 1001 or DEST_LS=1001);
```
- 用户租户
  MySQL 模式
  
  Oracle 模式
  MySQL 模式下，执行以下命令，查询租户的日志流的负载均衡任务状态。
  
  obclient> SELECT count(*) AS task_cnt FROM oceanbase.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
  Oracle 模式下，执行以下命令，查询租户的日志流的负载均衡任务状态。
  
  obclient> SELECT count(*) AS task_cnt FROM SYS.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
查询结果的示例如下：
```
+----------+
| task_cnt |
+----------+
|        0 |
+----------+
1 row in set
```
查询结果为 0，表示租户的日志流当前无正在进行中的负载均衡任务。

查询租户下日志流的相关信息，确保待变更的日志流存在且状态为 NORMAL。如果想要变更广播日志流，还需要确认指定的日志流是否为广播日志流。

查询租户下的日志流信息。

系统租户

obclient> SELECT LS_ID, PRIMARY_ZONE LS_GROUP_ID, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID != 1 AND STATUS = 'NORMAL';

用户租户

MySQL 模式

Oracle 模式

MySQL 模式下，执行以下命令，查询租户下的日志流信息。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID != 1 AND STATUS = 'NORMAL';

Oracle 模式下，执行以下命令，查询租户下的日志流信息。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM SYS.DBA_OB_LS WHERE LS_ID != 1 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1001 | z1;z2,z3     |        1001 | 1001,1002,1003 |
|  1002 | z2;z1,z3     |        1001 | 1001,1002,1003 |
|  1003 | z3;z1,z2     |        1001 | 1001,1002,1003 |
|  1004 | z1;z2,z3     |        1002 | 1004,1005,1006 |
|  1005 | z2;z1,z3     |        1002 | 1004,1005,1006 |
|  1006 | z3;z1,z2     |        1002 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+
6 rows in set

根据查询到的日志流信息，如果需要确认日志流是否为广播日志流，还需要查看日志流 FLAG 列的信息，如果 FLAG 列的值 DUPLICATE，则表示该日志流为广播日志流。
- 系统租户
```
obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID=1003;
```
- 用户租户
  MySQL 模式
  
  Oracle 模式
  MySQL 模式下，执行以下命令，确认日志流是否为广播日志流。
  
  obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID=1003;
  Oracle 模式下，执行以下命令，确认日志流是否为广播日志流。
  
  obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM SYS.DBA_OB_LS WHERE LS_ID=1003;

以下操作需要在系统租户下执行。

执行以下命令，查询租户的 Unit 信息，并确认目标 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）的状态为 ACTIVE。

obclient> SELECT UNIT_GROUP_ID, UNIT_ID, ZONE, SVR_IP, SVR_PORT FROM oceanbase.DBA_OB_UNITS WHERE TENANT_ID=1002 AND STATUS = 'ACTIVE' ORDER BY UNIT_GROUP_ID;

查询结果如下：

+---------------+---------+------+----------------+----------+
| UNIT_GROUP_ID | UNIT_ID | ZONE | SVR_IP         | SVR_PORT |
+---------------+---------+------+----------------+----------+
|          1001 |    1001 | z1   | xxx.xx.xxx.198 |     2882 |
|          1001 |    1002 | z2   | xxx.xx.xxx.196 |     2882 |
|          1001 |    1003 | z3   | xxx.xx.xxx.204 |     2882 |
|          1002 |    1004 | z1   | xxx.xx.xxx.194 |     2882 |
|          1002 |    1005 | z2   | xxx.xx.xxx.192 |     2882 |
|          1002 |    1006 | z3   | xxx.xx.xxx.197 |     2882 |
+---------------+---------+------+----------------+----------+
6 rows in set

obclient> SELECT SVR_IP, SVR_PORT, (DATA_DISK_CAPACITY - DATA_DISK_IN_USE) / 1024 / 1024 / 1024 AS REST_DATA_SIZE_IN_GB FROM oceanbase.GV$OB_SERVERS;

查询结果如下：

+----------------+----------+----------------------+
| SVR_IP         | SVR_PORT | REST_DATA_SIZE_IN_GB |
+----------------+----------+----------------------+
| xxx.xx.xxx.196 |     2882 |       4.925781250000 |
| xxx.xx.xxx.198 |     2882 |       4.875000000000 |
| xxx.xx.xxx.204 |     2882 |       4.925781250000 |
| xxx.xx.xxx.194 |     2882 |       4.925781250000 |
| xxx.xx.xxx.192 |     2882 |       4.875000000000 |
| xxx.xx.xxx.197 |     2882 |       4.925781250000 |
+----------------+----------+----------------------+
6 rows in set

查询待变更的日志流对数据盘容量的要求。

obclient> SELECT SVR_IP, SVR_PORT, TENANT_ID, LS_ID, 
SUM(OCCUPY_SIZE)/1024/1024/1024 AS OCCUPY_SIZE_GB, 
SUM(REQUIRED_SIZE)/1024/1024/1024 AS REQUIRED_SIZE_GB 
FROM __ALL_VIRTUAL_TABLET_POINTER_STATUS 
WHERE TENANT_ID=1002 AND LS_ID=1001 
GROUP BY SVR_IP, SVR_PORT, TENANT_ID, LS_ID 
ORDER BY REQUIRED_SIZE_GB;

查询结果如下：

+----------------+----------+-----------+-------+----------------+------------------+
| SVR_IP         | SVR_PORT | TENANT_ID | LS_ID | OCCUPY_SIZE_GB | REQUIRED_SIZE_GB |
+----------------+----------+-----------+-------+----------------+------------------+
| xxx.xx.xxx.198 |     2882 |      1002 |  1001 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.196 |     2882 |      1002 |  1002 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.204 |     2882 |      1002 |  1003 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.194 |     2882 |      1002 |  1004 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.192 |     2882 |      1002 |  1005 | 0.000007629395 |   0.000007629395 |
| xxx.xx.xxx.197 |     2882 |      1002 |  1006 | 0.000007629395 |   0.000007629395 |
+----------------+----------+-----------+-------+----------------+------------------+
6 rows in set

如果要修改日志流的 PRIMARY_ZONE，需要确保修改后的 Zone 在租户的 ZONE_LIST 中。租户的 ZONE_LIST 可以通过租户的 Locality 信息来确认。

系统租户

obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';

用户租户
MySQL 模式

Oracle 模式
MySQL 模式下，执行以下命令，查询租户状态。
obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;
Oracle 模式下，执行以下命令，查询租户状态。
obclient> SELECT PRIMARY_ZONE, LOCALITY FROM SYS.DBA_OB_TENANTS;

查询结果的示例如下：

+--------------+------------------------------------+
| PRIMARY_ZONE | LOCALITY                           |
+--------------+------------------------------------+
| RANDOM       | FULL{1}@z1, FULL{1}@z2, FULL{1}@z3 |
+--------------+------------------------------------+

示例结果中，租户 mq_t1 的 LOCALITY 为 FULL{1}@z1, FULL{1}@z2, FULL{1}@z3，表示租户的 ZONE_LIST 包含 z1、z2、z3 三个 Zone。

检查配置项 enable_rebalance 的值是否为 False。如果值为 True，执行日志流变更操作后，租户的负载均衡模块可能会自动调整日志流的 PRIMARY_ZONE 和 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）属性。
```
obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';
```
如果值不为 False，则需要执行以下命令，将配置项 enable_rebalance 的值设置为 False。
- 系统租户
```
obclient> ALTER SYSTEM SET enable_rebalance = 'False' TENANT = mq_t1;
```
- 用户租户
```
obclient> ALTER SYSTEM SET enable_rebalance = 'False';
```

步骤二：变更日志流

确保各项检查符合要求后，根据业务情况，选择合适的操作，变更日志流。

系统租户修改用户租户的日志流

使用 root 用户登录到集群的 sys 租户。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -A
```
变更日志流。

系统租户下，修改用户租户日志流的 SQL 语句如下：
```
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list) ][,PRIMARY_ZONE [=] 'zone_name'] TENANT [=] 'tenant_name';
```
语句相关说明如下：
- ls_id：待变更的日志流的 ID。
- unit_group_id：指定待变更的日志流的目标 Unit Group 的 ID，仅适用于同构 Zone 模式的租户。unit_group_id 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取。
- unit_id_list：指定待变更的日志流分布的目标 Unit 列表，仅适用于异构 Zone 模式的租户。unit_id_list 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取，每个 Zone 不超过一个 Unit。
- zone_name：目标 Zone 的名称。
- tenant_name：待变更日志流的目标租户的名称。
- 执行变更日志流的操作时，需要至少修改日志流的其中一个属性 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）或 PRIMARY_ZONE。
示例如下：
同构 Zone 模式

异构 Zone 模式
- 仅修改日志流的 UNIT_GROUP
  
  修改租户 mq_t1 的 1002 号日志流的位置到 1002 号的 UNIT_GROUP。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002 TENANT = mq_t1;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 同时修改日志流的 UNIT_GROUP 和 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 日志流的位置到 1002 的 UNIT_GROUP，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 仅修改日志流的 UNIT_LIST
  
  修改租户 mq_t1 的 1002 号日志流的位置到 1004、1005、1006 的 UNIT_LIST 上。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006) TENANT = mq_t1;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- 同时修改日志流的 UNIT_LIST 和 PRIMARY_ZONE
  
  修改租户 mq_t1 的 1002 日志流的位置到 1004、1005、1006 的 UNIT_LIST 上，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1' TENANT = mq_t1;

检查日志流是否变更成功。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID = 1002 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1002 | z1;z2,z3     |        1001 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+

用户租户修改本租户的日志流

MySQL 模式租户或 Oracle 模式租户的租户管理员连接数据库。

连接示例如下，连接数据库时请以实际环境为准。
```
obclient -h10.xx.xx.xx -P2883 -uroot@mq_t1#obdemo -p***** -A
```
变更日志流。

用户租户修改日志流的 SQL 语句如下：
```
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list) ][,PRIMARY_ZONE [=] 'zone_name'];
```
语句相关说明如下：
- ls_id：待变更的日志流的 ID。
- unit_group_id：指定待变更的日志流的目标 Unit Group 的 ID，仅适用于同构 Zone 模式的租户。unit_group_id 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取。
- unit_id_list：指定待变更的日志流分布的目标 Unit 列表，仅适用于异构 Zone 模式的租户。unit_id_list 可在系统租户下，通过查询 oceanbase.DBA_OB_UNITS 视图获取，每个 Zone 不超过一个 Unit。
- zone_name：目标 Zone 的名称。
- 执行变更日志流的操作时，需要至少修改日志流的其中一个属性 UNIT_GROUP（同构 Zone 模式）/UNIT_LIST（异构 Zone 模式）或 PRIMARY_ZONE。
示例如下：
同构 Zone 模式

异构 Zone 模式
- 仅修改日志流的 UNIT_GROUP
  
  修改 1002 号日志流的位置到 1002 号的 UNIT_GROUP。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002;
- 仅修改日志流的 PRIMARY_ZONE
  
  修改 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
- 同时修改日志流的 UNIT_GROUP 和 PRIMARY_ZONE
  
  修改 1002 日志流的位置到 1002 的 UNIT_GROUP，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1';
- 仅修改日志流的 UNIT_LIST
  
  修改 1002 号日志流的位置到 1004、1005、1006 的 UNIT_LIST 上。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006);
- 仅修改日志流的 PRIMARY_ZONE
  
  修改 1002 号日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
- 同时修改日志流的 UNIT_LIST 和 PRIMARY_ZONE
  
  修改 1002 日志流的位置到 1004、1005、1006 的 UNIT_LIST 上，并修改日志流 Leader 的第一优先级到 z1。
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1';

检查日志流是否变更成功。

obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID = 1002 AND STATUS = 'NORMAL';

查询结果的示例如下：

+-------+--------------+-------------+----------------+
| LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
+-------+--------------+-------------+----------------+
|  1002 | z1;z2,z3     |        1001 | 1004,1005,1006 |
+-------+--------------+-------------+----------------+