tessl/maven-com-mysql--mysql-connector-j

JDBC Type 4 driver for MySQL with X DevAPI support for document store operations

Overview

Eval results

Files

JDBC High Availability

Name: tessl/maven-com-mysql--mysql-connector-j
Author: tessl

Load balancing, replication, and failover support for high-availability MySQL deployments. These features enable applications to maintain connectivity and performance across multiple database servers.

Capabilities

Load-Balanced Connections

Load-balanced connection support for distributing queries across multiple MySQL servers.

package com.mysql.cj.jdbc.ha;

public interface LoadBalancedConnection extends com.mysql.cj.jdbc.JdbcConnection {
    // Host management
    boolean addHost(String host) throws SQLException;
    void removeHost(String host) throws SQLException;
    void removeHostWhenNotInUse(String host) throws SQLException;

    // Connection testing
    void ping(boolean allConnections) throws SQLException;
}

public class LoadBalancedMySQLConnection extends MultiHostMySQLConnection
    implements LoadBalancedConnection {
    // Implementation of load-balanced connection
}

public class LoadBalancedConnectionProxy extends MultiHostConnectionProxy
    implements InvocationHandler {
    // Proxy for managing load-balanced connections

    public LoadBalancedConnectionProxy(ConnectionUrl connectionUrl) throws SQLException;

    // Host management
    public synchronized void addHost(String host) throws SQLException;
    public synchronized void removeHost(String host) throws SQLException;
    public synchronized void removeHostWhenNotInUse(String host) throws SQLException;

    // Connection balancing
    public synchronized void ping(boolean allIsReadOnly) throws SQLException;
}

Usage:

// URL format: jdbc:mysql:loadbalance://host1:port,host2:port,host3:port/database
String url = "jdbc:mysql:loadbalance://server1:3306,server2:3306,server3:3306/mydb" +
             "?loadBalanceStrategy=random" +
             "&loadBalanceAutoCommitStatementThreshold=5";

Connection conn = DriverManager.getConnection(url, "root", "password");

// Cast to LoadBalancedConnection for management
LoadBalancedConnection lbConn = conn.unwrap(LoadBalancedConnection.class);

// Add new host to rotation
lbConn.addHost("server4:3306");

// Remove host from rotation
lbConn.removeHost("server2:3306");

// Remove host when not in use (graceful removal)
lbConn.removeHostWhenNotInUse("server3:3306");

// Test all connections
lbConn.ping(false);

// Use connection normally
Statement stmt = conn.createStatement();
ResultSet rs = stmt.executeQuery("SELECT * FROM users");
// Results come from load-balanced server

Load Balance Strategies

Pluggable strategies for selecting which server to use for each connection.

package com.mysql.cj.jdbc.ha;

public interface BalanceStrategy {
    // Initialize strategy
    void init(Connection conn, Properties props) throws SQLException;

    // Destroy strategy
    void destroy();

    // Pick connection from available hosts
    Connection pickConnection(
        InvocationHandler proxy,
        List<String> configuredHosts,
        Map<String, JdbcConnection> liveConnections,
        long[] responseTimes,
        int numRetries
    ) throws SQLException;
}

public class RandomBalanceStrategy implements BalanceStrategy {
    // Randomly selects from available hosts
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public Connection pickConnection(
        InvocationHandler proxy,
        List<String> configuredHosts,
        Map<String, JdbcConnection> liveConnections,
        long[] responseTimes,
        int numRetries
    ) throws SQLException;
}

public class BestResponseTimeBalanceStrategy implements BalanceStrategy {
    // Selects host with best response time
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public Connection pickConnection(
        InvocationHandler proxy,
        List<String> configuredHosts,
        Map<String, JdbcConnection> liveConnections,
        long[] responseTimes,
        int numRetries
    ) throws SQLException;
}

public class SequentialBalanceStrategy implements BalanceStrategy {
    // Selects hosts sequentially in order
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public Connection pickConnection(
        InvocationHandler proxy,
        List<String> configuredHosts,
        Map<String, JdbcConnection> liveConnections,
        long[] responseTimes,
        int numRetries
    ) throws SQLException;
}

public class ServerAffinityStrategy implements BalanceStrategy {
    // Maintains affinity to specific servers
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public Connection pickConnection(
        InvocationHandler proxy,
        List<String> configuredHosts,
        Map<String, JdbcConnection> liveConnections,
        long[] responseTimes,
        int numRetries
    ) throws SQLException;
}

Usage:

// Random strategy (default)
String url = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
             "?loadBalanceStrategy=random";

