This topic describes how to modify the locality of a tenant.
Application scenarios
You can modify the locality of a tenant to increase or decrease the number of replicas for the tenant or adjust the distribution of replicas.
Increase the number of replicas for a tenant
You can increase the number of replicas for a tenant in the cluster. Only one replica can be added at a time. For example, if you want to change a tenant from 1 replica to 2 replicas, see Add a replica.
Reduce the number of replicas for a tenant
You can reduce the number of replicas for a tenant in the cluster. For example, if you want to change a tenant from 2 replicas to 1 replica, see Reduce replicas.
Adjust the distribution of replicas for a tenant
You can modify the locality of a tenant in the cluster several times to adjust the distribution of replicas across IDCs. For example, if the original locality of a tenant is
F@z1,F@z2and IDC z2 expires and the replica must be migrated to z3, the locality must be changed toF@z1,F@z3. Specifically, the locality must be changed first fromF@z1,F@z2toF@z1,F@z2,F@z3, and then fromF@z1,F@z2,F@z3toF@z1,F@z3. For more information, see Adjust the distribution of replicas.
Prerequisites
Before you modify the locality of a tenant, verify the resource allocation on each node in the target zone. If the node resources in the target zone are insufficient to accommodate the resource units required by the tenant, the locality cannot be changed.
For more information about the resource allocation on each node in a zone, see View tenant and resource information.
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 zone2 with zone3, you must add zone3 first and then remove zone2.
We recommend that you modify the primary zone before you modify the locality.
Here are some examples:
Assume that zone2 is a primary zone with the highest priority. When you remove zone2, read and write services of the tenant are affected during locality modification.
Assume that the primary zone is set to RANDOM when you add zone3. After zone3 is added, it also provides read and write services.
Modifying the locality of a tenant involves changing Paxos members and copying data. You must evaluate the impact on system stability and performance. Regarding changes of Paxos members, evaluate the impact on the tolerance to node failures. Regarding changes of replica distribution, evaluate the impact on the service level agreement (SLA) design for IDC and city-wide failures in the deployment architecture. Regarding data copying, observe the impact on other tenants on the same node. We recommend that you copy data during off-peak hours and prepare a contingency plan in advance.
Locality modification must not reduce the expected tolerance to node failures. For example, in a two-replica cluster where an IDC is replaced, you must add a replica and then remove a replica to avoid reducing the expected tolerance to node failures during locality modification. Theoretically, a single-replica failure during locality modification does not affect service continuity. If service continuity is affected, immediately recover the availability of the database. We recommend that you try to rectify hardware faults first.
Procedure
The following example describes how to modify the locality of the mq_t1 tenant from FULL{1}@sa128_obv4_1 to F{1}@sa128_obv4_1,F{1}@sa128_obv4_2.
Log in to the
systenant of the cluster as therootuser.obclient -h172.30.xxx.xxx -P2883 -uroot@sys#obdemo -pxxxx -AAccess the database named
oceanbase.obclient>use oceanbase;View the locality before the modification.
obclient> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;The query result is as follows:
+-----------+-------------+-------------+---------------------------+--------------------------------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | +-----------+-------------+-------------+---------------------------+--------------------------------------------+ | 1 | sys | SYS | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | | 1001 | META$1002 | META | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | | 1002 | midas0_3790 | USER | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | | 1003 | META$1004 | META | sa128_obv4_1 | FULL{1}@sa128_obv4_1 | | 1004 | mq_t1 | USER | sa128_obv4_1 | FULL{1}@sa128_obv4_1 | +-----------+-------------+-------------+---------------------------+--------------------------------------------+ 5 rows in setModify the locality of the
mq_t1tenant.obclient>ALTER TENANT mq_t1 locality="F{1}@sa128_obv4_1,F{1}@sa128_obv4_2";View the execution status of the locality change job.
obclient> SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE JOB_TYPE = 'ALTER_TENANT_LOCALITY';The query result is as follows:
+--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+----------------------------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ | 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 | 0 | 100 | 2023-01-05 19:33:46.730319 | 2023-01-05 19:33:46.920111 | 1002 | ALTER TENANT mq_t1 locality="F{1}@sa128_obv4_1,F{1}@sa128_obv4_2" | FULL{1}@sa128_obv4_1 | xx.xx.xx.xx | 2882 | +--------+-----------------------+------------+-------------+----------+----------------------------+----------------------------+-----------+----------------------------------------------------------------------------------------------------+---------------------------------------------+----------------+-------------+ 1 row in setIf the value of
JOB_STATUSisSUCCESS, the locality change job is successful.View the locality after the modification.
obclient> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, PRIMARY_ZONE, LOCALITY FROM oceanbase.DBA_OB_TENANTS;The query result is as follows:
+-----------+-------------+-------------+----------------------------------------+------------------------------------------------------------------+--------------------+ | TENANT_ID | TENANT_NAME | TENANT_TYPE | PRIMARY_ZONE | LOCALITY | PREVIOUS_LOCALITY | +-----------+-------------+-------------+----------------------------------------+------------------------------------------------------------------+--------------------+ | 1 | sys | SYS | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | null | | 1001 | META$1002 | META | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | null | | 1002 | midas0_3790 | USER | sa128_obv4_2;sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | null | | 1003 | META$1004 | META | sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | null | | 1004 | mq_t1 | USER | sa128_obv4_1 | FULL{1}@sa128_obv4_1, FULL{1}@sa128_obv4_2 | null | +-----------+-------------+-------------+----------------------------------------+------------------------------------------------------------------+--------------------+ 5 rows in setThe query result shows that the locality of
mq_t1has been changed toF{1}@sa128_obv4_1,F{1}@sa128_obv4_2. If thePREVIOUS_LOCALITYcolumn is empty, the change is successful. If thePREVIOUS_LOCALITYcolumn is not empty, the change is in progress.