In OceanBase Database, the leader replica (leader for short) handles read and write requests in transactions. Therefore, the distribution of leaders across partitions determines how traffic is distributed across nodes.
Traffic overview
The database system handles data storage and queries in the application architecture. The read and write requests from the application are referred to as database traffic. Database traffic is divided into write traffic, strong-consistency read traffic, and weak-consistency read traffic. Write traffic and strong-consistency read traffic are handled by the leader replicas of OceanBase Database, while weak-consistency read traffic is handled by both leader and follower replicas. ODP provides the capability to route database traffic. ODP implements a simple SQL parser module that extracts the database name, table name, and hints from the SQL statement. Based on the business SQL, routing rules, and the status of the OBServer nodes, ODP selects the most suitable OBServer node to forward the request.
Primary zone
Traffic distribution is described through the primary zone. The primary zone indicates the preferred location for leader replicas. Since leader replicas handle strong-consistency read and write traffic, the primary zone determines how traffic is distributed in OceanBase Database. For example, if the primary_zone of a table t1 is set to "Zone1", the RootService will try to schedule the leader of t1 to Zone1.
Note
A replica is an object that stores data, while a primary zone is an object that represents the container for data. Therefore, the data in a container inherits the leader preference location specified by the container's primary zone attribute. OceanBase Database currently only supports tenant-level primary zones, while OceanBase Database V3.x also supports setting primary zones at the table, database, and table group levels.
A primary zone is essentially a list of zones, where each zone has a specified priority. The priority of each zone in the list is determined as follows:
When a primary zone list contains multiple zones, the zones are separated by semicolons (;), indicating a priority from high to low. zones separated by commas (,) have the same priority, indicating that traffic is distributed across multiple zones, and these zones provide services simultaneously.
For example, 'hz1,hz2;sh1,sh2;sz1' indicates that hz1 and hz2 have the same priority and a higher priority than sh1/sh2 and sz1; sh1 and sh2 have the same priority and a higher priority than sz1.
OceanBase Database currently only supports tenant-level primary zones and no longer supports setting primary zones at the table, database, or table group levels. If you do not specify the primary_zone when creating a tenant, the default value is RANDOM, indicating that all zones have the same priority.
You can view the primary zone attribute of a tenant in the PRIMARY_ZONE column of the oceanbase.DBA_OB_TENANTS view. Here is an example:
obclient(root@sys)[oceanbase]> SELECT TENANT_ID, TENANT_NAME, TENANT_TYPE, CREATE_TIME, PRIMARY_ZONE, LOCALITY, COMPATIBILITY_MODE, STATUS FROM oceanbase.DBA_OB_TENANTS;
The query result is as follows:
+-----------+-------------+-------------+----------------------------+--------------+----------------------------------------------+--------------------+--------+
| TENANT_ID | TENANT_NAME | TENANT_TYPE | CREATE_TIME | PRIMARY_ZONE | LOCALITY | COMPATIBILITY_MODE | STATUS |
+-----------+-------------+-------------+----------------------------+--------------+----------------------------------------------+--------------------+--------+
| 1 | sys | SYS | 2025-12-29 15:43:42.930290 | RANDOM | FULL{1}@zone1 | MYSQL | NORMAL |
| 1001 | META$1002 | META | 2025-12-29 15:44:48.700796 | zone1;zone2 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | MYSQL | NORMAL |
| 1002 | mysql001 | USER | 2025-12-29 15:44:48.704354 | zone1;zone2 | FULL{1}@zone1, FULL{1}@zone2, FULL{1}@zone3 | MYSQL | NORMAL |
| 1003 | META$1004 | META | 2025-12-29 15:50:35.033311 | zone1 | FULL{1}@zone1 | MYSQL | NORMAL |
| 1004 | oracle001 | USER | 2025-12-29 15:50:35.034367 | zone1 | FULL{1}@zone1 | ORACLE | NORMAL |
+-----------+-------------+-------------+----------------------------+--------------+----------------------------------------------+--------------------+--------+
5 rows in set
In the current version, log stream leaders can be distributed according to the secondary primary zone. When the highest-priority zone fails, log stream leaders are evenly distributed across the zones with the next lower priority in PRIMARY_ZONE.
Notice
If the number of zones in the second-priority PRIMARY_ZONE differs from that in the first priority, log stream leaders may not be fully distributed across the second priority.
Region attribute
In OceanBase Database, each zone has a region attribute (the REGION column in the DBA_OB_ZONES view), indicating the region where the zone is located. Each zone can be configured with only one region, but a single region can contain multiple zones. The setting of the primary zone implicitly specifies the preferred region for leader replicas. Specifically, when you set the primary zone, it has two layers of semantics:
The specified primary zone is the preferred zone for the leader replica.
The region where the specified primary zone is located is the preferred region for the leader replica.
Specifically, the leader will be prioritized to be scheduled to the zone with the highest priority. If the replica in the zone with the highest priority cannot become the leader, the leader will be prioritized to be scheduled to another zone in the same region. This ensures that business access to OceanBase Database does not cross cities.