This topic describes how to adjust the distribution of replicas in a tenant by modifying the locality of the tenant in a cluster.
For more information about how to modify the locality, see Modify locality.
Prerequisites
Before you modify the locality of a tenant, check the status of the resource units and the resource pool in the target zone. If OBServer nodes in the target zone do not have sufficient resources to accommodate the new resource units of the tenant, the locality cannot be changed.
For more information about how to check the status of the resource units and resource pool in a zone, see View resource information of a cluster.
Considerations
The locality of a tenant must be specified.
Modifying the locality of a tenant also changes the distribution of table replicas for the tenant.
If a tenant locality modification is not finished, the next tenant locality modification cannot be performed.
You can perform only one action at a time when you modify the locality. For example, if you want to replace zone3 with zone4, you must add zone4 first and then remove zone3.
After you add a replica to a tenant, the locality of the tenant does not match the primary zone of the tenant. If the new zone is involved in leader switchover, you must modify the primary zone. If the new zone is not involved in leader switchover, you do not need to modify the primary zone.
Procedure
The following example describes how to modify the locality of the mysql001 tenant from FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 to FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4.
Log on to the sys tenant of the cluster as the root user.
obclient -h172.30.xxx.xxx -P2883 -uroot@sys -pxxxx -AAccess the database named
oceanbase.obclient>use oceanbase;View the locality of the
mysql001tenant.obclient> SELECT TENANT_ID,TENANT_NAME,TENANT_TYPE,PRIMARY_ZONE,LOCALITY FROM oceanbase.DBA_OB_TENANTS; +-----------+-------------+-------------+-------------------+---------------------------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | +-----------+-------------+-------------+-------------------+---------------------------------------------+ | 1 | sys | SYS | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | | 1001 | META$1002 | META | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | | 1002 | mysql001 | USER | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | +-----------+-------------+-------------+-------------------+---------------------------------------------+ The query result shows that the 'mysql001' tenant has a full-featured replica in each of Zone 1, Zone 2, and Zone 3.Modify the locality of the
mysql001tenant to add a replica in zone4.obclient>ALTER TENANT mysql001 locality="FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3, FULL{1}@zone4";View the execution status of the locality modification job.
obclient>SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE = 'ALTER_TENANT_LOCALITY'; +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ | JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT | +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ | 1 | ALTER_TENANT_LOCALITY | SUCCESS | NULL | 0 | 2023-01-05 19:38:38.416011 | 2023-01-05 19:38:38.416011 | 1002 | ALTER TENANT mysql001 locality='FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3, FULL{1}@zone4' | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | xx.xx.xx.237 | 2882 | +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+If the value of
JOB_STATUSisSUCCESS, the locality modification job is executed successfully.Modify the locality of the
mysql001tenant to remove the replica from zone3.obclient>ALTER TENANT mysql001 locality="FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4";View the execution status of the locality modification job.
obclient>SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE = 'ALTER_TENANT_LOCALITY'; +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ | JOB_ID | JOB_TYPE | JOB_STATUS | RESULT_CODE | PROGRESS | START_TIME | MODIFY_TIME | TENANT_ID | SQL_TEXT | EXTRA_INFO | RS_SVR_IP | RS_SVR_PORT | +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ | 1 | ALTER_TENANT_LOCALITY | SUCCESS | NULL | 0 | 2023-01-05 19:38:38.416011 | 2023-01-05 19:38:38.416011 | 1002 | ALTER TENANT mysql001 locality='FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4' | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3, FULL{1}@zone4 | xx.xx.xx.237 | 2882 | +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+If the value of
JOB_STATUSisSUCCESS, the locality modification job is successful.View the modified locality of the
mysql001tenant.obclient> SELECT TENANT_ID,TENANT_NAME,TENANT_TYPE,PRIMARY_ZONE,LOCALITY FROM oceanbase.DBA_OB_TENANTS; +-----------+-------------+-------------+-------------------+---------------------------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | +-----------+-------------+-------------+-------------------+---------------------------------------------+ | 1 | sys | SYS | zone1;zone2;zone3 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | | 1001 | META$1002 | META | zone1;zone2 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4 | | 1002 | mysql001 | USER | zone1;zone2 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4 | +-----------+-------------+-------------+-------------------+---------------------------------------------+
The query results in step 3 and step 8 show that the locality of the mysql001 tenant is changed from FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 to FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone4, and the mysql001 tenant has a full-featured replica in each of zone1, zone2, and zone4.
After you add the replica in step 4, the locality of the tenant does not match the primary zone of the tenant. If the new zone is involved in leader switchover, you must modify the primary zone.
If the new zone is not involved in leader switchover, you do not need to modify the primary zone.