Locality describes the distribution of replicas at the table or tenant level. The distribution information refers to the number and types of replicas in each zone. The locality of each tenant is different and independent. Different tenants in a cluster can have different localities.
Syntax
Locality is described by the following syntax:
replicas{count}@location
The following table describes elements in the syntax.
| Element | Description |
|---|---|
| replicas | The type of the replica. For more information, see Replica types. The value of replicas is the name of the replica type. Both full names and abbreviations are supported. You can view the supported replica type names in the Name (abbreviation) row of the table that describes the replica types in the overview of replicas. |
| location | Represents the location of the replica. It contains a collection of values that are known to the system. The value of location is the name of the zone. For more information about how to query zone names at the cluster or tenant level, see View cluster topology. |
| count | If this parameter is not specified, only one replica is available. {n} specifies N replicas. The special count {all_server} specifies that the number of replicas is the same as the number of available OBServers. A partition can have at most one full-featured replica or one log-only replica in a zone. These replicas are part of the Paxos replica group. A partition can have several read-only replicas in the same zone. |
Note
You do not need to specify the table- or table group-level locality. In this case, the locality is inherited from the tenant. You must specify the locality of the tenant.
When the locality of a tenant changes, if the locality of a table in the tenant is unspecified, the distribution of the table replicas also changes. When the locality of a tenant changes, if the locality of a table in the tenant is specified, the distribution of the table replicas does not change.
The following example describes the locality of different tenants in an OceanBase cluster that has five zones. The zones are z1 to z5.
The locality of the sys tenant:
F@z1,F@z2,F@z3,F@z4,F@z5The locality of tenant1:
F@z1,F@z2,F,R{ALL_SERVER}@z3The locality of tenant2:
F@z1
Locality change rules
All changes made to the locality of an object must comply with the following rules:
Restrictions on tenant/table locality changes
When a tenant locality change is not finished, the next tenant locality change cannot be performed.
The zones in a table-level locality must be a subset of the zones in a tenant-level locality.
Paxos replica number changing rules
OceanBase supports three types of locality changes: F->R, R->F, and F->L.
F->R
F->R refers to the change from a full-featured replica to a read-only replica. This operation reduces the number of Paxos replicas. The number of replicas reduced after each change must be less than the number of replicas that remain.
R->F
R->F refers to the change from a read-only replica to a full-featured replica. This operation increases the number of Paxos replicas. The number of Paxos replicas increased after each change must be less than the original number of Paxos replicas before the change.
F->L
F->L refers to the change from a full-featured replica to a log-only replica. This operation does not change the number of Paxos replicas. The F->L change and an operation that changes the number of Paxos replicas cannot be performed at the same time.
An operation that does not change the Paxos replicas can be performed simultaneously with the preceding operations. In this case, the number of replicas to be changed is unlimited.
Application scenarios of locality
Locality settings are often used when you want to increase or decrease the number of replicas in a cluster or migrate a cluster.
Increase the number of replicas in a cluster
You can increase the number of partition replicas in each tenant in a cluster. For example, after you change a locality from
F@z1,F@z2,F@z3toF@z1,F@z2,F@z3,F@z4,F@z5, the number of replicas of each partition in the tenant increases from three to five.Decrease the number of replicas in a cluster
You can decrease the number of partition replicas in each tenant in a cluster. For example, after you change a locality from
F@z1,F@z2,F@z3,F@z4,F@z5toF@z1,F@z2,F@z3, the number of replicas of each partition decreases from five to three.Cluster migration
You can change the locality of each tenant in a cluster. For example, after you change a locality from
F@hz1,F@hz2,F@hz3toF@hz1,F@sh1,F@sh2, two zones in Hangzhou are relocated to Shanghai. hz and sh indicate the Hangzhou and Shanghai regions.