Modify a log stream

A log stream belongs to a log stream group. The number of log streams in each group is determined by the number of zones in the primary zone. Each zone in the primary zone's zone list can host the Leader of one log stream in the group.

You can modify log streams as needed to manually balance their distribution across UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode).

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 modifying a log stream, note the following:

• The log stream to be modified must exist and be in the NORMAL state.

• The tenant of the log stream to be modified must be in the NORMAL state.

• When modifying the UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) of a log stream in the primary tenant, ensure that no load balancing tasks are currently running for any log stream in the tenant.

• It is not recommended to modify the UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) of a log stream in a standby tenant. Standby tenants automatically adjust the UNIT_GROUP/UNIT_LIST of log streams, so manual modifications may not take effect.

• When modifying the UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) of a log stream, the target UNIT_GROUP/UNIT_LIST must be in the ACTIVE state.

• When modifying the PRIMARY_ZONE of a log stream, ensure that the new 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.

• When modifying a log stream, the tenant-level parameter enable_rebalance must be disabled (False). If it is enabled, the tenant's load balancing module may automatically adjust the log stream's PRIMARY_ZONE and UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode).

• In homogeneous zone mode, only broadcast log streams and system log streams (log stream 1) support setting UNIT_GROUP to 0.

• In heterogeneous zone mode, the UNIT_LIST specified for a user log stream must not be empty.

Step 1: Perform checks before the modification

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 status of the tenant to which the log stream belongs and ensure that the status is NORMAL.

   • System tenant

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

   • User tenant

     MySQL-compatible mode

     Oracle-compatible mode

     In MySQL-compatible mode, execute the following command to query the tenant status.

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

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

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

   Query result:

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

   According to the query result, the tenant status is NORMAL.

3. Query whether a load balancing task is being performed on the log stream. When modifying the UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) of a log stream in the primary tenant, ensure that no load balancing task is being performed on all log streams of the tenant.

   • System tenant

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

     MySQL-compatible mode

     Oracle-compatible mode

     In MySQL-compatible mode, execute the following command to query the load balancing task status of the log stream.

     obclient> SELECT count(*) AS task_cnt FROM oceanbase.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
     

     In Oracle-compatible mode, execute the following command to query the load balancing task status of the log stream.

     obclient> SELECT count(*) AS task_cnt FROM SYS.DBA_OB_BALANCE_TASKS WHERE SRC_LS = 1001 or DEST_LS=1001;
     

   Query result:

   +----------+
   | task_cnt |
   +----------+
   |        0 |
   +----------+
   1 row in set
   

   A query result of 0 indicates that no load balancing task is being performed on the log stream.

4. Query the information about the log stream to ensure that the log stream to be modified exists and is in the NORMAL state. If you want to modify a broadcast log stream, also confirm whether the specified log stream is a broadcast log stream.

   1. Query the log stream information of the tenant.

      • System tenant

        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';
        

      • User tenant

        MySQL-compatible mode

        Oracle-compatible mode

        In MySQL-compatible mode, execute the following command to query the log stream information.

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

        In Oracle-compatible mode, execute the following command to query the log stream information.

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

      Query result:

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

   2. If you want to confirm whether the log stream is a broadcast log stream, check the value of the FLAG column. If the value is DUPLICATE, the log stream is a broadcast log stream.

      • System tenant

        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;
        

      • User tenant

        MySQL-compatible mode

        Oracle-compatible mode

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

        In Oracle-compatible mode, execute 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 SYS.DBA_OB_LS WHERE LS_ID=1003;
        

5. If you want to modify the UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) of the log stream, query the unit information of the tenant and ensure that the remaining disk space on the target UNIT_GROUP/UNIT_LIST can accommodate the log stream to be modified.

   The following operations must be performed in the system tenant.

   1. Execute the following command to query the unit information of the tenant and confirm that the status of the target UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) is 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;
      

      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
      

   2. Based on the UNIT_GROUP_ID, UNIT_ID, SVR_IP, and SVR_PORT information, query the remaining disk space on the server corresponding to the target UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode).

      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;
      

      Query result:

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

   3. Query the disk space requirements of the log stream to be modified.

      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;
      

      Query result:

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

      In the query result, OCCUPY_SIZE_GB indicates the actual disk space occupied by the tablet, and REQUIRED_SIZE_GB indicates the disk space required for storing the tablet. If both OCCUPY_SIZE_GB and REQUIRED_SIZE_GB are less than the remaining disk space on the target UNIT_GROUP/UNIT_LIST, the requirement is met.

