Create a log stream

You can create log streams on a unit group (in homogeneous zone mode) or on a UNIT_LIST (in heterogeneous zone mode) to manually adjust the number of log streams for each tenant across service nodes.

Background information

This version supports tenants in homogeneous zone and heterogeneous zone 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_LIST to 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, note the following:

• 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 STATUS and SWITCHOVER_STATUS of the tenant where the log stream is to be created must both be NORMAL.

• When creating a log stream:

  • In homogeneous zone mode, the status of the target UNIT_GROUP must be ACTIVE, and the value of the UNIT_GROUP_ID column in the DBA_OB_UNITS view must not be 0.
  • In heterogeneous zone mode, the status of the target UNIT_LIST must be ACTIVE, and the specified target UNIT_LIST must not be empty.

• When specifying the PRIMARY_ZONE for the log stream, ensure that the zone is included in the tenant's ZONE_LIST. For log streams, only a single zone, such as z1 or z2, can be specified for the PRIMARY_ZONE parameter. Unlike tenants, log streams cannot have multiple zones, such as z1,z2, z1; z2, or RANDOM specified for PRIMARY_ZONE.

• It is recommended to 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 target UNIT_GROUP/UNIT_LIST to another UNIT_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

1. Log in to the sys tenant or 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***** -A
   

2. Query the tenant status, PRIMARY_ZONE, and locality information.

   When you create a log stream, make sure that the STATUS and SWITCHOVER_STATUS values are NORMAL for the tenant. If you want to specify the PRIMARY_ZONE value of the log stream, make sure that the specified zone is in the tenant's ZONE_LIST. You can refer to the zones in the locality of the tenant for more information.

   • 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

     MySQL-compatible mode

     Oracle-compatible mode

     In MySQL-compatible mode, 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;
     

     In Oracle-compatible mode, run the following command to query the tenant status.

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

   The query result is as follows:

   +-----------+-------------+--------+-------------------+-------------+--------------+-------------------------------------+
   | 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, FULL{1}@z3  |
   +-----------+-------------+--------+-------------------+-------------+--------------+-------------------------------------+
   1 row in set
   

3. Query the unit information of the tenant to confirm that the status of the target UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) is ACTIVE.

   In the system tenant, run the following command to query the unit information of the 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   | 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
   

4. Check whether the values of parameters enable_rebalance and enable_transfer are False.

   In the user tenant, run the following command to query the values of the parameters.

   obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';
   

   obclient> SHOW PARAMETERS LIKE '%enable_transfer%';
   

   If the values are True, run the following command to set the values to False.

   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

1. Log in to the sys tenant of the cluster as the root user.

   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***** -A
   

2. Create 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 the UNIT_GROUP to which the log stream belongs. This parameter applies only to tenants in homogeneous zone mode. You can query the oceanbase.DBA_OB_UNITS view in the system tenant to obtain the unit_group_id.

   • unit_id_list: the list of units to which the log stream is distributed. This parameter applies only to tenants in heterogeneous zone mode. You can query the oceanbase.DBA_OB_UNITS view in the system tenant to obtain the unit_id_list. Each zone can contain at most one unit.

   • zone_name: the name of the target zone. If you do not specify PRIMARY_ZONE, the system will allocate it based on the rule of maintaining balance for the same UNIT_GROUP (homogeneous zone mode) or UNIT_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 mode

   Heterogeneous zone mode

   • Create a log stream on the UNIT_GROUP with 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 UNIT_GROUP_ID 1001 (which contains units 1001, 1002, and 1003).

   • Create a log stream on the UNIT_GROUP with ID 1001 and set the PRIMARY_ZONE of the log stream to z1.

     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 UNIT_GROUP_ID 1001 (which contains units 1001, 1002, and 1003), and the primary zone is z1.

   • Create a log stream on the UNIT_ID 1001, 1002, and 1003 in the UNIT_LIST.

     obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002,1003) TENANT = mq_t1;
     

     After the statement is executed, the system creates a log stream on the UNIT_ID 1001, 1002, and 1003 in the UNIT_LIST.

   • Create a log stream on the UNIT_ID 1001, 1002, and 1003 in the UNIT_LIST and set the PRIMARY_ZONE of the log stream to z1.

     obclient(root@sys)[(none)]> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002,1003), PRIMARY_ZONE 'z1' TENANT = mq_t1;
     

     After the statement is executed, the system creates a log stream on the UNIT_ID 1001, 1002, and 1003 in the UNIT_LIST, and the primary zone is z1.