// Best response time strategy
String url2 = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
              "?loadBalanceStrategy=bestResponseTime";

// Sequential strategy
String url3 = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
              "?loadBalanceStrategy=com.mysql.cj.jdbc.ha.SequentialBalanceStrategy";

// Server affinity strategy
String url4 = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
              "?loadBalanceStrategy=serverAffinity" +
              "&serverAffinityOrder=server2,server1";

Connection conn = DriverManager.getConnection(url, "root", "password");

Load Balance Exception Checkers

Pluggable checkers to determine if exceptions should trigger failover.

package com.mysql.cj.jdbc.ha;

public interface LoadBalanceExceptionChecker {
    // Initialize checker
    void init(Connection conn, Properties props) throws SQLException;

    // Destroy checker
    void destroy();

    // Check if exception should trigger failover
    boolean shouldExceptionTriggerFailover(SQLException ex);
}

public class StandardLoadBalanceExceptionChecker implements LoadBalanceExceptionChecker {
    // Standard exception checker
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public boolean shouldExceptionTriggerFailover(SQLException ex);
}

public class NdbLoadBalanceExceptionChecker implements LoadBalanceExceptionChecker {
    // Exception checker for MySQL Cluster (NDB)
    public void init(Connection conn, Properties props) throws SQLException;
    public void destroy();
    public boolean shouldExceptionTriggerFailover(SQLException ex);
}

Usage:

// Use standard exception checker
String url = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
             "?loadBalanceExceptionChecker=" +
             "com.mysql.cj.jdbc.ha.StandardLoadBalanceExceptionChecker";

// Use NDB exception checker for MySQL Cluster
String url2 = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
              "?loadBalanceExceptionChecker=" +
              "com.mysql.cj.jdbc.ha.NdbLoadBalanceExceptionChecker";

Connection conn = DriverManager.getConnection(url, "root", "password");

Load Balance Auto-Commit Interceptor

Interceptor for handling auto-commit in load-balanced environments.

package com.mysql.cj.jdbc.ha;

public class LoadBalancedAutoCommitInterceptor implements QueryInterceptor {
    // Manages transaction boundaries in load-balanced connections
    // Ensures consistency when autoCommit=true

    public QueryInterceptor init(MysqlConnection conn, Properties props, Log log);

    public <T extends Resultset> T preProcess(Supplier<String> sql, Query interceptedQuery);

    public boolean executeTopLevelOnly();

    public void destroy();

    public <T extends Resultset> T postProcess(
        Supplier<String> sql,
        Query interceptedQuery,
        T originalResultSet,
        ServerSession serverSession
    );
}

Usage:

// Automatically enabled for load-balanced connections
// Configure via URL parameters
String url = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
             "?loadBalanceAutoCommitStatementThreshold=5" +
             "?loadBalanceAutoCommitStatementRegex=^SELECT.*";

Connection conn = DriverManager.getConnection(url, "root", "password");

Replication Connections

Replication-aware connections that route reads to replicas and writes to source.

package com.mysql.cj.jdbc.ha;

public interface ReplicationConnection extends com.mysql.cj.jdbc.JdbcConnection {
    // Get connection group ID
    long getConnectionGroupId();

    // Get current active connection
    JdbcConnection getCurrentConnection();

    // Get source connection (for writes)
    JdbcConnection getSourceConnection();

    // Promote replica to source
    void promoteReplicaToSource(String host) throws SQLException;

    // Remove source from pool
    void removeSourceHost(String host) throws SQLException;
    void removeSourceHost(String host, boolean waitUntilNotInUse) throws SQLException;

    // Check if host is a source
    boolean isHostSource(String host);

    // Get replica connection (for reads)
    JdbcConnection getReplicaConnection();

    // Add replica to pool
    void addReplicaHost(String host) throws SQLException;

    // Remove replica from pool
    void removeReplica(String host) throws SQLException;
    void removeReplica(String host, boolean closeGently) throws SQLException;

    // Check if host is a replica
    boolean isHostReplica(String host);
}

public class ReplicationMySQLConnection extends MultiHostMySQLConnection
    implements ReplicationConnection {
    // Implementation of replication connection
}

public class ReplicationConnectionProxy extends MultiHostConnectionProxy
    implements InvocationHandler {
    // Proxy for managing replication connections

    public ReplicationConnectionProxy(ConnectionUrl connectionUrl) throws SQLException;

    // Host management
    public synchronized void promoteReplicaToSource(String host) throws SQLException;
    public synchronized void removeReplica(String host) throws SQLException;
    public synchronized void removeSourceHost(String host) throws SQLException;
    public synchronized void addReplicaHost(String host) throws SQLException;
    public synchronized void addSourceHost(String host) throws SQLException;
}

