Starting from OceanBase Connector/J V2.4.18, the replication mode is supported. This mode allows you to specify multiple nodes in the connection string and automatically switches to a different node when a node becomes unavailable (failover).
Applicable scenarios
Applicable scenario: When multiple nodes are specified in the URL, and you want to achieve automatic failover when a node becomes unavailable. A typical scenario is when you have a primary-standby setup for OceanBase Database. You can specify the primary and standby addresses in the same URL, and the driver will handle the failover at the connection layer.
The differences between replication and loadbalance are shown in the table below:
Comparison dimension |
replication mode |
loadbalance mode |
|---|---|---|
| Main goal | Multi-node failover; can be combined with setReadOnly for read/write routing |
Multi-node load balancing at the connection level to distribute new connections |
| Typical behavior | Tries available nodes based on the address list and role (master/standby) and switches to a different node when a failure occurs | Selects a host from the candidate hosts based on the strategy when a new connection is established |
| Description | Focuses on availability and disaster recovery | Focuses on connection distribution and throughput |
JDBC URL format
Basic format
Use replication: in the protocol section, and separate the host descriptions with commas:
jdbc:oceanbase:replication://<hostDescription>[,<hostDescription>...]/[database][?<parameter>=<value>&...]
Here is a simplified example (the port number is for reference; in a direct connection to a database node, it is commonly 2881):
String url = "jdbc:oceanbase:replication://xxx.x.x.xx:2881,xxx.x.x.xx:2881/testdb?user=user1@tenant1&password=***";
Explicitly specify master/standby using address
In addition to the simple host:port format, you can use address=(type=master|slave)(host=...)(port=...) to specify the role of each node. If you do not use the address= shorthand, the first node is considered the master, and the subsequent nodes are considered standbys by default.
Here is a complex example:
jdbc:oceanbase:replication://address=(type=master)(host=xxx.x.x.xx)(port=2881),address=(type=slave)(host=xxx.x.x.xx)(port=2881)/testdb
IPv6 addresses follow the existing rules of the driver (IPv6 addresses are enclosed in square brackets in the simple format).
Primary and secondary roles: inferred by default or explicitly specified
JDBC URL format |
Description |
|---|---|
jdbc:oceanbase:replication://host1:port1,host2:port2[,host:port...]/[database][?...] |
If the roles are not explicitly specified, the driver typically treats the first address as the primary (master) and the subsequent addresses as secondary (slave). |
jdbc:oceanbase:replication://address=(type=master or slave)(host=...)(port=...),.../[database][?...] |
Explicitly specify the role of each address. This is suitable for scenarios requiring multiple primaries, multiple secondaries, or custom roles. |
Parameters related to failover and blacklists
Replication, along with loadbalance and failover, are multi-host capabilities declared at the URL level. Retries, blacklists, and other behaviors after a connection failure can still be used in conjunction with existing URL parameters (the meanings are consistent with those in the overview document in the same directory). Common parameters are described in Overview of Failover and Load-Balancing modes.
The table below lists parameters closely related to failover for easy configuration in replication scenarios.
Parameter |
Description |
|---|---|
| retriesAllDown | The maximum number of attempts when all hosts are unavailable. Default value: 120. |
| failoverLoopRetries | The maximum number of attempts during silent polling for available hosts. Default value: 120. |
| validConnectionTimeout | The duration (in seconds) for connection validation caching in a multi-host scenario; if set to 0, no validation is performed. Default value: 120. |
| loadBalanceBlacklistTimeout | The timeout (in milliseconds) for a host to be added to the blacklist (the exact implementation may vary based on the driver, as described in the overview document). |
| assureReadOnly | When used with read-only connections, it sets the session to read-only. Default value: true. |
For specific default values and units, refer to the corresponding version's RN and Database URL.
Note
Replication is a multi-node switching capability at the connection layer. After you configure the reachable nodes in the URL, the driver will attempt other candidate nodes based on the replication semantics when a connection fails.
Notice
After you change the URL, port, tenant, or user format (such as user@tenant in MySQL mode), verify the connection and failover. In a production environment, it is recommended to confirm that the failover path meets expectations by using monitoring tools.