Modify a log stream|V4.6.0|OceanBase Database| docs|Distributed Database

Modify a log stream

Last Updated：2026-05-07 11:26:24 Updated

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 both homogeneous and heterogeneous zone modes for tenants. Specifically:

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 and heterogeneous zone modes, see Data distribution.

Considerations

Before modifying a log stream, note the following:

The log stream must exist and be in the NORMAL state.
The tenant of the log stream must also be in the NORMAL state.
When modifying the UNIT_GROUP (for homogeneous zones) or UNIT_LIST (for heterogeneous zones) 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 (for homogeneous zones) or UNIT_LIST (for heterogeneous zones) of a log stream in a standby tenant, as standby tenants automatically adjust this attribute. Manual modifications may not take effect.
When changing the UNIT_GROUP (for homogeneous zones) or UNIT_LIST (for heterogeneous zones), the target UNIT_GROUP or UNIT_LIST must be in the ACTIVE state.
When changing the PRIMARY_ZONE of a log stream, ensure the new zone is included in the tenant’s ZONE_LIST. For log streams, only a single zone (for example, z1 or z2) can be set as the PRIMARY_ZONE. Multiple zones (for example, z1,z2, z1; z2) or RANDOM are not allowed.
Before modifying a log stream, the tenant-level parameter enable_rebalance must be disabled (False). If enabled, the tenant's load balancing module may automatically adjust the log stream's PRIMARY_ZONE and UNIT_GROUP (for homogeneous zones) or UNIT_LIST (for heterogeneous zones).
In homogeneous zone mode, only broadcast log streams and system log streams (Log Stream 1) support setting the UNIT_GROUP to 0.
In heterogeneous zone mode, the UNIT_LIST of user log streams cannot be empty.

Step 1: Perform checks before the modification

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

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

The query result is as follows:

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

The tenant status is NORMAL.

Query whether a load balancing task is being performed on the log stream. If you modify the UNIT_GROUP attribute 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(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
  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;
The query result is as follows:
```
+----------+
| task_cnt |
+----------+
|        0 |
+----------+
1 row in set
```
The query result is 0, indicating that no load balancing task is being performed on the log stream.

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.

Query the log stream information.

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

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

The query result is as follows:

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

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(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=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;

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

The following operations must be performed in the system tenant.

Execute the following command to query the unit information of the tenant and confirm that the status of the target UNIT_GROUP (in homogeneous zone mode) or UNIT_LIST (in heterogeneous zone mode) is ACTIVE.

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

Based on the UNIT_GROUP_ID, SVR_IP, and SVR_PORT information, query the remaining disk space on the server corresponding to the target UNIT_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.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

Query the disk space requirements of 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.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.

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(root@sys)[oceanbase]> 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;
The query result is as follows:
```
+--------------+------------------------------------+
| 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.
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(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, based on the business situation, perform the required operation to change the log stream.

Modify the log stream of a user tenant

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
```
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';
```
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 the homogeneous zone mode. You can obtain the unit_group_id by querying the oceanbase.DBA_OB_UNITS view in the sys tenant.
- unit_id_list: the IDs of the target units to which the log stream is to be modified. This parameter is applicable only to tenants in the heterogeneous zone mode. You can obtain the unit_id_list by querying the oceanbase.DBA_OB_UNITS view in the sys tenant. Each zone can have 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 you modify the log stream, you must modify at least one attribute of the log stream: UNIT_GROUP (homogeneous zone mode) / UNIT_LIST (heterogeneous zone mode) or PRIMARY_ZONE.
Here are some examples:
Homogeneous zone mode

Heterogeneous zone mode
- Modify only the UNIT_GROUP attribute of the log stream.
  
  Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_GROUP of log stream 1002.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002 TENANT = mq_t1;
- Modify only the PRIMARY_ZONE attribute of the log stream.
  
  Change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- Modify both the UNIT_GROUP and PRIMARY_ZONE attributes of the log stream.
  
  Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_GROUP of log stream 1002, and change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002, PRIMARY_ZONE 'z1' TENANT = mq_t1;
- Modify only the UNIT_LIST attribute of the log stream.
  
  Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_LIST of units 1004, 1005, and 1006.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006) TENANT = mq_t1;
- Modify only the PRIMARY_ZONE attribute of the log stream.
  
  Change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 PRIMARY_ZONE 'z1' TENANT = mq_t1;
- Modify both the UNIT_LIST and PRIMARY_ZONE attributes of the log stream.
  
  Change the location of log stream 1002 of the mq_t1 tenant to the UNIT_LIST of units 1004, 1005, and 1006, and change the primary zone of leader of log stream 1002 of the mq_t1 tenant to z1.
  
  obclient(root@sys)[oceanbase]> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1' TENANT = mq_t1;

Check whether the log stream is 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';

The query result is as follows:

+-------+--------------+-------------+----------------+
| 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 (a group of units with the same UNIT_GROUP_ID in homogeneous zone mode) and PRIMARY_ZONE attributes of the log stream are consistent with the expected values, the change is successful.

Modify the log stream of a user tenant

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
```
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'];
```
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 of the log stream to be modified. This parameter applies 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 target Units of the log stream to be modified. This parameter applies 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 contain at most one Unit.
- zone_name: the name of the target zone.
- When you change the log stream, you must modify at least one attribute of the log stream: UNIT_GROUP (for homogeneous zone mode) or UNIT_LIST (for heterogeneous zone mode), or PRIMARY_ZONE.
Here are some examples:
Homogeneous zone mode

Heterogeneous Zone mode
- Modify only the UNIT_GROUP attribute of the log stream.
  
  Move the log stream with ID 1002 to the UNIT_GROUP of the same ID.
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_GROUP 1002;
- Modify only the PRIMARY_ZONE attribute 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 attributes of the log stream.
  
  Move the log stream with ID 1002 to the UNIT_GROUP of the same ID, and change the primary zone of the log stream 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 position of the 1002 log stream to the UNIT_LIST of 1004, 1005, and 1006.
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006);
- Modify only the PRIMARY_ZONE of the log stream.
  
  Set the first priority of the leader of the 1002 log stream 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 position of the 1002 log stream to the UNIT_LIST of 1004, 1005, and 1006, and set the first priority of the leader of the log stream to z1.
  
  obclient> ALTER SYSTEM MODIFY LS 1002 UNIT_LIST (1004,1005,1006), PRIMARY_ZONE 'z1';

Check whether the log stream is changed.

For example, in MySQL mode, the query result 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';

The query result is as follows:

+-------+--------------+-------------+----------------+
| 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, a group of units with the same UNIT_GROUP_ID) and PRIMARY_ZONE attributes of the log stream are as expected, the change is successful.

OceanBase

Customer Stories

Documentation

Modify a log stream

Background information

Considerations

Step 1: Perform checks before the modification

Step 2: Modify the log stream

Modify the log stream of a user tenant

Modify the log stream of a user tenant