Usage:

// URL format: jdbc:mysql:replication://source1:3306,replica1:3306,replica2:3306/database
String url = "jdbc:mysql:replication://" +
             "source:3306,replica1:3306,replica2:3306/mydb" +
             "?loadBalanceStrategy=random";

Connection conn = DriverManager.getConnection(url, "root", "password");

// Cast to ReplicationConnection for management
ReplicationConnection replConn = conn.unwrap(ReplicationConnection.class);

// Default: routes writes to source, reads to replicas
conn.setAutoCommit(false);
Statement stmt = conn.createStatement();

// This goes to source
stmt.executeUpdate("INSERT INTO users (name) VALUES ('Alice')");

// Set read-only to route to replicas
conn.setReadOnly(true);

// This goes to replica
ResultSet rs = stmt.executeQuery("SELECT * FROM users");
while (rs.next()) {
    System.out.println(rs.getString("name"));
}

// Promote replica to source (e.g., after source failure)
replConn.promoteReplicaToSource("replica1:3306");

// Add new replica
replConn.addReplicaHost("replica3:3306");

// Remove replica
replConn.removeReplica("replica2:3306");

conn.commit();
conn.close();

Replication Connection Groups

Management of replication connection groups for dynamic reconfiguration.

package com.mysql.cj.jdbc.ha;

public class ReplicationConnectionGroup {
    // Constructor
    public ReplicationConnectionGroup(String groupName);

    // Get group name
    public String getGroupName();

    // Get source hosts
    public Collection<String> getSourceHosts();

    // Get replica hosts
    public Collection<String> getReplicaHosts();

    // Add source host
    public void addSourceHost(String hostPortPair);

    // Add replica host
    public void addReplicaHost(String hostPortPair);

    // Remove source host
    public void removeSourceHost(String hostPortPair);

    // Remove replica host
    public void removeReplicaHost(String hostPortPair);

    // Promote replica to source
    public void promoteReplica(String hostPortPair);

    // Get active connections count
    public int getConnectionCount();

    // Get active connections count for source
    public long getConnectionCountWithHostAsSource(String hostPortPair);

    // Get active connections count for replica
    public long getConnectionCountWithHostAsReplica(String hostPortPair);

    // Get number of replica hosts
    public int getReplicaHostsSize();

    // Get number of source hosts
    public int getSourceHostsSize();
}

public class ReplicationConnectionGroupManager {
    // Get connection group by name
    public static ReplicationConnectionGroup getConnectionGroup(String groupName);

    // Get all connection groups
    public static Collection<ReplicationConnectionGroup> getConnectionGroups();

    // Add replica host to group
    public static void addReplicaHost(String groupName, String hostPortPair)
        throws SQLException;

    // Add source host to group
    public static void addSourceHost(String groupName, String hostPortPair)
        throws SQLException;

    // Remove replica host from group
    public static void removeReplicaHost(String groupName, String hostPortPair)
        throws SQLException;

    // Remove replica host from group and wait
    public static void removeReplicaHost(String groupName, String hostPortPair,
                                        boolean closeGently) throws SQLException;

    // Promote replica to source
    public static void promoteReplicaToSource(String groupName, String hostPortPair)
        throws SQLException;

    // Remove source host from group
    public static void removeSourceHost(String groupName, String hostPortPair)
        throws SQLException;

    // Remove source host from group and wait
    public static void removeSourceHost(String groupName, String hostPortPair,
                                       boolean closeGently) throws SQLException;

    // Get number of source hosts
    public static int getSourceHostsCount(String groupName);

    // Get number of replica hosts
    public static int getReplicaHostsCount(String groupName);

    // Get number of active connections
    public static long getActiveConnectionCount(String groupName);

    // Get number of active source connections
    public static long getActiveSourceConnectionCount(String groupName, String hostPortPair);

    // Get number of active replica connections
    public static long getActiveReplicaConnectionCount(String groupName, String hostPortPair);
}

Usage:

// Create connection with group name
String url = "jdbc:mysql:replication://source:3306,replica1:3306/mydb" +
             "?replicationConnectionGroup=mygroup";

Connection conn = DriverManager.getConnection(url, "root", "password");

// Manage group dynamically
ReplicationConnectionGroup group =
    ReplicationConnectionGroupManager.getConnectionGroup("mygroup");

