0
# High Availability
1

2
Multi-host connection support with automatic failover, load balancing, and replication awareness for enterprise-grade availability.
3

4
## Capabilities
5

6
### High Availability Modes
7

8
Enumeration defining different high availability connection strategies.
9

10
```java { .api }
11
/**
12
 * High availability modes for database connections
13
 */
14
public enum HaMode {
15
  /** No high availability - connect to first host only */
16
  NONE,
17
  
18
  /** Replication mode - first host is primary, others are replicas */
19
  REPLICATION,
20
  
21
  /** Sequential mode - connect to hosts in order specified */
22
  SEQUENTIAL,
23
  
24
  /** Load balance mode - round-robin across all hosts */
25
  LOADBALANCE,
26
  
27
  /** Load balance read mode - primary sequential, replica load-balanced */
28
  LOAD_BALANCE_READ;
29
  
30
  /**
31
   * Get available host based on HA mode strategy
32
   * @param hostAddresses List of available host addresses
33
   * @param denyList Temporarily denied hosts with timeout
34
   * @param primary Whether to return primary or replica host
35
   * @return Available host address if found
36
   */
37
  public abstract Optional<HostAddress> getAvailableHost(
38
    List<HostAddress> hostAddresses,
39
    ConcurrentMap<HostAddress, Long> denyList,
40
    boolean primary
41
  );
42
  
43
  /**
44
   * Create HaMode from string value
45
   * @param value Mode name or alias
46
   * @return Corresponding HaMode
47
   * @throws IllegalArgumentException if value is invalid
48
   */
49
  public static HaMode from(String value);
50
  
51
  /**
52
   * Reset round-robin state (for testing)
53
   */
54
  public void resetLast();
55
}
56
```
57

58
**Usage Examples:**
59

60
```java
61
// Different HA mode connection URLs
62
// No HA - single host
63
"jdbc:mariadb://localhost:3306/mydb"
64

65
// Replication - primary and replicas
66
"jdbc:mariadb:replication://primary:3306,replica1:3306,replica2:3306/mydb"
67

68
// Load balancing - round-robin all hosts
69
"jdbc:mariadb:loadbalance://host1:3306,host2:3306,host3:3306/mydb"
70

71
// Sequential - connect in order
72
"jdbc:mariadb:sequential://host1:3306,host2:3306,host3:3306/mydb"
73

74
// Load balance reads only
75
"jdbc:mariadb:load-balance-read://primary:3306,replica1:3306,replica2:3306/mydb"
76

77
// Programmatic usage
78
HaMode mode = HaMode.from("replication");
79
List<HostAddress> hosts = Arrays.asList(
80
    HostAddress.from("primary", 3306, true),
81
    HostAddress.from("replica", 3306, false)
82
);
83
ConcurrentMap<HostAddress, Long> denyList = new ConcurrentHashMap<>();
84
Optional<HostAddress> availableHost = mode.getAvailableHost(hosts, denyList, true);
85
```
86

87
### Host Selection Strategies
88

89
Different algorithms for selecting hosts based on HA mode:
90

91
**REPLICATION Mode:**
92
- Primary operations: Connect to first available primary host
93
- Read operations: Load balance across replica hosts
94
- Failover: Switch to replica if primary fails, promote replica to primary
95

96
**SEQUENTIAL Mode:**
97
- Connect to hosts in the order specified in connection string
98
- Failover to next host in list if current host fails
99
- Always prefer earlier hosts in the list when they become available
100

101
**LOADBALANCE Mode:**
102
- Round-robin distribution across all available hosts
103
- Equal load distribution for both read and write operations
104
- Automatic exclusion of failed hosts from rotation
105

106
**LOAD_BALANCE_READ Mode:**
107
- Write operations: Sequential primary host selection
108
- Read operations: Load balance across replica hosts
109
- Combines benefits of replication and load balancing
110

111
### Failover Configuration
112

113
Settings for controlling failover behavior and retry logic.
114

115
```java
116
// Basic failover configuration
117
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?retriesAllDown=3"
118

119
// Advanced failover with transaction replay
120
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
121
"retriesAllDown=5&" +                    // Retry 5 times when all hosts down
122
"transactionReplay=true&" +              // Enable transaction replay on failover
123
"transactionReplaySize=64"               // Buffer size for transaction replay
124

125
// Galera cluster support
126
"jdbc:mariadb:sequential://node1:3306,node2:3306,node3:3306/mydb?" +
127
"galeraAllowedState=4"                   // Only connect to Galera nodes in state 4 (Synced)
128
```
129

