Specify the configuration file
OceanBase Call Interface (OBCI) supports driver load balancing for a client to select an appropriate proxy for connecting to the database.
To use load balancing, you need to set connection parameters and backend proxy IP addresses in the configuration file of OBCI. Also, you need to set the name of the configuration file in the OBCI_TNS_FILE environment variable.
## Set the name of the configuration file to obci_tnsnames.ora.
export OBCI_TNS_FILE=./obci_tnsnames.ora
To provide the load balancing feature, the format of OBCI configuration file is compatible with that of OCI. Information about the configuration file of Oracle Call Interface (OCI):
The configuration file of OCI is stored under the directory that is specified by the TNS_ADMIN environment variable, or the ORACLE_HOME/network/admin directory.
The configuration file of OCI is always named as tnsnames.ora.
You can specify the configuration file through three environment variables: OBCI_TNS_FILE, TNS_ADMIN, and ORACLE_HOME. The priority of the three environment variables is as following:
OBCI_TNS_FILE: first priority.
TNS_ADMIN: second priority. This variable is queried when the OBCI_TNS_FILE variable is not specified.
ORACLE_HOME: third priority. This variable is queried when the preceding two variables are not specified.
Note
We recommend that you use the OBCI_TNS_FILE variable to specify the configuration file.
Description of the configuration file
Configuration example
## Load balancing configuration
obci_load_balance=
(DESCRIPTION=
(OBLB=ON)
(OBLB_RETRY_ALL_DOWNS=120)
(OBLB_RETRY_TIMEOUT=200000)
(OBLB_GROUP_STRATEGY=ROTATION)
(OBLB_BLACKLIST=
(REMOVE_STRATEGY=
(NAME=timeout)(TIMEOUT=1000)
)
(APPEND_STRATEGY=
(NAME=retryDuration)(RETRY_TIMES=20)(DURATION=1000)
)
)
(ADDRESS_LIST=
(OBLB_STRATEGY=SERVERAFFINITY)
(ADDRESS=(PROTOCOL=tcp)(HOST=11.xxx.xxx.1)(PORT=10001)(WEIGHT=1))
(ADDRESS=(PROTOCOL=tcp)(HOST=11.xxx.xxx.1)(PORT=10000)(WEIGHT=10)))
(ADDRESS_LIST=
(OBLB_STRATEGY=ROTATION)
(ADDRESS=(PROTOCOL=tcp)(HOST=11.xxx.xxx.1)(PORT=1031)(WEIGHT=10))
(ADDRESS=(PROTOCOL=tcp)(HOST=11.xxx.xxx.1)(PORT=10002)(WEIGHT=10)))
(ADDRESS_LIST=
(ADDRESS=(PROTOCOL=tcp)(HOST=11.xxx.xxx.1)(PORT=10003)(WEIGHT=10)))
(CONNECT_DATA=(SERVICE_NAME=TEST)))
## Normal configuration
normal=
(DESCRIPTION=
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL=TCP)(HOST=11.xxx.xxx.1)(PORT=1031)))
(CONNECT_DATA=
(SID=TEST)))
## Special configuration, which is not required for load balancing, but can be specified for compatibility with previous capabilities
TestExtraInfo=
(DESCRIPTION=
(ADDRESS_LIST=
(ADDRESS = (PROTOCOL=TCP)(HOST=11.xxx.xxx.1)(PORT=1031)))
(CONNECT_DATA=
(SID=TEST)(OB_MODE=1)(OB_USER_EXTRA_INFO=@xyoracle)))
Normal configuration
As shown in the preceding configuration example, you can specify only an IP address, a port number, and an SID in the normal configuration. You can concatenate the IP address, port number, and SID into a connection string, which can be used with the account and password to log on to the corresponding database.
Example:
## The connection string obtained based on the preceding normal configuration
dblink: 11.xxx.xxx.1:1031/TEST
Load balancing configuration
Notice
Keys and values in the configuration file are case-insensitive. We recommend that you use the obci_dblink_check file, which will be described later, to check whether the configuration file is as expected.
DESCRIPTION keys
| Key | Description | Value | Remarks |
|---|---|---|---|
| OBLB | Specifies whether to enable load balancing. |
|
If load balancing is disabled, all keys that start with OBLB are invalid, and the first address is used to connect to the proxy or OBServer. |
| OBLB_RETRY_ALL_DOWNS | The total number of connection attempts allowed. | Default value: 120. We recommend that you set the key as needed. | During load balancing, each connection attempt is counted and this key specifies the total number of connection attempts allowed. If you set this key to 10, the client attempts no more than 10 times to connect to the database based on the load balancing strategy of OBCI. The IP address is selected based on the load balancing strategy at each attempt until the specified number of attempts is reached or the connection succeeds. |
| OBLB_RETRY_TIMEOUT | The total timeout period for all connection attempts. | Default value: 10000ms | During load balancing, the client keeps attempting to connect to the backend proxy. This key specifies the total timeout period for all attempts and is checked before each attempt. If the timeout period is reached, an error will be reported. |
| OBLB_CONNECT_TIMEOUT | The timeout period for one connection attempt. | Default value: 0s, which indicates that the connection attempt will not time out until it succeeds. | This key specifies the timeout period for an attempt to build a TCP connection with the backend. |
| OBLB_GROUP_STRATEGY | The proxy group selection strategy for load balancing. | Default value: ROTATION, which is also the only value. | The OBCI load balancing feature allows you to configure multiple proxy groups. OBCI can select a preferential group based on the strategy for the client to try to build the connection. |
OBLB_BLACKLIST keys
| Key | Description | Value |
|---|---|---|
| REMOVE_STRATEGY | The unblacklisting strategy for removing an IP address from the blacklist. | You can define an unblacklisting strategy by specifying NAME with relevant attributes. |
| NAME | The name of an unblacklisting or blacklisting strategy. | You can specify the name based on the strategy. For more information, see NAME. |
| TIMEOUT | An attribute under the TIMEOUT strategy. It indicates the period of time after which an IP address can be removed from the blacklist. | A number in milliseconds. |
| APPEND_STRATEGY | The blacklisting strategy for adding an IP address to the blacklist. | You can define a blacklisting strategy by specifying NAME with relevant attributes. |
| RETRYTIMES | An attribute under the RetryDuration strategy. An IP address will be added to the blacklist when the client failed to use the IP address to connect to the database after the number of attempts specified by this attribute within the period specified by DURATION. | A number. Default value: 1 |
| DURATION | An attribute under the RetryDuration strategy. It indicates a period of time. | A number. Default value: 10ms. |
NAME
NAME specifies the name of an unblacklisting or a blacklisting strategy. The following table describes the valid values of NAME for the two types of strategies.
| Strategy type | Valid value | Description |
|---|---|---|
| Unblacklisting strategy | TIMEOUT | When NAME is set to this value, a blacklisted IP address will be removed from the blacklist upon load balancing after the period, such as 10 ms, specified by the TIMEOUT attribute. |
| Blacklisting strategy | RetryDuration | When NAME is set to this value, you need to specify the DURATION and RETRYTIMES attributes for the strategy. If an IP address cannot be used to connect to the database after the number of attempts specified by RETRYTIMES within the period specified by DURATION, the IP address will be blacklisted. |
| Blacklisting strategy | NORMAL | When NAME is set to this value, the strategy has no other attributes and an IP address will be blacklisted if it cannot be used to connect to the database. |
ADDRESS_LIST and ADDRESS keys
| Key | Description | Value |
|---|---|---|
| OBLB_STRATEGY | The load balancing strategy for the address group. |
|
| PROTOCOL | The connection protocol. This key is inherited from the Oracle TNS file and has no practical effect. | |
| HOST | The IP address. | The IP address of the backend proxy or OBServer. |
| PORT | The port number. | A number. |
| WEIGHT | The weight of an IP address, which is used in the strategy for selecting the destination IP address in weighted random mode. | 1 |
CONNECT_DATA keys
| Key | Description | Value | Remarks |
|---|---|---|---|
| SERVICE_NAME or SID | Both of the keys indicate the database. They are inherited from the Oracle TNS file. | ||
| OB_MODE | This key is not required for load balancing, but is compatible with previous features. It extends the connection capabilities. | If you set this key to 1, the value of EXTRA_INFO is suffixed to the username. | |
| EXTRA_INFO | This key is not required for load balancing, but is compatible with previous features. It extends the connection capabilities. | If you set OB_MODE to 1, the value of EXTRA_INFO is suffixed to the username. | Generally, if the username does not contain a tenant, you can set EXTRA_INFO to @oracle or @mysql to identify the tenant. |
Verify the configuration file
The OBCI package contains an executable file named obci_dblink_check.
You can use this file to verify whether the configuration file is correct. Verification results:
$ ./obci_dblink_check --tns_service obci_load_balance
run tns_file_check with tns_service:obci_load_balance
find tns_service:obci_load_balance in OBCI_TNS_FILE
Tns:
--tns_serivce_count:1
--TnsService:obci_load_balance
----description_count:1
----Discription:
------oblb:1
------oblb_group_strategy:0
------retry_all_downs:120
------retry_timeout:200000
------connect_timeout:0
------append_strategy:3001
------remove_strategy:2001
------remove_timeout:1000
------duration:1000
------retry_times:20
------address_list_count:3
------AddressList:
--------address_count:2
--------oblb_strategy:1002
--------Address:
----------host:11.xxx.xxx.1
----------port:10001
----------weight:1
--------Address:
----------host:11.xxx.xxx.1
----------port:10000
----------weight:10
------AddressList:
--------address_count:2
--------oblb_strategy:1003
--------Address:
----------host:11.xxx.xxx.1
----------port:1031
----------weight:10
--------Address:
----------host:11.xxx.xxx.1
----------port:10002
----------weight:10
------AddressList:
--------address_count:1
--------oblb_strategy:1001
--------Address:
----------host:11.xxx.xxx.1
----------port:10003
----------weight:10
--------ConnectData:
----------dbname:TEST
