Manage service names

This topic describes the background information and version limitations of service names as well as the scenarios and methods for using their features.

Background information

OceanBase Cloud Platform (OCP) V4.2.0 and later support primary and standby tenants. However, due to the limitations of OBProxies and OceanBase Database, you must modify the database connection strings for your applications after you perform a switchover or failover between primary and standby tenants. In this case, your applications cannot be automatically routed to the new primary tenant after the switchover or failover. To resolve this issue, OceanBase Database provides an automatic routing solution. This solution requires collaboration among OCP, OBProxies, and OceanBase Database.

A service name in OceanBase Database defines a service. You can execute an SQL statement to assign the service name to a tenant. OCP ensures that tenants in the primary/standby relationship have the same service name while those not in the primary/standby relationship have different service names. The following table describes the primary and standby tenants.

The following figure shows how a business application accesses a tenant based on its service name.

OceanBase Database allows you to execute the corresponding SQL statement to create, start, stop, or delete a service name for a tenant. After you create a service name for a tenant, it is automatically started. Then, you can create a session based on the service name. If you want to delete a service name, you must stop it first.

Version limitations

OCP, OceanBase Database, and OBProxies must meet the following version requirements:

• OCP: [V4.3.1, +∞)
• OceanBase Database: V4.2.1.9, [V4.2.4.0, V4.3.0.0), or [V4.3.3.0, +∞)
• OBProxies: [V4.3.1.0, +∞)

Features

Automatic routing

Automatic routing is available only when the following two conditions are met:

1. The primary and standby tenants have the same service name.
2. The OceanBase clusters to which the primary and standby tenants belong are associated with the same OBProxy cluster. The OBProxy cluster can automatically route requests to the new primary tenant after a switchover.

Specify a service name

After you specify a service name for a tenant in OCP, you can connect to the tenant by using the service name.

obclient -hIP -PPORT -uroot@SERVICE_NAME:service1 -pPASSWORD

Here, SERVICE_NAME is a keyword. OCP allows you to specify a service name for a tenant by using the following methods:

• Specify a service name during tenant creation: You can specify a service name for a tenant when you create the tenant.

  

• Add a service name on the tenant details page: You can add a service name for a tenant on its details page. You can also edit or delete an existing service name.

  

• Synchronize a service name: OCP synchronizes tenant information from OceanBase Database once every minute. It compares the tenant information in the internal tables and views of OceanBase Database with the metadata in OCP and updates the metadata accordingly. In this case, the service name of the tenant is also updated.

Use service names in switchover scenarios

Switchover

The following two items are added to the switchover precheck:

1. The primary and standby tenants have no service name or have the same service name.
2. The service name of the primary and standby tenants is different from those of other tenants without the primary/standby relationship.

If the OceanBase cluster where the standby tenant resides is not bound to the OBProxy cluster associated with the OceanBase cluster where the primary tenant resides, OCP generates an alert before the switchover to notify you that automatic routing may fail after the switchover, but does not forcibly prohibits the switchover. The switchover does not change the service name of the tenants. Business applications can access the tenants through the OBProxy by using the [USERNAME]@SERVICE_NAME:[serviceName] setting without modifying the connection string.

Failover

During a failover, OceanBase Database deletes the service name of the new primary tenant. Therefore, business applications cannot connect to the new primary tenant based on the service name, and you must modify the connection string. To avoid modification of the connection string, OCP allows you to choose whether to specify a service name for the new primary tenant before the failover. This is an optional operation. You can retain the original service name for the new primary tenant. In this case, business applications can directly access the new primary tenant after the failover without modifying the connection string.

The following figure shows the technical mechanism. After a failover is performed on tenant B, the original primary/standby relationship is divided into two parts: (tenants B and C) and (tenants A, D, and E). The service names of tenants A, C, D, and E are still ServiceA, and the service name of tenant B is deleted. To allow business applications to access tenant B without modifying the connection string, OCP resets the service name of tenant B to ServiceA at the end of the failover process, and sets the service names of tenant A, D, and E to the INVALID state. The INVALID state is a concept in OCP. A service name in this state is masked from the OBProxy to prevent the OBProxy from accessing the original primary tenant. The config server of OCP returns only the tenant whose service name is not in the INVALID state.

Decoupling between primary and standby tenants

In OceanBase Database, you can use the same command to decouple a standby tenant from its primary tenant and perform a failover on the standby tenant. However, they require two different operations in OCP. In the primary/standby relationship shown in the following figure, the original primary tenant is in the normal state. After decoupling, OceanBase Database automatically deletes the service name of tenant B, and OCP deletes the service name of tenant C. This prevents tenants not in the primary/standby relationship from using the same service name.

Adaptation to the multi-cluster mode

When the primary and standby OceanBase clusters are deployed in the primary and standby OCP clusters respectively, both the primary and standby OCP clusters can return the RootService lists of the primary and standby OceanBase clusters. This way, you do not need to modify the connection strings for applications after a switchover is performed between the primary and standby OceanBase clusters. The following figure shows the technical mechanism.

After the primary or standby OceanBase cluster is associated with an OBProxy, the OBProxy can obtain the RootService lists of both the primary and standby OceanBase clusters if the following conditions are met:

1. The cluster names of the primary and standby OceanBase clusters are the same. This way, the OBProxy can request the RootService lists by using one cluster name.
2. The proxyro@sys passwords of the primary and standby OceanBase clusters are the same. This way, the OBProxy can access both clusters by using the same password after it is associated with either of the clusters.

To provide features similar to those of the primary and standby OceanBase clusters in multi-cluster mode, OCP V4.3.2 and later allow you to associate OceanBase clusters with OBProxies across OCP clusters.

1. You can associate an OceanBase cluster with a remote OBProxy cluster. Remote OBProxy clusters are displayed in a drop-down list.

   

2. You can associate an OBProxy cluster with a remote OceanBase cluster. Remote OceanBase clusters are displayed in a drop-down list.

   

3. You can associate an OceanBase cluster with a remote OBProxy cluster when you create the OceanBase cluster. Remote OBProxy clusters are displayed in a drop-down list.

   

After you associate a local OBProxy cluster with a remote OceanBase cluster, you can access tenants in the remote OceanBase cluster through a local OBProxy.