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

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

Configure load balancing strategies in the URL

You can specify load balancing information in the ExtendDescription parameter of the URL that connects to OceanBase Connector/J. Default configuration method:

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

The following example shows the sample settings of the ExtendDescription parameter:

Notice

Each configuration URL has a unique NET_SERVICE_NAME value.

(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))
)
)

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 Option. The following table describes the parameters.

Note

We recommend that you use URL Option 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 has the same meaning as `RETRY_ALL_DOWNS` in the extended configuration information. The settings in the extended configuration information overwrite those in the URL.
loadBalanceStrategy	Supported strategies are `RANDOM`, `ROTATION`, and `SERVERAFFINITY`.	N/A
serverAffinityOrder	The pairs of host names and port numbers when the `SERVERAFFINITY` load balancing strategy is used. The pairs of host names and port numbers are separated with commas (,). The hosts specified in this parameter must be a subset of those specified in the Host parameter of this URL, and their case and type must be the same. For example, you cannot use IP addresses of hosts in this parameter while using the corresponding host names in the Host parameter.	N/A
loadBalanceBlacklistTimeout	The timeout period, in milliseconds, after which a host is added to the blacklist. The blacklist 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 blacklist. The default value is 0, which indicates that the blacklist is disabled.	N/A

Example:

jdbc:oceanbase:loadbalance//host1:port1:5,host2:port2:10/schema?user=usr&password=pwd&loadBalanceStrategy=serverAffinity

Configure load balancing strategies by using 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 specify the directory, the directory is specified by using 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 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 export oceanbase.tns_admin_name=tnsyournames.ob. oceanbase.tns_admin_name is a JVM parameter. By default, the tnsnames.ob configuration file is used. We do not recommend that you specify the file name.
To disable the daemon, you can set the export OCEANBASE_TNS_ADMIN_DEAMON environment variable or the oceanbase.tns_admin_deamon JVM parameter to false.

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 DESCRIPTION parameters and each DESCRIPTION parameter belongs to a NET_SERVICE_NAME.

The following sample code indicates that 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 minimum configuration

The following example shows the minimum extended configuration information for the load balancing 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.
@TNS_TEST_NORMAL specifies the value of NET_SERVICE_NAME. If the configuration file contains multiple NET_SERVICE_NAME values, each value must start with an at sign (@).

The following example shows the minimum 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))
  )
 )

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

Configure load balancing strategies in the URL

You can specify load balancing information in the ExtendDescription parameter of the URL that connects to OceanBase Connector/J. Default configuration method:

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

The following example shows the sample settings of the ExtendDescription parameter:

Notice

Each configuration URL has a unique NET_SERVICE_NAME value.

(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))
)
)

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 Option. The following table describes the parameters.

Note

We recommend that you use URL Option 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 has the same meaning as `RETRY_ALL_DOWNS` in the extended configuration information. The settings in the extended configuration information overwrite those in the URL.
loadBalanceStrategy	Supported strategies are `RANDOM`, `ROTATION`, and `SERVERAFFINITY`.	N/A
serverAffinityOrder	The pairs of host names and port numbers when the `SERVERAFFINITY` load balancing strategy is used. The pairs of host names and port numbers are separated with commas (,). The hosts specified in this parameter must be a subset of those specified in the Host parameter of this URL, and their case and type must be the same. For example, you cannot use IP addresses of hosts in this parameter while using the corresponding host names in the Host parameter.	N/A
loadBalanceBlacklistTimeout	The timeout period, in milliseconds, after which a host is added to the blacklist. The blacklist 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 blacklist. The default value is 0, which indicates that the blacklist is disabled.	N/A

Example:

jdbc:oceanbase:loadbalance//host1:port1:5,host2:port2:10/schema?user=usr&password=pwd&loadBalanceStrategy=serverAffinity

Configure load balancing strategies by using the configuration file

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 export oceanbase.tns_admin_name=tnsyournames.ob. oceanbase.tns_admin_name is a JVM parameter. By default, the tnsnames.ob configuration file is used. We do not recommend that you specify the file name.
To disable the daemon, you can set the export OCEANBASE_TNS_ADMIN_DEAMON environment variable or the oceanbase.tns_admin_deamon JVM parameter to false.

Content of the configuration file

The following sample code indicates that 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 minimum configuration

The following example shows the minimum extended configuration information for the load balancing 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.
@TNS_TEST_NORMAL specifies the value of NET_SERVICE_NAME. If the configuration file contains multiple NET_SERVICE_NAME values, each value must start with an at sign (@).

The following example shows the minimum 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

Load balancing strategy configuration methods

Configure load balancing strategies in the URL

Notice

Note

Configure load balancing strategies by using the configuration file

Prerequisites

Content of the configuration file

Example of minimum configuration

Load balancing strategy configuration methods

Configure load balancing strategies in the URL

Notice

Note

Configure load balancing strategies by using the configuration file

Prerequisites

Content of the configuration file

Example of minimum configuration