OceanBase Connector/J supports three failover and load balancing modes: sequential, loadbalance, and replication.
Sequential mode
The sequential mode supports connection failover in a multi-host environment. This mode does not allow secondary servers to perform load-balanced reads. OceanBase Connector/J attempts to connect to the hosts in the sequence specified in the connection URL, so the first available host is used for all queries. The connection URL is as follows:
jdbc:oceanbasedb:sequential:host1,host2,host3,host4/testobdb
OceanBase Connector/J first attempts to connect to host1. If the host is unavailable, OceanBase Connector/J attempts to connect to host2. When a host fails, OceanBase Connector/J attempts to reconnect to a host in the same sequence.
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.
Replication mode
The replication mode supports connection load balancing in a primary/secondary deployment. This mode applies to environments with one or more hosts. This mode allows secondary servers to handle read queries for load balancing if the connection is set to read-only beforehand. OceanBase Connector/J randomly selects a secondary server from the connection URL to handle read queries for load balancing.
Related parameters
The following table describes the parameters.
| Parameter | Description |
|---|---|
| autoReconnect | If this parameter is enabled and no failover or load balancing mode is in use, OceanBase Connector/J only attempts to reconnect to the host after the connection fails, which is called basic failover. If this parameter is enabled and a failover and load balancing mode is in use, OceanBase Connector/J blocklists the failed host and attempts to connect to other hosts of the same type, which is called standard failover. Default value: false. |
| 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: 120s. |
| 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: false. |
| allowMasterDownConnection | If this parameter is enabled in replication mode, a connection can be created when the primary server is down. If no primary server is available, OceanBase Connector/J connects to a secondary server, and Connection.isReadOnly() returns true. Default value: false. |