Create a log stream

You can create log streams on a UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) based on your business needs to manually adjust the number of log streams for each tenant across service nodes.

Background information

The current version supports tenants in homogeneous zone mode and heterogeneous zone mode:

• In homogeneous zone mode, you need to specify a unit group to create a log stream.

• In heterogeneous zone mode, you need to 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 creating a log stream, note the following:

• Only regular user log streams can be created. Broadcast log streams are not supported.

• Creating a log stream can only be performed on the primary tenant. The STATUS and SWITCHOVER_STATUS of the tenant for which the log stream is to be created must both be NORMAL.

• When creating a log stream:

  • In homogeneous zone mode, the target UNIT_GROUP must be in the ACTIVE state, and the target UNIT_GROUP_ID in the DBA_OB_UNITS view must not be 0.

  • In heterogeneous zone mode, the target UNIT_LIST must be in the ACTIVE state, and the specified target UNIT_LIST must not be empty.

• When specifying the PRIMARY_ZONE for the log stream to be created, ensure that the specified zone is in the tenant's ZONE_LIST. For log streams, setting the log stream's PRIMARY_ZONE differs slightly from setting the tenant's PRIMARY_ZONE. A log stream allows only one zone to be set, for example z1 or z2, and cannot have multiple zones like a tenant, such as z1,z2, z1; z2, or RANDOM.

• It is recommended that load balancing-related parameters be set 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 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;
     

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

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

   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;
   

   Query result:

   +---------------+---------+------+----------------+----------+
   | 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. Confirm whether the parameters enable_rebalance and enable_transfer are disabled (value is 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 commands to set them 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 the log stream.

   The SQL statement for creating a log stream for a user tenant 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';
   

   Parameter descriptions:

   • unit_group_id: the ID of the target UNIT_GROUP for the log stream to be created. This option is only applicable to tenants in homogeneous zone mode. You can obtain unit_group_id by querying the oceanbase.DBA_OB_UNITS view under the system tenant.

   • unit_id_list: the list of units where the log stream will be distributed. This option is only applicable to tenants in heterogeneous zone mode. You can obtain unit_id_list by querying the oceanbase.DBA_OB_UNITS view under the system tenant; each zone can have no more than one unit.

   • zone_name: the name of the target zone. If PRIMARY_ZONE is not specified, the system will allocate it based on the balancing rules for PRIMARY_ZONE within the same UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) under the tenant.

   • tenant_name: the name of the target tenant for which the log stream will be created.

   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 specified UNIT_GROUP_ID 1001 (with corresponding 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 specified UNIT_GROUP_ID 1001 (with corresponding units 1001, 1002, and 1003), and its primary zone is z1.

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

     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 specified UNIT_LIST 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(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 specified UNIT_LIST 1001, 1002, and 1003, and its primary zone is z1.

3. Confirm the created 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
      

      Query result:

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

      According to 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;
      

      Query result:

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

      According to the query result, the status of the new log stream is NORMAL, the primary zone is z1, and it is distributed on the UNIT_LIST 1001, 1002, and 1003 (in homogeneous zone mode, corresponding to a group of units with the same UNIT_GROUP_ID). The result is consistent with the expected result, and 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'];
   
   

   Parameter descriptions:

   • unit_group_id: the ID of the target UNIT_GROUP for the log stream to be created. This parameter is only applicable to tenants in homogeneous zone mode. You can obtain the unit_group_id by querying the oceanbase.DBA_OB_UNITS view under the system tenant.

   • unit_id_list: the list of units where the log stream will be distributed. This parameter is only applicable to tenants in heterogeneous zone mode. You can obtain the unit_id_list by querying the oceanbase.DBA_OB_UNITS view under the system tenant; each zone can have no more than one unit.

   • zone_name: the name of the target zone. If PRIMARY_ZONE is not specified, the system will allocate it according to the balancing rules for PRIMARY_ZONE within the same UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) under the tenant.

   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 specified UNIT_GROUP_ID 1001 (with corresponding 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 specified UNIT_GROUP_ID 1001 (with corresponding units 1001, 1002, and 1003), and its primary zone 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 specified UNIT_LIST 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 specified UNIT_LIST 1001, 1002, and 1003, and its primary zone is z1.

3. Confirm the created log stream.

   Using MySQL-compatible mode as an example, the procedure 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
      

      Query result:

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

      According to the query result, the LS_ID of the new log stream is 1003.

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

      Query result:

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

      According to the query result, the status of the new log stream is NORMAL, the primary zone is z1, and it is distributed on the UNIT_LIST 1001, 1002, and 1003 (in homogeneous zone mode, corresponding to a group of units with the same UNIT_GROUP_ID). The result is consistent with the expected result, and the log stream was created successfully.