130
### Connection Distribution
131

132
Advanced host specification with explicit primary/replica designation:
133

134
```java
135
// Explicit host types
136
"jdbc:mariadb://address=(host=db-primary)(port=3306)(type=primary)," +
137
"address=(host=db-replica-1)(port=3306)(type=replica)," +
138
"address=(host=db-replica-2)(port=3306)(type=replica)/mydb"
139

140
// Mixed port configurations
141
"jdbc:mariadb://address=(host=primary)(port=3306)(type=primary)," +
142
"address=(host=replica1)(port=3307)(type=replica)," +
143
"address=(host=replica2)(port=3308)(type=replica)/mydb"
144

145
// Geographic distribution
146
"jdbc:mariadb:replication://" +
147
"address=(host=us-east-primary)(port=3306)(type=primary)," +
148
"address=(host=us-west-replica)(port=3306)(type=replica)," +
149
"address=(host=eu-replica)(port=3306)(type=replica)/mydb"
150
```
151

152
## Host Management
153

154
### Host State Tracking
155

156
The driver automatically tracks host connection health and performance:
157

158
```java { .api }
159
/**
160
 * Host address with connection tracking
161
 */
162
public class HostAddress {
163
  /**
164
   * Get timeout for connection tracking information
165
   * @return Timeout timestamp or null if no tracking
166
   */
167
  public Long getThreadConnectedTimeout();
168
  
169
  /**
170
   * Get current number of threads connected to this host
171
   * @return Number of active connections
172
   */
173
  public int getThreadsConnected();
174
  
175
  // Host properties
176
  public final String host;
177
  public final int port;
178
  public final boolean primary;  // true for primary, false for replica
179
}
180
```
181

182
### Deny List Management
183

184
Temporary exclusion of failed hosts with automatic recovery:
185

186
```java
187
// Hosts are automatically added to deny list when they fail
188
// and removed when the deny timeout expires
189
ConcurrentMap<HostAddress, Long> denyList = new ConcurrentHashMap<>();
190

191
// Manual deny list management (for testing/administration)
192
HostAddress problematicHost = HostAddress.from("slow-host", 3306);
193
long denyUntil = System.currentTimeMillis() + 60000; // Deny for 1 minute
194
denyList.put(problematicHost, denyUntil);
195
```
196

197
### Connection Load Distribution
198

199
Automatic load distribution based on active connection counts:
200

201
```java
202
// When multiple hosts are available, the driver can choose
203
// the host with the fewest active connections
204
// This happens automatically when connection count tracking is available
205

206
// Host selection priority:
207
// 1. Host with fewest connections (if tracking available)
208
// 2. Round-robin selection based on HA mode
209
// 3. Exclude hosts in deny list
210
```
211

212
## Failover Scenarios
213

214
### Primary Failure in Replication Mode
215

216
```java
217
// Initial connection to primary
218
"jdbc:mariadb:replication://primary:3306,replica1:3306,replica2:3306/mydb"
219

220
// When primary fails:
221
// 1. Driver detects connection failure
222
// 2. Primary host added to deny list
223
// 3. Connection attempts replica hosts
224
// 4. First available replica becomes new primary for this connection
225
// 5. Subsequent read operations can use other replicas
226
```
227

228
### All Hosts Down Scenario
229

230
```java
231
// Configuration with retry behavior
232
"jdbc:mariadb:replication://host1:3306,host2:3306/mydb?" +
233
"retriesAllDown=5&" +                    // Retry 5 times
234
"transactionReplay=true"                 // Replay transactions on recovery
235

236
// Behavior when all hosts are down:
237
// 1. Driver attempts connection to each host
238
// 2. All hosts added to deny list
239
// 3. Wait and retry up to retriesAllDown times
240
// 4. If transactionReplay=true, replay buffered transactions when host recovers
241
// 5. Throw SQLException if all retries exhausted
242
```
243

244
### Network Partition Recovery
245