// Add new replica
ReplicationConnectionGroupManager.addReplicaHost("mygroup", "replica2:3306");

// Promote replica to source (e.g., during failover)
ReplicationConnectionGroupManager.promoteReplicaToSource("mygroup", "replica1:3306");

// Remove failed source
ReplicationConnectionGroupManager.removeSourceHost("mygroup", "source:3306", true);

// Get connection counts
long sourceConnections =
    ReplicationConnectionGroupManager.getActiveSourceConnectionCount(
        "mygroup", "replica1:3306"
    );
System.out.println("Active source connections: " + sourceConnections);

Connection Groups

Generic connection group management for load-balanced connections.

package com.mysql.cj.jdbc.ha;

public class ConnectionGroup {
    // Constructor
    public ConnectionGroup(String groupName);

    // Get group name
    public String getGroupName();

    // Get initial hosts
    public Collection<String> getInitialHosts();

    // Get initial hosts size
    public int getInitialHostsSize();

    // Get active hosts
    public Collection<String> getActiveHosts();

    // Get active hosts size
    public int getActiveHostsSize();

    // Get closed hosts
    public Collection<String> getClosedHosts();

    // Add host to group
    public void addHost(String hostPortPair, boolean forExisting);

    // Remove host from group
    public void removeHost(String hostPortPair);

    // Get connection count for host
    public long getConnectionCount(String hostPortPair);

    // Get total connection count
    public long getTotalConnectionCount();
}

public class ConnectionGroupManager {
    // Register connection group
    public static synchronized void registerConnectionGroup(String groupName,
                                                           ConnectionGroup group);

    // Get connection group
    public static ConnectionGroup getConnectionGroup(String groupName);

    // Get all connection groups
    public static Collection<ConnectionGroup> getConnectionGroups();

    // Add host to group
    public static void addHost(String groupName, String hostPortPair, boolean forExisting);

    // Remove host from group
    public static void removeHost(String groupName, String hostPortPair) throws SQLException;

    // Get connection count for host
    public static long getConnectionCountForHost(String groupName, String hostPortPair);

    // Get total connection count for group
    public static long getActiveConnectionCount(String groupName);

    // Get number of active hosts
    public static int getActiveHostsCount(String groupName);
}

Usage:

// Create load-balanced connection with group
String url = "jdbc:mysql:loadbalance://server1:3306,server2:3306/mydb" +
             "?loadBalanceConnectionGroup=lbgroup";

Connection conn = DriverManager.getConnection(url, "root", "password");

// Manage connection group
ConnectionGroup group = ConnectionGroupManager.getConnectionGroup("lbgroup");

// Add host to existing connections
ConnectionGroupManager.addHost("lbgroup", "server3:3306", true);

// Remove host from group
ConnectionGroupManager.removeHost("lbgroup", "server2:3306");

// Get statistics
long hostConnections =
    ConnectionGroupManager.getConnectionCountForHost("lbgroup", "server1:3306");
long totalConnections = ConnectionGroupManager.getActiveConnectionCount("lbgroup");
int activeHosts = ConnectionGroupManager.getActiveHostsCount("lbgroup");

System.out.println("Connections to server1: " + hostConnections);
System.out.println("Total connections: " + totalConnections);
System.out.println("Active hosts: " + activeHosts);

Failover Connections

Automatic failover support for connection reliability.

package com.mysql.cj.jdbc.ha;

public class FailoverConnectionProxy extends MultiHostConnectionProxy
    implements InvocationHandler {
    // Proxy for managing failover connections

    public FailoverConnectionProxy(ConnectionUrl connectionUrl) throws SQLException;

    // Failover occurs automatically on connection failure
    // Tries each configured host in sequence
    // Transparently reconnects when needed
}

Usage:

// URL format: jdbc:mysql://primary:3306,secondary:3306/database
String url = "jdbc:mysql://primary:3306,secondary:3306/mydb" +
             "?autoReconnect=true" +
             "&failOverReadOnly=false";

Connection conn = DriverManager.getConnection(url, "root", "password");

// Failover happens automatically on connection failure
try {
    Statement stmt = conn.createStatement();
    ResultSet rs = stmt.executeQuery("SELECT * FROM users");
    // If primary fails, automatically fails over to secondary
} catch (SQLException e) {
    // Handle persistent failure
}

Multi-Host Base Classes

Base classes for multi-host connection implementations.

package com.mysql.cj.jdbc.ha;

public abstract class MultiHostConnectionProxy implements InvocationHandler {
    // Base proxy class for multi-host connections

