Locality 描述了表、表组或租户下副本的分布情况。这里的副本分布情况指在 Zone 或 Region 上包含的副本的数量以及副本的类型，不同的租户在同一个集群内可以配置不同的 Locality 并且彼此之间相互独立不受影响。

Locality 语义

Locality 基本语法结构型为如下所示：

replicas{量词}@location

下述表格展示了语法中各元素的意义：

说明

• 表和表组的 Locality 可以为空，表示继承自所属租户。租户的 Locality 不可以为空。

• 当租户的 Locality 发生变更时，在该租户下，所有 Locality 为空的表的副本的分布情况也会随之变化。Locality 不为空的表在租户的 Locality 变更时，其对应副本的分布情况不会改变。

示例:

下述示例展示了在一个拥有五个 Zone（z1~z5）的 OceanBase 集群中，可以容纳不同 Locality 的多个租户和它们的 Locality 情况：

• sys tenant 的 Locality： F@z1,F@z2,F@z3,F@z4,F@z5

• tenant1 的 Locality： F@z1,F@z2,F,R{ALL_SERVER}@z3

• tenant2 的 Locality： F@z1

Locality 变更规则

• 在旧的一轮租户 Locality 没有完成变更时，新一轮的租户 Locality 变更不允许被执行。

• 当租户下 Locality 不为空的表的变更没有完成时，租户 Locality 变更不允许执行。

• 租户的 Locality 变更没有发起时，Locality 不为空的表的 Locality 变更不允许执行。

• 不允许直接增加或删除 Region Locality。

  例如， Locality F@zone增加为 F@zone,X{*}@region 或 Locality F@zone,X{*}@region删除为 F@zone都是不被允许（其中 X{*} 表示任意类型任意数量的副本）。

• Region 不允许增加或删除 Paxos 副本，但允许转换 Paxos 副本，每次允许转换一个。

  例如，从 Locality F{2},L{1}@region 转换为 F{1},L{2}@region是允许的。但是从 Locality F{2},L{1}@region 删除为 F{2}@region 是不允许的。

• 对于 Zone Locality，每次仅允许增加、删除或修改一个 Zone 内的一个 Paxos 副本。

  例如，允许将 Locality F@zone1 增加为 F@zone1,L@zone2，将 Locality F@zone1,L@zone2 删除为 F@zone1或是将 Locality F@zone1,L@zone2 修改为 F@zone1,F@zone2。

• 为了解决 Region Locality 的搬迁问题，OceanBase 数据库中允许 Zone 和 Region 之间互相变更。

  例如，允许将 Locality F{2},L@region 变更为 F@zone1,F@zone2,L@zone3，或是将 Locality F@zone1,F@zone2,L@zone3 变更为 F{2},L@region，需要注意的是，这里 Paxos 副本的副本数前后必须相等。

注意

• 以上几种变更不能同时发生，每次仅能发生一个。

• non_paxos 副本可以随上述变化一并发生，并且不限制数量。

Locality 应用场景

Locality 的设置通常用于集群的副本数升级/降级和集群的搬迁：

• 集群副本数升级

  以租户为粒度，对集群中的每一个租户，增加租户下 Partition 的副本数。例如，将 Locality 由 F@z1,F@z2,F@z3变更为 F@z1,F@z2,F@z3,F@z4,F@z5，租户从 3 副本变为 5 副本。

• 集群副本数降级

  以租户为粒度，对集群内的每一个租户减少其中 Partition 的副本数。例如，将 Locality 由 F@z1,F@z2,F@z3,F@z4,F@z5 变更为 F@z1,F@z2,F@z3,F@z4，租户从 5 副本变为 4 副本。

• 集群搬迁

  以租户为粒度，对集群内的每一个租户通过若干次 Locality 变更。比如，将 Locality 从 F@hz1,F@hz2,F@hz3变更为 F@hz1,F@sh1,F@sh2即代表将原集群中属于杭州的两个 Zone 迁到上海。