246
```java
247
// When network connectivity is restored:
248
// 1. Hosts in deny list are checked when timeout expires
249
// 2. Successful reconnection removes host from deny list
250
// 3. Load balancing resumes including recovered hosts
251
// 4. Connection distribution rebalances automatically
252
```
253

254
## Transaction Replay
255

256
Automatic transaction replay for seamless failover:
257

258
```java
259
// Enable transaction replay
260
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
261
"transactionReplay=true&" +              // Enable replay
262
"transactionReplaySize=64"               // Buffer 64 transactions
263

264
// How it works:
265
// 1. Driver buffers transactions in memory
266
// 2. On connection failure, driver switches to available host
267
// 3. Buffered transactions are replayed on new connection
268
// 4. Application continues without manual retry logic
269
// 5. Buffer size limits memory usage
270

271
// Limitations:
272
// - Only works for transactions within buffer size
273
// - Cannot replay transactions with non-deterministic functions
274
// - Large transactions may not fit in buffer
275
```
276

277
## Galera Cluster Support
278

279
Special support for Galera cluster environments:
280

281
```java
282
// Galera-aware connection
283
"jdbc:mariadb:sequential://node1:3306,node2:3306,node3:3306/mydb?" +
284
"galeraAllowedState=4"                   // Only connect to "Synced" nodes
285

286
// Galera states:
287
// 1 = Joining - node is joining cluster
288
// 2 = Donor/Desynced - node is providing state transfer
289
// 3 = Joined - node has joined but not synced
290
// 4 = Synced - node is fully synchronized (default requirement)
291

292
// Multiple allowed states
293
"galeraAllowedState=3,4"                 // Allow Joined or Synced nodes
294
```
295

296
## Monitoring and Diagnostics
297

298
### JMX Monitoring
299

300
Monitor connection health and failover events:
301

302
```java
303
// Enable JMX for connection pools
304
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
305
"pool=true&" +
306
"registerJmxPool=true&" +
307
"poolName=MyReplicationPool"
308

309
// JMX beans provide:
310
// - Active connection count per host
311
// - Failover event history  
312
// - Deny list status
313
// - Host response times
314
```
315

316
### Logging Failover Events
317

318
```java
319
// Enable detailed logging for troubleshooting
320
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
321
"log=true&" +                           // Enable query logging
322
"dumpQueriesOnException=true"           // Include queries in exception messages
323

324
// Log output includes:
325
// - Host connection attempts
326
// - Failover events and timing
327
// - Deny list additions/removals
328
// - Transaction replay events
329
```
330

331
## Best Practices
332

333
### Production Replication Setup
334

335
```java
336
// Recommended production replication configuration
337
String replicationUrl = "jdbc:mariadb:replication://" +
338
    "primary.db.company.com:3306," +
339
    "replica1.db.company.com:3306," +
340
    "replica2.db.company.com:3306/production?" +
341
    
342
    // High availability
343
    "retriesAllDown=3&" +
344
    "transactionReplay=true&" +
345
    "transactionReplaySize=32&" +
346
    
347
    // Connection management
348
    "connectTimeout=5000&" +
349
    "socketTimeout=30000&" +
350
    
351
    // Security
352
    "sslMode=VERIFY_FULL&" +
353
    "trustStore=/etc/ssl/mysql-truststore.jks&" +
354
    
355
    // Performance
356
    "useCompression=true&" +
357
    "cachePrepStmts=true&" +
358
    
359
    // Monitoring
360
    "pool=true&" +
361
    "registerJmxPool=true&" +
362
    "poolName=ProductionReplicationPool";
363
```
364

365
### Load Balancer Setup
366

367
```java
368
// Load balancer for read-heavy applications
369
String loadBalanceUrl = "jdbc:mariadb:loadbalance://" +
370
    "db1.cluster.company.com:3306," +
371
    "db2.cluster.company.com:3306," +
372
    "db3.cluster.company.com:3306," +
373
    "db4.cluster.company.com:3306/database?" +
374
    
375
    // Even load distribution
376
    "retriesAllDown=2&" +
377
    
378
    // Connection optimization
379
    "pool=true&" +
380
    "maxPoolSize=40&" +  // Higher pool size for load balancing
381
    "minPoolSize=10&" +
382
    
383
    // Monitoring
384
    "registerJmxPool=true&" +
385
    "poolName=LoadBalancePool";
386
```