6. If you want to modify the PRIMARY_ZONE attribute of the log stream, ensure that the new zone is in the ZONE_LIST of the tenant. You can confirm the ZONE_LIST of the tenant based on the locality information of the tenant.

   • System tenant

     obclient> SELECT 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, execute the following command to query the tenant status.

     obclient> SELECT PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;
     

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

     obclient> SELECT PRIMARY_ZONE, LOCALITY FROM SYS.DBA_OB_TENANTS;
     

   Query result:

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

   In the sample result, the LOCALITY of the tenant mq_t1 is FULL{1}@z1, FULL{1}@z2, FULL{1}@z3, indicating that the ZONE_LIST of the tenant contains the zones z1, z2, and z3.

7. Check whether the value of the enable_rebalance parameter is False. If the value is True, after you modify the log stream, the load balancing module of the tenant may automatically modify the PRIMARY_ZONE and UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) attributes of the log stream.

   obclient> SHOW PARAMETERS LIKE '%enable_rebalance%';
   

   If the value is not False, execute the following command to set the value of the enable_rebalance parameter to False.

   • System tenant

     obclient> 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, based on the business situation, perform the required operation to change the log stream.

Modify a user tenant's log stream in the sys 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. Modify the log stream.

   The SQL statement to change the log stream of a user tenant in the sys 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';
   

   Parameter descriptions:

   • ls_id: the ID of the log stream to be modified.

   • unit_group_id: the ID of the target unit group for the log stream to be modified. 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: Specifies the list of target units where the log stream to be modified 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.

   • tenant_name: the name of the target tenant of the log stream.

   • When modifying the log stream, you must modify at least one attribute: UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) or PRIMARY_ZONE.

   Examples:

   Homogeneous zone mode

   Heterogeneous zone mode

   • Modify only the UNIT_GROUP of the log stream.

     Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_GROUP with ID 1002.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002 TENANT = mq_t1;
     

   • Modify only the PRIMARY_ZONE of the log stream.

     Change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
     

   • Modify both the UNIT_GROUP and PRIMARY_ZONE of the log stream.

     Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_GROUP with ID 1002, and change the primary zone of leader to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1' TENANT = mq_t1;
     

   • Modify only the UNIT_LIST of the log stream.

     Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_LIST 1004, 1005, and 1006.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006) TENANT = mq_t1;
     

   • Modify only the PRIMARY_ZONE of the log stream.

     Change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
     

   • Modify both the UNIT_LIST and PRIMARY_ZONE of the log stream.

     Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_LIST 1004, 1005, and 1006, and change the primary zone of leader to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1' TENANT = mq_t1;
     

3. Check whether the log stream was modified successfully.

   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';
   

   Query result:

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

   Compare the log stream before and after the change. If the UNIT_LIST (in homogeneous zone mode, corresponding to the group of units with the same UNIT_GROUP_ID), PRIMARY_ZONE, and other attributes match the expected values, the change was successful.

Modify the log stream of a user tenant

1. Log in 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. Modify the log stream.

   The SQL statement for changing 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'];
   

   Parameter descriptions:

   • ls_id: the ID of the log stream to be modified.

   • unit_group_id: the ID of the target unit group for the log stream to be changed. 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 target units for distributing the log stream to be changed. 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.

   • When modifying the log stream, you must modify at least one attribute: UNIT_GROUP (homogeneous zone mode) or UNIT_LIST (heterogeneous zone mode) or PRIMARY_ZONE.

   Examples:

   Homogeneous zone mode

   Heterogeneous zone mode

   • Modify only the UNIT_GROUP of the log stream.

     Move the log stream with ID 1002 to the UNIT_GROUP with ID 1002.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002;
     

   • Modify only the PRIMARY_ZONE of the log stream.

     Change the primary zone of the log stream with ID 1002 to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
     

   • Modify both the UNIT_GROUP and PRIMARY_ZONE of the log stream.

     Move the log stream with ID 1002 to the UNIT_GROUP with ID 1002, and change the primary zone of leader to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1';
     

   • Modify only the UNIT_LIST of the log stream.

     Move the log stream with ID 1002 to the UNIT_LIST 1004, 1005, and 1006.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006);
     

   • Modify only the PRIMARY_ZONE of the log stream.

     Change the primary zone of the log stream with ID 1002 to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1';
     

   • Modify both the UNIT_LIST and PRIMARY_ZONE of the log stream.

     Move the log stream with ID 1002 to the UNIT_LIST 1004, 1005, and 1006, and change the primary zone of leader to z1.

     obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1';
     

3. Check whether the log stream was modified successfully.

   Using MySQL-compatible mode as an example, the query is as follows:

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

   Query result:

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

   Compare the log stream before and after the change. If the UNIT_LIST (in homogeneous zone mode, corresponding to the group of units with the same UNIT_GROUP_ID), PRIMARY_ZONE, and other attributes match the expected values, the change was successful.