OceanBase Connector/J supports two modes in multi-host scenarios: replication (Failover) and loadbalance (Load-Balancing).
replication mode
replication mode declares multiple database addresses in the JDBC URL. When an address is unreachable, the driver automatically tries other addresses in the list to achieve Failover. This mode is suitable for scenarios where multiple direct nodes are configured at the connection layer, and the driver handles the switch when a node fails.
For detailed syntax, URL examples, and differences from loadbalance, see Replication mode.
LoadBalance mode
The LoadBalance mode supports connection load balancing in a multi-host environment. This mode does not allow secondary servers to perform load-balanced reads. OceanBase Connector/J randomly selects a host from each connection URL to implement load balancing for all queries. The connections are randomly distributed across all hosts, achieving load balancing for queries.
Related parameters
The following table describes the parameters.
Parameter |
Description |
|---|---|
| retriesAllDown | If all hosts are down during a failover, this parameter is used to define the maximum number of connection retries allowed for OceanBase Connector/J. Default value: 120. |
| failoverLoopRetries | When OceanBase Connector/J silently searches for available hosts, this parameter specifies the maximum number of connection retries allowed for OceanBase Connector/J. This parameter is different from retriesAllDown. The silent search is used for temporary solutions of OceanBase Connector/J. For example, the primary connection is used to handle read queries when a secondary connection fails. Default value: 120. |
| validConnectionTimeout | When multiple hosts are configured, OceanBase Connector/J holds the verification connection within the specified duration, in seconds. When this parameter is set to 0, no verification is performed. Default value: 120. |
| loadBalanceBlacklistTimeout | When a connection fails, the host is added to the blocklist and blocked for the duration defined by this parameter. OceanBase Connector/J preferentially attempts to connect to a host that is not in the blocklist. It attempts to connect to a host that is in the blocklist only when no host is found. The blocklist is shared within the class loader. Default value: 50 ms. |
| assureReadOnly | If this parameter is enabled when a failover and load balancing mode is in use and a read-only connection is established to the host, the session is set to read-only to ensure that the connection is in read-only mode. Default value: true. |