You can create log streams on a unit group (in homogeneous zone mode) or on a UNIT_LIST (in heterogeneous zone mode) based on your business requirements. This lets you manually adjust the number of log streams for a tenant across service nodes.
Background information
The current version supports tenants in homogeneous zone mode and heterogeneous zone mode. In these modes, you create log streams in the following ways:
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 you create a log stream, consider the following points:
Only regular (user) log streams can be created. Broadcast log streams are not supported.
You can create a log stream only for the primary tenant. The
STATUSandSWITCHOVER_STATUSof the tenant where the log stream is to be created must both beNORMAL.When you create a log stream:
- In homogeneous zone mode, the status of the target
UNIT_GROUPmust beACTIVE, and the value of theUNIT_GROUP_IDcolumn in theDBA_OB_UNITSview must not be 0. - In heterogeneous zone mode, the status of the target
UNIT_LISTmust beACTIVE, and the specified targetUNIT_LISTmust not be empty.
- In homogeneous zone mode, the status of the target
When you specify the
PRIMARY_ZONEfor the log stream, ensure that the zone is included in the tenant'sZONE_LIST. For log streams, only a single zone, such asz1orz2, can be specified for thePRIMARY_ZONEparameter. Unlike tenants, log streams cannot have multiple zones, such asz1,z2,z1; z2, orRANDOMspecified forPRIMARY_ZONE.We recommend that you set load balancing-related parameters to
False. Otherwise:If the tenant-level parameter enable_rebalance is set to
True, the created log stream may be migrated by the system from the targetUNIT_GROUP/UNIT_LISTto anotherUNIT_GROUP/UNIT_LIST.If the tenant-level parameter enable_transfer is set to
True, the created log stream may be deleted.
Step 1: Perform checks before the creation
Log in to the
systenant or a user tenant of the cluster as the administrator.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 tenant status,
PRIMARY_ZONE, and locality information.When you create a log stream, make sure that the
STATUSandSWITCHOVER_STATUSvalues areNORMALfor the tenant. If you want to specify thePRIMARY_ZONEvalue of the log stream, make sure that the specified zone is in the tenant'sZONE_LIST. You can determine the zones in the tenant'sZONE_LISTbased on the tenant's locality.System tenant
obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, STATUS, SWITCHOVER_STATUS, TENANT_ROLE, 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 TENANT_ID, TENANT_NAME, STATUS, SWITCHOVER_STATUS, TENANT_ROLE, PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;The following example shows the query result:
+-----------+-------------+--------+-------------------+-------------+--------------+-------------------------------------+ | TENANT_ID | TENANT_NAME | STATUS | SWITCHOVER_STATUS | TENANT_ROLE | PRIMARY_ZONE | LOCALITY | +-----------+-------------+--------+-------------------+-------------+--------------+-------------------------------------+ | 1002 | mq_t1 | NORMAL | NORMAL | PRIMARY | RANDOM | FULL{1}@z1, FULL{1}@z2 | +-----------+-------------+--------+-------------------+-------------+--------------+-------------------------------------+ 1 row in set
Query the unit information of the tenant and confirm that the status of the target
UNIT_GROUP(in homogeneous zone mode) orUNIT_LIST(in heterogeneous zone mode) isACTIVE.Execute the following command under the sys tenant to query the unit information of a tenant.
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 | xx.xx.xx.91 | 2882 | | 1001 | 1002 | z2 | xx.xx.xx.127 | 2882 | +---------------+---------+-------+--------------+----------+ 3 rows in setConfirm whether the parameters enable_rebalance and enable_transfer are disabled, that is, their values are
False.In a user tenant, execute the following commands to query the parameter values.
obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';obclient> SHOW PARAMETERS LIKE '%enable_transfer%';If the value is
True, you can execute the following commands to change the values toFalse.obclient> ALTER SYSTEM SET enable_rebalance = False;obclient> ALTER SYSTEM SET enable_transfer = False;
Step 2: Create a log stream
After confirming that all checks meet the requirements, select the appropriate operation based on your business needs to create a log stream for the tenant.
Create a 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***** -ACreate a log stream.
The SQL statement for creating a log stream in the system tenant is as follows:
ALTER SYSTEM CREATE LS {UNIT_GROUP [=] unit_group_id} | {UNIT_LIST [=] (unit_id_list) }[, PRIMARY_ZONE [=] 'zone_name'] TENANT [=] 'tenant_name';The statement is described as follows:
unit_group_id: the ID of theUNIT_GROUPto which the log stream belongs. This parameter applies only to tenants in homogeneous zone mode. You can query theoceanbase.DBA_OB_UNITSview in the system tenant to obtain theunit_group_id.unit_id_list: The list of units where the log stream will be distributed. This parameter applies only to tenants in heterogeneous zone mode. You can obtain theunit_id_listby querying theoceanbase.DBA_OB_UNITSview under the system tenant. Each zone has at most one unit.zone_name: the name of the target zone. If you do not specifyPRIMARY_ZONE, the system will allocate it based on the rule of maintaining balance for the sameUNIT_GROUP(homogeneous zone mode) orUNIT_LIST(heterogeneous zone mode) in the tenant.tenant_name: the name of the tenant to which the log stream belongs.
Here are some examples:
Homogeneous zone modeHeterogeneous zone modeCreate a log stream on the
UNIT_GROUPwith ID 1001.obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_GROUP 1001 TENANT = mq_t1;After the statement is executed, the system creates a log stream on the specified
UNIT_GROUP_ID1001 (whose corresponding units are 1001 and 1002).Create a log stream on the
UNIT_GROUPwith ID 1001 and set itsPRIMARY_ZONEtoz1.obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_GROUP 1001, PRIMARY_ZONE 'z1' TENANT = mq_t1;After the statement is executed, the system creates a log stream on the specified
UNIT_GROUP_ID1001 (whose corresponding units are 1001 and 1002), and its primary zone isz1.
Create a log stream on the
UNIT_ID1001 and 1002 in theUNIT_LIST.obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002) TENANT = mq_t1;After the statement is executed, the system creates a log stream on the
UNIT_ID1001 and 1002 in theUNIT_LIST.Create a log stream on the
UNIT_ID1001 and 1002 in theUNIT_LISTand set thePRIMARY_ZONEof the log stream toz1.obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002), PRIMARY_ZONE 'z1' TENANT = mq_t1;After the statement is executed, the system creates a log stream on the specified
UNIT_LISTof units with IDs 1001 and 1002, and its primary zone isz1.
Confirm the created log stream.
Obtain the
LS_IDof the newly created log stream.obclient(root@sys)[oceanbase]> SELECT * FROM oceanbase.CDB_OB_TENANT_EVENT_HISTORY WHERE EVENT='CREATE LS' AND TENANT_ID=1002 ORDER BY TIMESTAMP DESC LIMIT 1\GAn example of the query result is as follows:
*************************** 1. row *************************** TENANT_ID: 1002 TIMESTAMP: 2026-01-09 11:31:14.284278 MODULE: LS COMMAND EVENT: CREATE LS NAME1: ARGS VALUE1: {op:1, op str:"CREATE LS", tenant_id:1002, ls_id:{id:-1}, unit_group_id:1001, ls_primary_zone:"z1"} NAME2: LS_ID VALUE2: 1003 NAME3: LS_GROUP_ID VALUE3: 1002 NAME4: UNIT_GROUP_ID VALUE4: 1001 NAME5: PRIMARY_ZONE VALUE5: z1 NAME6: NULL VALUE6: EXTRA_INFO: NULL SVR_IP: 6.xx.xxx.xxx SVR_PORT: 13324 TRACE_ID: Y3xxxxxxxxxxx-xxxxxxxxxxxxxxx-x-x COST_TIME: 19407 RET_CODE: 0 ERROR_MSG: NULL 1 row in setAs shown in the query result, the
LS_IDof the new log stream is 1003.Confirm the details of the new log stream.
obclient(root@sys)[oceanbase]> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.CDB_OB_LS WHERE TENANT_ID=1002 AND LS_ID = 1003;An example of the query result is as follows:
+-------+--------+--------------+-------------+----------------+ | LS_ID | STATUS | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST | +-------+--------+--------------+-------------+----------------+ | 1003 | NORMAL | z1;z2 | 1001 | 1001,1002 | +-------+--------+--------------+-------------+----------------+ 1 row in setAccording to the query result, the status of the newly created log stream is
NORMAL, its primary zone isz1, and it is distributed across theUNIT_LISTof units with IDs 1001 and 1002 (in homogeneous zone mode, this corresponds to the set of units with the sameUNIT_GROUP_IDin theoceanbase.DBA_OB_UNITSview). This matches the expected results, indicating that the log stream has been successfully created.
Create a 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***** -ACreate a log stream.
The SQL statement for creating a log stream in a user tenant is as follows:
ALTER SYSTEM CREATE LS {UNIT_GROUP [=] unit_group_id} | {UNIT_LIST [=] (unit_id_list) }[, PRIMARY_ZONE [=] 'zone_name'];The statement is described as follows:
unit_group_id: the ID of theUNIT_GROUPto which the log stream belongs. This parameter is applicable only to tenants in homogeneous zone mode. You can obtainunit_group_idby querying theoceanbase.DBA_OB_UNITSview in the system tenant.unit_id_list: the list of units to which the log stream is distributed. This parameter is applicable only to tenants in heterogeneous zone mode. You can obtainunit_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. If you do not specifyPRIMARY_ZONE, the system assigns a zone based on the rule of keeping the primary zone balanced within the sameUNIT_GROUP(homogeneous zone mode) orUNIT_LIST(heterogeneous zone mode) in the tenant.
Examples:
Homogeneous zone modeHeterogeneous zone modeCreate a log stream on the
UNIT_GROUPwith ID 1001.obclient> ALTER SYSTEM CREATE LS UNIT_GROUP 1001;After the statement is executed, the system creates a log stream on the specified
UNIT_GROUP_ID1001 (whose corresponding units are 1001 and 1002).Create a log stream on the
UNIT_GROUPwith ID 1001 and set itsPRIMARY_ZONEtoz1.obclient> ALTER SYSTEM CREATE LS UNIT_GROUP 1001, PRIMARY_ZONE 'z1';After the statement is executed, the system creates a log stream on the specified
UNIT_GROUP_ID1001 (whose corresponding units are 1001 and 1002), and its primary zone isz1.
Create a log stream on the
UNIT_LISTwithUNIT_ID1001 and 1002.obclient> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002);After the statement is executed, the system creates a log stream on the specified
UNIT_LISTwith IDs 1001 and 1002.Create a log stream on the
UNIT_LISTwithUNIT_ID1001 and 1002, and set thePRIMARY_ZONEof the log stream toz1.obclient> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002), PRIMARY_ZONE 'z1';After the statement is executed, the system creates a log stream on the specified
UNIT_LISTwith IDs 1001 and 1002, and its primary zone isz1.
Confirm the created log stream.
Obtain the
LS_IDof the newly created log stream.obclient> SELECT * FROM oceanbase.DBA_OB_TENANT_EVENT_HISTORY WHERE EVENT='CREATE LS' ORDER BY TIMESTAMP DESC LIMIT 1\GAn example of the query result is as follows:
*************************** 1. row *************************** TENANT_ID: 1002 TIMESTAMP: 2026-01-09 11:31:14.284278 MODULE: LS COMMAND EVENT: CREATE LS NAME1: ARGS VALUE1: {op:1, op str:"CREATE LS", tenant_id:1002, ls_id:{id:-1}, unit_group_id:1001, ls_primary_zone:"z1"} NAME2: LS_ID VALUE2: 1003 NAME3: LS_GROUP_ID VALUE3: 1002 NAME4: UNIT_GROUP_ID VALUE4: 1001 NAME5: PRIMARY_ZONE VALUE5: z1 NAME6: NULL VALUE6: EXTRA_INFO: NULL SVR_IP: 6.xx.xxx.xxx SVR_PORT: 13324 TRACE_ID: Y3xxxxxxxxxxx-xxxxxxxxxxxxxxx-x-x COST_TIME: 19407 RET_CODE: 0 ERROR_MSG: NULL 1 row in setAs shown in the query result, the
LS_IDof the new log stream is 1003.Check the details of the new log stream.
obclient> SELECT LS_ID, STATUS, PRIMARY_ZONE, LS_GROUP_ID, UNIT_LIST FROM oceanbase.DBA_OB_LS WHERE LS_ID = 1003;An example of the query result is as follows:
+-------+--------+--------------+-------------+----------------+ | LS_ID | STATUS | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST | +-------+--------+--------------+-------------+----------------+ | 1003 | NORMAL | z1;z2 | 1001 | 1001,1002 | +-------+--------+--------------+-------------+----------------+ 1 row in setThe query result shows that the status of the new log stream is
NORMAL, the primary zone isz1, and the log stream is distributed on theUNIT_LISTwithUNIT_ID1001 and 1002 (which corresponds to a group of units with the sameUNIT_GROUP_IDin theoceanbase.DBA_OB_UNITSview in homogeneous zone mode), which is consistent with the expected result.