High Availability

/**
 * High availability modes for database connections
 */
public enum HaMode {
  /** No high availability - connect to first host only */
  NONE,
  
  /** Replication mode - first host is primary, others are replicas */
  REPLICATION,
  
  /** Sequential mode - connect to hosts in order specified */
  SEQUENTIAL,
  
  /** Load balance mode - round-robin across all hosts */
  LOADBALANCE,
  
  /** Load balance read mode - primary sequential, replica load-balanced */
  LOAD_BALANCE_READ;
  
  /**
   * Get available host based on HA mode strategy
   * @param hostAddresses List of available host addresses
   * @param denyList Temporarily denied hosts with timeout
   * @param primary Whether to return primary or replica host
   * @return Available host address if found
   */
  public abstract Optional<HostAddress> getAvailableHost(
    List<HostAddress> hostAddresses,
    ConcurrentMap<HostAddress, Long> denyList,
    boolean primary
  );
  
  /**
   * Create HaMode from string value
   * @param value Mode name or alias
   * @return Corresponding HaMode
   * @throws IllegalArgumentException if value is invalid
   */
  public static HaMode from(String value);
  
  /**
   * Reset round-robin state (for testing)
   */
  public void resetLast();
}

// Different HA mode connection URLs
// No HA - single host
"jdbc:mariadb://localhost:3306/mydb"

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

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

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

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

// Programmatic usage
HaMode mode = HaMode.from("replication");
List<HostAddress> hosts = Arrays.asList(
    HostAddress.from("primary", 3306, true),
    HostAddress.from("replica", 3306, false)
);
ConcurrentMap<HostAddress, Long> denyList = new ConcurrentHashMap<>();
Optional<HostAddress> availableHost = mode.getAvailableHost(hosts, denyList, true);

// Basic failover configuration
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?retriesAllDown=3"

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

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

// Explicit host types
"jdbc:mariadb://address=(host=db-primary)(port=3306)(type=primary)," +
"address=(host=db-replica-1)(port=3306)(type=replica)," +
"address=(host=db-replica-2)(port=3306)(type=replica)/mydb"

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

// Geographic distribution
"jdbc:mariadb:replication://" +
"address=(host=us-east-primary)(port=3306)(type=primary)," +
"address=(host=us-west-replica)(port=3306)(type=replica)," +
"address=(host=eu-replica)(port=3306)(type=replica)/mydb"

/**
 * Host address with connection tracking
 */
public class HostAddress {
  /**
   * Get timeout for connection tracking information
   * @return Timeout timestamp or null if no tracking
   */
  public Long getThreadConnectedTimeout();
  
  /**
   * Get current number of threads connected to this host
   * @return Number of active connections
   */
  public int getThreadsConnected();
  
  // Host properties
  public final String host;
  public final int port;
  public final boolean primary;  // true for primary, false for replica
}

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

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

// When multiple hosts are available, the driver can choose
// the host with the fewest active connections
// This happens automatically when connection count tracking is available

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

// Initial connection to primary
"jdbc:mariadb:replication://primary:3306,replica1:3306,replica2:3306/mydb"

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

// Configuration with retry behavior
"jdbc:mariadb:replication://host1:3306,host2:3306/mydb?" +
"retriesAllDown=5&" +                    // Retry 5 times
"transactionReplay=true"                 // Replay transactions on recovery

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

// When network connectivity is restored:
// 1. Hosts in deny list are checked when timeout expires
// 2. Successful reconnection removes host from deny list
// 3. Load balancing resumes including recovered hosts
// 4. Connection distribution rebalances automatically

// Enable transaction replay
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
"transactionReplay=true&" +              // Enable replay
"transactionReplaySize=64"               // Buffer 64 transactions

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

// Limitations:
// - Only works for transactions within buffer size
// - Cannot replay transactions with non-deterministic functions
// - Large transactions may not fit in buffer

// Galera-aware connection
"jdbc:mariadb:sequential://node1:3306,node2:3306,node3:3306/mydb?" +
"galeraAllowedState=4"                   // Only connect to "Synced" nodes

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

// Multiple allowed states
"galeraAllowedState=3,4"                 // Allow Joined or Synced nodes

// Enable JMX for connection pools
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
"pool=true&" +
"registerJmxPool=true&" +
"poolName=MyReplicationPool"

// JMX beans provide:
// - Active connection count per host
// - Failover event history  
// - Deny list status
// - Host response times

// Enable detailed logging for troubleshooting
"jdbc:mariadb:replication://primary:3306,replica:3306/mydb?" +
"log=true&" +                           // Enable query logging
"dumpQueriesOnException=true"           // Include queries in exception messages

// Log output includes:
// - Host connection attempts
// - Failover events and timing
// - Deny list additions/removals
// - Transaction replay events

// Recommended production replication configuration
String replicationUrl = "jdbc:mariadb:replication://" +
    "primary.db.company.com:3306," +
    "replica1.db.company.com:3306," +
    "replica2.db.company.com:3306/production?" +
    
    // High availability
    "retriesAllDown=3&" +
    "transactionReplay=true&" +
    "transactionReplaySize=32&" +
    
    // Connection management
    "connectTimeout=5000&" +
    "socketTimeout=30000&" +
    
    // Security
    "sslMode=VERIFY_FULL&" +
    "trustStore=/etc/ssl/mysql-truststore.jks&" +
    
    // Performance
    "useCompression=true&" +
    "cachePrepStmts=true&" +
    
    // Monitoring
    "pool=true&" +
    "registerJmxPool=true&" +
    "poolName=ProductionReplicationPool";

// Load balancer for read-heavy applications
String loadBalanceUrl = "jdbc:mariadb:loadbalance://" +
    "db1.cluster.company.com:3306," +
    "db2.cluster.company.com:3306," +
    "db3.cluster.company.com:3306," +
    "db4.cluster.company.com:3306/database?" +
    
    // Even load distribution
    "retriesAllDown=2&" +
    
    // Connection optimization
    "pool=true&" +
    "maxPoolSize=40&" +  // Higher pool size for load balancing
    "minPoolSize=10&" +
    
    // Monitoring
    "registerJmxPool=true&" +
    "poolName=LoadBalancePool";