A log stream belongs to a log stream group. The number of log streams in a group is determined by the number of zones in the primary zone. Each zone in the primary zone's zone list hosts the leader of one log stream in the group.
You can manually rebalance log streams across UNIT_GROUPs (in homogeneous zone mode) or UNIT_LISTs (in heterogeneous zone mode) as needed.
Background information
The current version supports tenants in homogeneous zone and heterogeneous zone modes. In these modes:
In homogeneous zone mode, you must specify a unit group to create a log stream.
In heterogeneous zone mode, you must specify a
UNIT_LISTto create a log stream.For more information about the differences between homogeneous zone mode and heterogeneous zone mode, see Data distribution.
Considerations
Before modifying a log stream, note the following:
The log stream to be modified must exist and its status must be
NORMAL.The tenant of the log stream to be modified must be in the
NORMALstate.When modifying the
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) of a log stream, ensure that none of the tenant's log streams are currently involved in a load balancing task.When modifying the
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) of a log stream, ensure that the targetUNIT_GROUPorUNIT_LISTis in theACTIVEstate.When modifying the
PRIMARY_ZONEof a log stream, ensure that the new zone is included in the tenant'sZONE_LIST. For log streams, only a single zone (for example,z1orz2) can be set as thePRIMARY_ZONE. Multiple zones (for example,z1,z2,z1; z2) orRANDOMare not allowed.When modifying a log stream, ensure that the tenant-level parameter
enable_rebalanceis disabled, meaning its value isFalse. Ifenable_rebalanceis enabled, the tenant's load balancing module may automatically adjust the log stream'sPRIMARY_ZONEandUNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) attributes.In homogeneous zone mode, only broadcast log streams and system log streams (Log Stream 1) support setting the
UNIT_GROUPto 0.In heterogeneous zone mode, the specified
UNIT_LISTfor a user log stream cannot be empty.
Step 1: Perform checks before the modification
Log in to the cluster as the administrator user in the
systenant or a user tenant.Below is a sample connection command. Adjust the database connection details according to your actual environment.
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -AQuery the status of the tenant containing the log stream to be modified and ensure the tenant status is
NORMAL.System tenant
obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';User tenant
Run the following command to query the tenant status.
obclient> SELECT TENANT_ID, TENANT_NAME, STATUS, TENANT_ROLE FROM oceanbase.DBA_OB_TENANTS;The following example shows the query result:
+-----------+-------------+--------+-------------+ | TENANT_ID | TENANT_NAME | STATUS | TENANT_ROLE | +-----------+-------------+--------+-------------+ | 1002 | mq_t1 | NORMAL | PRIMARY | +-----------+-------------+--------+-------------+ 1 row in setThe tenant status is
NORMAL.
Query whether there are any ongoing load balancing tasks for the tenant's log streams. When modifying the
UNIT_GROUP(in homogeneous zone mode) orUNIT_LIST(in heterogeneous zone mode) of a log stream on the primary tenant, all log streams of the tenant must currently have no load balancing tasks.System tenant
obclient(root@sys)[oceanbase]> SELECT count(*) AS task_cnt FROM oceanbase.CDB_OB_BALANCE_TASKS WHERE TENANT_ID=1002 AND (SRC_LS = 1001 or DEST_LS=1001);User tenant
Run the following command to query the load balancing task status of the tenant's log streams.
obclient> SELECT count(*) AS task_cnt FROM oceanbase.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;The following example shows the query result:
+----------+ | task_cnt | +----------+ | 0 | +----------+ 1 row in setA query result of
0indicates that there are currently no ongoing load balancing tasks for the tenant's log streams.
Query the information about the log streams under the tenant to ensure that the log stream to be modified exists and its status is
NORMAL. If you want to change a broadcast log stream, you also need to confirm whether the specified log stream is a broadcast log stream.Query the log stream information under the tenant.
System tenant
obclient(root@sys)[oceanbase]> 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';User tenant
Run the following command to query the log stream information under the tenant.
obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID != 1 AND STATUS = 'NORMAL';The following example shows the query result:
+-------+--------------+-------------+----------------+ | LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST | +-------+--------------+-------------+----------------+ | 1001 | z1;z2 | 1001 | 1001,1002 | | 1002 | z2;z1 | 1001 | 1001,1002 | | 1004 | z1;z2 | 1002 | 1004,1005 | | 1005 | z2;z1 | 1002 | 1004,1005 | +-------+--------------+-------------+----------------+ 4 rows in set
If you want to confirm whether the log stream is a broadcast log stream, check the value of the
FLAGcolumn. If the value isDUPLICATE, the log stream is a broadcast log stream.System tenant
obclient(root@sys)[oceanbase]> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID=1002;User tenant
Run the following command to confirm whether the log stream is a broadcast log stream.
obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, FLAG, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID=1002;
If you want to modify the
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) of a log stream, you need to query the unit information of the tenant and ensure that the remaining capacity of the data disk on the targetUNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) can accommodate the log stream to be modified.The following operations must be performed in the sys tenant.
Run the following command to query the unit information of the tenant and confirm that the status of the target
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode) isACTIVE.obclient(root@sys)[oceanbase]> 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;The query result is as follows:
+---------------+---------+------+----------------+----------+ | 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 | | 1002 | 1004 | z1 | xxx.xx.xxx.194 | 2882 | | 1002 | 1005 | z2 | xxx.xx.xxx.192 | 2882 | +---------------+---------+------+----------------+----------+ 4 rows in setBased on the obtained
UNIT_GROUP_IDand its correspondingSVR_IPandSVR_PORTinformation, query the remaining capacity of the data disk on the server corresponding to the targetUNIT_GROUP.obclient(root@sys)[oceanbase]> 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;The query result is as follows:
+----------------+----------+----------------------+ | 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.194 | 2882 | 4.925781250000 | | xxx.xx.xxx.192 | 2882 | 4.875000000000 | +----------------+----------+----------------------+ 4 rows in setQuery the data disk capacity requirement for the log stream to be modified.
obclient(root@sys)[oceanbase]> 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;The query result is as follows:
+----------------+----------+-----------+-------+----------------+------------------+ | 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.194 | 2882 | 1002 | 1004 | 0.000007629395 | 0.000007629395 | | xxx.xx.xxx.192 | 2882 | 1002 | 1005 | 0.000007629395 | 0.000007629395 | +----------------+----------+-----------+-------+----------------+------------------+ 4 rows in setIn the query result,
OCCUPY_SIZE_GBindicates the actual disk space occupied by the tablets;REQUIRED_SIZE_GBindicates the disk space required to store the tablets. CompareOCCUPY_SIZE_GBandREQUIRED_SIZE_GBwith the remaining capacity of the data disk on the targetUNIT_GROUPorUNIT_LIST. If both values are less than the remaining capacity, the requirement is met.
If you want to modify the
PRIMARY_ZONEof a log stream, ensure that the new zone is included in the tenant'sZONE_LIST. The tenant'sZONE_LISTcan be confirmed through the tenant's locality information.System tenant
obclient(root@sys)[oceanbase]> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS WHERE tenant_name = 'mq_t1';User tenant
Run the following command to query the tenant status.
obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;An example of the query result is as follows:
+--------------+------------------------------------+ | PRIMARY_ZONE | LOCALITY | +--------------+------------------------------------+ | RANDOM | FULL{1}@z1, FULL{1}@z2 | +--------------+------------------------------------+In the sample result, the
LOCALITYof tenantmq_t1isFULL{1}@z1, FULL{1}@z2, indicating that the tenant'sZONE_LISTcontains zonesz1andz2.
Check whether the value of the
enable_rebalanceparameter isFalse. If the value isTrue, after you perform a log stream change operation, the load balancing module of the tenant may automatically adjust thePRIMARY_ZONEandUNIT_GROUP(in homogeneous zone mode) orUNIT_LIST(in heterogeneous zone mode) attributes of the log stream.obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';If the value is not
False, run the following command to set the value of theenable_rebalanceparameter toFalse.System tenant
obclient(root@sys)[oceanbase]> ALTER SYSTEM SET enable_rebalance = 'False' TENANT = mq_t1;User tenant
obclient> ALTER SYSTEM SET enable_rebalance = 'False';
Step 2: Modify the log stream
After all the checks are passed, perform the required operation to modify the log stream based on your business needs.
Modify the log stream for a user tenant as the system tenant
Log in to the
systenant of the cluster as therootuser.Below is a sample connection command. Adjust the database connection details according to your actual environment.
obclient -h10.xx.xx.xx -P2883 -uroot@sys#obdemo -p***** -AModify the log stream.
In the system tenant, the SQL statement for modifying the log stream of a user tenant is as follows:
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list)][, PRIMARY_ZONE [=] 'zone_name'] TENANT [=] 'tenant_name';The statement is described as follows:
ls_id: the ID of the log stream to be modified.unit_group_id: the ID of the target unit group to which the log stream is to be modified. This parameter is applicable only to tenants in homogeneous zone mode. You can obtain theunit_group_idby querying theoceanbase.DBA_OB_UNITSview in the system tenant.unit_id_list: the list of target units to which the log stream is to be modified. This parameter is applicable only to tenants in heterogeneous zone mode. You can obtain theunit_id_listby querying theoceanbase.DBA_OB_UNITSview in the system tenant. Each zone can contain at most one unit.zone_name: the name of the target zone.tenant_name: the name of the target tenant of the log stream.When performing the log stream modification operation, you must modify at least one attribute of the log stream:
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode), orPRIMARY_ZONE.
Examples:
Homogeneous zone modeHeterogeneous zone modeModify only the
UNIT_GROUPof the log stream.Move log stream 1002 of tenant
mq_t1toUNIT_GROUP1002.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002 TENANT = mq_t1;Modify only the
PRIMARY_ZONEof the log stream.Change the primary zone of the leader of log stream 1002 of tenant
mq_t1toz1.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;Modify both the
UNIT_GROUPandPRIMARY_ZONEof the log stream.Move log stream 1002 of tenant
mq_t1toUNIT_GROUP1002, and change the primary zone of the leader of the log stream toz1.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1' TENANT = mq_t1;
Modify only the
UNIT_LISTof the log stream.Move log stream 1002 of tenant
mq_t1to theUNIT_LISTof units 1004 and 1005.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005) TENANT = mq_t1;Modify only the
PRIMARY_ZONEof the log stream.Change the primary zone of the leader of log stream 1002 of tenant
mq_t1toz1.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;Modify both the
UNIT_LISTandPRIMARY_ZONEof the log stream.Move log stream 1002 of tenant
mq_t1to theUNIT_LISTof units 1004 and 1005, and change the primary zone of the leader of the log stream toz1.obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005), PRIMARY_ZONE 'z1' TENANT = mq_t1;
Check whether the log stream has been successfully changed.
obclient(root@sys)[oceanbase]> 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';An example of the query result is as follows:
+-------+--------------+-------------+----------------+ | LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST | +-------+--------------+-------------+----------------+ | 1002 | z1;z2 | 1001 | 1004,1005 | +-------+--------------+-------------+----------------+ 1 row in setCompare the log stream before and after the change. If the
UNIT_LIST(in homogeneous zone mode, a group of units with the sameUNIT_GROUP_ID) andPRIMARY_ZONEof the log stream match the expected values, the change is successful.
Modify the log stream as the user tenant
Connect to the database as the tenant administrator of the user tenant.
Below is a sample connection command. Adjust the database connection details according to your actual environment.
obclient -h10.xx.xx.xx -P2883 -uroot@mq_t1#obdemo -p***** -AModify the log streams.
The SQL statement for a user tenant to modify log streams is as follows:
ALTER SYSTEM MODIFY LS [=] ls_id [UNIT_GROUP [=] unit_group_id] | [UNIT_LIST [=] (unit_id_list)][, PRIMARY_ZONE [=] 'zone_name'];The statement is described as follows:
ls_id: the ID of the log stream to be modified.unit_group_id: the ID of the target unit group to which the log stream is to be modified. This parameter is applicable only to tenants in homogeneous zone mode. You can obtain theunit_group_idby querying theoceanbase.DBA_OB_UNITSview in the system tenant.unit_id_list: the list of target units to which the log stream is to be modified. This parameter is applicable only to tenants in heterogeneous zone mode. You can obtain theunit_id_listby querying theoceanbase.DBA_OB_UNITSview in the system tenant. Each zone can contain at most one unit.zone_name: the name of the target zone.When you modify a log stream, you must modify at least one of the following attributes:
UNIT_GROUP(for homogeneous zone mode) orUNIT_LIST(for heterogeneous zone mode), orPRIMARY_ZONE.
Examples:
Homogeneous zone modeHeterogeneous zone modeModify only the
UNIT_GROUPof the log stream.Move log stream 1002 to
UNIT_GROUP1002.obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002;Modify only the
PRIMARY_ZONEof the log stream.Change the primary zone of the leader of log stream 1002 to
z1.obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';Modify both the
UNIT_GROUPandPRIMARY_ZONEof the log stream.Move log stream 1002 to
UNIT_GROUP1002, and change the primary zone of the leader of the log stream toz1.obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1';
Modify only the
UNIT_LISTof the log stream.Move log stream 1002 to the
UNIT_LISTof units 1004 and 1005.obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005);Modify only the
PRIMARY_ZONEof the log stream.Change the primary zone of the leader of log stream 1002 to
z1.obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';Modify both the
UNIT_LISTandPRIMARY_ZONEof the log stream.Move log stream 1002 to the
UNIT_LISTof units 1004 and 1005, and change the primary zone of the leader of the log stream toz1.obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005), PRIMARY_ZONE 'z1';
Check whether the log stream has been successfully modified.
obclient> SELECT LS_ID, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID = 1002 AND STATUS = 'NORMAL';An example of the query result is as follows:
+-------+--------------+-------------+----------------+ | LS_ID | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST | +-------+--------------+-------------+----------------+ | 1002 | z1;z2 | 1001 | 1004,1005 | +-------+--------------+-------------+----------------+ 1 row in setCompare the log stream before and after the modification. If the
UNIT_LIST(in homogeneous zone mode, a group of units with the sameUNIT_GROUP_ID) andPRIMARY_ZONEof the log stream match the expected values, the modification is successful.