Overview of locality management

Locality describes the distribution of replicas on the table, table group, or tenant level. The distribution information includes the number and types of replicas in each zone and region. The locality of each tenant is different and independent. Different tenants in a cluster can have different localities.

Locality syntax

Locality is described by the following syntax:

replicas{count}@location

The following table describes the elements in the preceding syntax:

Note

• You do not need to specify the table- or table group-level locality. In this case, the locality is inherited from the tenant. The locality of a tenant must be specified.

• 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.

Example:

The following example describes the locality of different tenants in a cluster that has five zones. The zones are z1-z5.

• The locality of the sys tenant: F@z1,F@z2,F@z3,F@z4,F@z5

• The locality of tenant1: F@z1,F@z2,F,R{ALL_SERVER}@z3

• The locality of tenant2: F@z1

Locality change rules

All changes made to the locality of an object must obey the following rules:

• Restrictions on ongoing change and table locality

  • When a tenant locality change is not finished, the next tenant locality change cannot be executed.

  • 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 change: F->R, R->F, and F->L.

    • 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 reduced replicas must be less than the number of replicas that remain after the change.

    • 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 increased Paxos replicas must be less than the original number of replicas before the change.

    • 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.

Locality scenarios

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

  For every tenant in a cluster, you can increase the number of replicas of each partition. For example, after you change a locality from F@z1,F@z2,F@z3 to F@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@z5 to F@z1,F@z2,F@z3,F@z4, the number of replicas of each partition decreases from five to four.

• 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@hz3 to F@hz1,F@sh1,F@sh2, the replicas in hz2 and hz3 are migrated to sh1 and sh2.