Load balancing strategy configuration methods|V2.4.17|OceanBase Connector/J

Load balancing strategy configuration methods

Last Updated：2026-04-10 06:56:35 Updated

You can configure load balancing strategies in the URL or configuration file.

Configure load balancing strategies in the URL

You can specify load balancing information in the ExtendDescription portion of the connection URL used by OceanBase Connector/J. The default configuration method is as follows:

jdbc:oceanbase:[loadbalance:]//@[ExtendDescription]|<hostDescription>[,<hostDescription>...]]/[database][?<key1>=<value1>[&<key2>=<value2>]]

Here is an example of ExtendDescription settings:

Notice

Each DESCRIPTION has a unique NET_SERVICE_NAME.

(NET_SERVICE_NAME=(DESCRIPTION=
  (OBLB=ON)                                                    
  (OBLB_RETRY_ALL_DOWNS=120)
  (OBLB_GROUP_STRATEGY=ROTATION)                               
  (OBLB_BLACKLIST= 
      (
        REMOVE_STRATEGY=(
          (NAME=TIMEOUT)
          (TIMEOUT=100)
        )
      )                          
      (
        APPEND_STRATEGY =(
          (NAME=RETRYDURATION)
          (RETRYTIMES=3)
          (DURATION=100)
        )
      )
  )
  (ADDRESS_LIST=  
     (OBLB_STRATEGY=SERVERAFFINITY)                          
     (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))      
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
  )    
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=RANDOM)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
  )
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=ROTATION)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
   )
   (CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
)
)

Here is a complete example:

String url = "jdbc:oceanbase:loadbalance://@(NET_SERVICE_NAME=(DESCRIPTION=
  (OBLB=ON)                                                    
  (OBLB_RETRY_ALL_DOWNS=120)
  (OBLB_GROUP_STRATEGY=ROTATION)                               
  (OBLB_BLACKLIST= 
      (
        REMOVE_STRATEGY=(
          (NAME=TIMEOUT)
          (TIMEOUT=100)
        )
      )                          
      (
        APPEND_STRATEGY =(
          (NAME=RETRYDURATION)
          (RETRYTIMES=3)
          (DURATION=100)
        )
      )
  )
  (ADDRESS_LIST=  
     (OBLB_STRATEGY=SERVERAFFINITY)                          
     (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))      
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
  )    
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=RANDOM)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
  )
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=ROTATION)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
   )
   (CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
))/OBDATABASE?rewriteBatchedStatements=true&allowSendParamTypes=true&prepStmtCacheSize=1000";
Connection = DriverManager.getConnection(url);

You can also configure load balancing strategies by using URL parameters. The following table describes the parameters.

Note

We recommend that you use URL parameters to configure load balancing strategies for OceanBase Connector/J. You can specify the corresponding settings in the Java Database Connectivity (JDBC) URL.

Parameter	Description	Remarks
retriesAllDown	The maximum number of connection retries when all available database nodes cannot be connected. Default value: `120`.	This parameter is equivalent to `OBLB_RETRY_ALL_DOWNS` in the extended configuration information, but it will be overwritten by `OBLB_RETRY_ALL_DOWNS`.
loadBalanceStrategy	Supported strategies are `RANDOM`, `ROTATION`, and `SERVERAFFINITY`.	N/A
serverAffinityOrder	The pairs of hostnames and port numbers used in the `SERVERAFFINITY` load balancing strategy, which are separated with commas (,). The hosts specified in this parameter must be a subset of those listed in the URL, and their case and type must match. For example, you cannot use IP addresses of hosts in this parameter while using the corresponding hostnames in the URL, or vice versa.	N/A
loadBalanceBlacklistTimeout	The timeout period, in milliseconds, after which a host is added to the blocklist. The blocklist is enabled only if you set this parameter to a positive integer. In other words, if a host cannot be connected after the specified period, it is added to the blocklist. The default value is `0`, which indicates that the blocklist is disabled.	N/A

Here are some examples:

"jdbc:oceanbase:loadbalance://host1:port1:5,host2:port2:10/" + "test?user=test@oracle&password=test"

"jdbc:oceanbase:loadbalance://host1:port1,host2:port2/" + "test?user=test@oracle&password=test&loadBalanceStrategy=serverAffinity&serverAffinityOrder=host1:port1:5,host2:port2:10"

"jdbc:oceanbase:loadbalance://host1:port1:5,host2:port2:10/" + "test?user=test@oracle&password=test&loadBalanceStrategy=serverAffinity&serverAffinityOrder=host1:port1:5,host2:port2:10"

Configure load balancing strategies in the configuration file