3. Confirm the log stream.

   1. Obtain the LS_ID of the new 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\G
      

      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 set
      

      As shown in the query result, the LS_ID of the new log stream is 1003.

   2. 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;
      

      The query result is as follows:

      +-------+--------+--------------+-------------+----------------+
      | LS_ID | STATUS | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
      +-------+--------+--------------+-------------+----------------+
      |  1003 | NORMAL | z1;z2,z3     |        1001 | 1001,1002,1003 |
      +-------+--------+--------------+-------------+----------------+
      1 row in set
      

      As shown in the query result, the status of the new log stream is NORMAL, the primary zone is z1, and the log stream is distributed on the UNIT_LIST 1001, 1002, and 1003 (in homogeneous zone mode, the units with the same UNIT_GROUP_ID in the oceanbase.DBA_OB_UNITS view), which matches the expected result, indicating that the log stream was created successfully.

Create a log stream as the user tenant

1. Connect to the database as the tenant administrator of a MySQL-compatible or Oracle-compatible 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***** -A
   

2. Create 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 the UNIT_GROUP to which the log stream belongs. This parameter is applicable only to tenants in homogeneous zone mode. You can obtain unit_group_id by querying the oceanbase.DBA_OB_UNITS view 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 obtain unit_id_list by querying the oceanbase.DBA_OB_UNITS view in the system tenant. Each zone can have at most one unit.

   • zone_name: the name of the target zone. If you do not specify PRIMARY_ZONE, the system assigns a zone based on the rule of keeping the primary zone balanced within the same UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) in the tenant.

   Here are some examples:

   Homogeneous zone mode

   Heterogeneous zone mode

   • Create a log stream on the UNIT_GROUP with ID 1001.

     obclient> ALTER SYSTEM CREATE LS UNIT_GROUP 1001;
     

     After the statement is executed, the system creates a log stream on the UNIT_GROUP_ID 1001 (which corresponds to units 1001, 1002, and 1003).

   • Create a log stream on the UNIT_GROUP with ID 1001 and set the primary zone of the log stream to z1.

     obclient> ALTER SYSTEM CREATE LS UNIT_GROUP 1001, PRIMARY_ZONE 'z1';
     

     After the statement is executed, the system creates a log stream on the UNIT_GROUP_ID 1001 (which corresponds to units 1001, 1002, and 1003), and the primary zone of the log stream is z1.

   • Create a log stream on the UNIT_LIST with UNIT_ID 1001, 1002, and 1003.

     obclient> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002,1003);
     

     After the statement is executed, the system creates a log stream on the UNIT_LIST with UNIT_ID 1001, 1002, and 1003.

   • Create a log stream on the UNIT_LIST with UNIT_ID 1001, 1002, and 1003 and set the primary zone of the log stream to z1.

     obclient> ALTER SYSTEM CREATE LS UNIT_LIST (1001,1002,1003), PRIMARY_ZONE 'z1';
     

     After the statement is executed, the system creates a log stream on the UNIT_LIST with UNIT_ID 1001, 1002, and 1003, and the primary zone of the log stream is z1.

3. Confirm the log stream.

   Take a MySQL mode tenant as an example. The operation is as follows.

   1. Obtain the LS_ID of the new log stream.

      obclient> SELECT * FROM oceanbase.DBA_OB_TENANT_EVENT_HISTORY WHERE EVENT='CREATE LS' ORDER BY TIMESTAMP DESC LIMIT 1\G
      

      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 set
      

      The LS_ID of the new log stream is 1003.

   2. 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;
      

      The query result is as follows:

      +-------+--------+--------------+-------------+----------------+
      | LS_ID | STATUS | PRIMARY_ZONE | LS_GROUP_ID | UNIT_LIST      |
      +-------+--------+--------------+-------------+----------------+
      |  1003 | NORMAL | z1;z2,z3     |        1001 | 1001,1002,1003 |
      +-------+--------+--------------+-------------+----------------+
      1 row in set
      

      The query result shows that the status of the new log stream is NORMAL, the primary zone is z1, and the log stream is distributed on the UNIT_LIST with UNIT_ID 1001, 1002, and 1003 (which corresponds to a group of units with the same UNIT_GROUP_ID in the oceanbase.DBA_OB_UNITS view in homogeneous zone mode), which is consistent with the expected result.