    protected ConnectionUrl connectionUrl;
    protected List<String> hostsList;

    public MultiHostConnectionProxy(ConnectionUrl connectionUrl) throws SQLException;

    // Invoke method on current connection
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable;

    // Execute on current connection
    protected synchronized Object invokeMore(Object proxy, Method method, Object[] args)
        throws Throwable;

    // Deal with invocation exceptions
    protected void dealWithInvocationException(InvocationTargetException e) throws Throwable;
}

public class MultiHostMySQLConnection implements JdbcConnection {
    // Base connection class for multi-host connections

    protected MultiHostConnectionProxy thisAsProxy;

    public MultiHostMySQLConnection(MultiHostConnectionProxy proxy);

    // Implements all JdbcConnection methods by delegating to proxy
    // Provides common functionality for load-balanced and replication connections
}

JMX Management Beans

JMX MBeans for monitoring and managing connection groups.

package com.mysql.cj.jdbc.jmx;

public interface LoadBalanceConnectionGroupManagerMBean {
    // JMX interface for load balance connection group management

    // Get active host count
    int getActiveHostCount(String groupName);

    // Get total connection count
    long getTotalConnectionCount(String groupName);

    // Get connection count for specific host
    long getActiveConnectionCount(String groupName, String host);

    // Add host to group
    void addHost(String groupName, String host, boolean forExisting);

    // Remove host from group
    void removeHost(String groupName, String host) throws SQLException;
}

public class LoadBalanceConnectionGroupManager implements LoadBalanceConnectionGroupManagerMBean {
    // JMX implementation for load balance connection group management

    public int getActiveHostCount(String groupName);
    public long getTotalConnectionCount(String groupName);
    public long getActiveConnectionCount(String groupName, String host);
    public void addHost(String groupName, String host, boolean forExisting);
    public void removeHost(String groupName, String host) throws SQLException;
}

public interface ReplicationGroupManagerMBean {
    // JMX interface for replication group management

    // Add replica host
    void addReplicaHost(String groupName, String host) throws SQLException;

    // Remove replica host
    void removeReplicaHost(String groupName, String host) throws SQLException;

    // Promote replica to source
    void promoteReplicaToSource(String groupName, String host) throws SQLException;

    // Remove source host
    void removeSourceHost(String groupName, String host) throws SQLException;

    // Get source host count
    int getSourceHostsCount(String groupName);

    // Get replica host count
    int getReplicaHostsCount(String groupName);

    // Get active source connection count
    long getActiveSourceConnectionCount(String groupName, String host);

    // Get active replica connection count
    long getActiveReplicaConnectionCount(String groupName, String host);

    // Get total active connection count
    long getActiveConnectionCount(String groupName);
}

public class ReplicationGroupManager implements ReplicationGroupManagerMBean {
    // JMX implementation for replication group management

    public void addReplicaHost(String groupName, String host) throws SQLException;
    public void removeReplicaHost(String groupName, String host) throws SQLException;
    public void promoteReplicaToSource(String groupName, String host) throws SQLException;
    public void removeSourceHost(String groupName, String host) throws SQLException;
    public int getSourceHostsCount(String groupName);
    public int getReplicaHostsCount(String groupName);
    public long getActiveSourceConnectionCount(String groupName, String host);
    public long getActiveReplicaConnectionCount(String groupName, String host);
    public long getActiveConnectionCount(String groupName);
}

Usage with JMX:

// Register MBeans with JMX server
MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();

// Register load balance manager
LoadBalanceConnectionGroupManager lbManager = new LoadBalanceConnectionGroupManager();
ObjectName lbName = new ObjectName(
    "com.mysql.cj.jdbc.jmx:type=LoadBalanceConnectionGroupManager"
);
mbs.registerMBean(lbManager, lbName);

// Register replication manager
ReplicationGroupManager replManager = new ReplicationGroupManager();
ObjectName replName = new ObjectName(
    "com.mysql.cj.jdbc.jmx:type=ReplicationGroupManager"
);
mbs.registerMBean(replManager, replName);

// Now can manage via JMX console or programmatically
// Example: Add host via JMX
mbs.invoke(
    lbName,
    "addHost",
    new Object[]{"mygroup", "newserver:3306", true},
    new String[]{"java.lang.String", "java.lang.String", "boolean"}
);

Install with Tessl CLI

npx tessl i tessl/maven-com-mysql--mysql-connector-j

docs

jdbc-high-availability.md

logging-monitoring.md

tessl/maven-com-mysql--mysql-connector-j