In OceanBase Connector/J, you can use the oceanbase.tns_admin system parameter to specify the directory of the configuration file. If you do not set this parameter, the directory is specified by the OCEANBASE_TNS_ADMIN environment variable. By default, the name of the configuration file is tnsnames.ob. You can use the OCEANBASE_TNS_ADMIN_NAME environment variable to specify a different configuration file name.

The OCEANBASE_TNS_ADMIN_DEAMON environment variable specifies whether to enable the daemon to monitor changes in the configuration file. The default value is true. If you set it to false, OceanBase Connector/J reads the configuration file each time it connects to the database. You can use the OCEANBASE_TNS_ADMIN_NAME environment variable to change the name of the tns configuration file. By default, the name of the configuration file is tnsnames.ob.

Prerequisites

You have specified the use of the configuration file by setting export OCEANBASE_TNS_ADMIN=/path or oceanbase.tns_admin=/path. oceanbase.tns_admin is a Java Virtual Machine (JVM) parameter.
You have specified the name of the configuration file by setting export OCEANBASE_TNS_ADMIN_NAME=/tnsyournames.ob or oceanbase.tns_admin_name=tnsyournames.ob. oceanbase.tns_admin_name is a JVM parameter. If you do not specify it, the default file name tnsnames.ob will be used. We recommend that you do not specify the file name.
You have set export OCEANBASE_TNS_ADMIN_DEAMON=false or oceanbase.tns_admin_deamon=false if you do not want to enable the daemon. oceanbase.tns_admin_deamon is a JVM parameter.

Content of the configuration file

The content of the configuration file must be in the same format as that of the extended configuration information. However, the configuration file can contain multiple DESCRIPTIONs and each DESCRIPTION has a unique NET_SERVICE_NAME value.

In the following example, the configuration file contains three NET_SERVICE_NAME values: TNS_TEST_NORMAL, TNS_TEST_WEIGHT, and TNS_TEST_GROUP.

TNS_TEST_NORMAL=
 (DESCRIPTION=
  (ADDRESS_LIST =
   (OBLB_STRATEGY=RANDOM)
   (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1))
   (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port1))
   (CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
  )
 )
TNS_TEST_WEIGHT=
 (DESCRIPTION=
  (ADDRESS_LIST =
   (OBLB_STRATEGY=SERVERAFFINITY)
   (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=4))
   (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
   (CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
  )
 )
TNS_TEST_GROUP=(DESCRIPTION=
  (OBLB=ON)                                                    
  (OBLB_RETRY_ALL_DOWNS=120)
  (OBLB_GROUP_STRATEGY=ROTATION)                               
  (OBLB_BLACKLIST=  
      (
        REMOVE_STRATEGY=(
          (NAME=TIMEOUT)
          (TIMEOUT=100)
        )
      )                          
      (
        APPEND_STRATEGY =(
          (NAME=RETRYDURATION)
          (RETRYTIMES=3)
          (DURATION=100)
        )
      ) 
  )
  (ADDRESS_LIST=   
     (OBLB_STRATEGY=SERVERAFFINITY)                          
     (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1)(WEIGHT=1))      
     (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2)(WEIGHT=10))
  )    
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=RANDOM)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
  )
  (ADDRESS_LIST= 
     (OBLB_STRATEGY=ROTATION)
     (ADDRESS=(PROTOCOL=tcp)(HOST=host3)(port=port3)) 
     (ADDRESS=(PROTOCOL=tcp)(HOST=host4)(port=port4))
   )
   (CONNECT_DATA=(SERVICE_NAME=OBDATABASE))
)

Example of minimal configuration

The following example shows the minimal extended configuration information for the LoadBalance mode of OceanBase Connector/J:

String connU = "jdbc:oceanbase:loadbalance://@TNS_TEST_NORMAL/test?rewriteBatchedStatements=true&allowSendParamTypes=true&prepStmtCacheSize=1000&prepStmtCacheSqlLimit=4096&cachePrepStmts=true";
Connection sharedConnection = DriverManager.getConnection(connU, "usr", "password");

The URL in the example contains the following key information:

jdbc:oceanbase:loadbalance indicates that the LoadBalance mode is enabled. This information is required.
@TNS_TEST_NORMAL indicates the NET_SERVICE_NAME value of a DESCRIPTION. Multiple DESCRIPTIONs in a configuration file are distinguished by their NET_SERVICE_NAME values that start with an at sign (@).

The following example shows the minimal configuration of TNS_TEST_NORMAL for using the default strategy:

TNS_TEST_NORMAL=
 (DESCRIPTION=
  (ADDRESS_LIST =
   (ADDRESS=(PROTOCOL=tcp)(HOST=host1)(PORT=port1))
   (ADDRESS=(PROTOCOL=tcp)(HOST=host2)(PORT=port2))
   (CONNECT_DATA=(SERVICE_NAME=ORCLCDB))
  )
 )

Customer Stories

Documentation