Documentation Home
Connectors and APIs Manual
Download this Manual
PDF (US Ltr) - 4.1Mb
PDF (A4) - 4.1Mb


3.5.3.12 High Availability and Clustering

  • autoReconnect

    Should the driver try to re-establish stale and/or dead connections? If enabled the driver will throw an exception for queries issued on a stale or dead connection, which belong to the current transaction, but will attempt reconnect before the next query issued on the connection in a new transaction. The use of this feature is not recommended, because it has side effects related to session state and data consistency when applications don't handle SQLExceptions properly, and is only designed to be used when you are unable to configure your application to handle SQLExceptions resulting from dead and stale connections properly. Alternatively, as a last option, investigate setting the MySQL server variable 'wait_timeout' to a high value, rather than the default of 8 hours.

    Default Value false
    Since Version 1.1
  • autoReconnectForPools

    Use a reconnection strategy appropriate for connection pools?

    Default Value false
    Since Version 3.1.3
  • failOverReadOnly

    When failing over in 'autoReconnect' mode, should the connection be set to 'read-only'?

    Default Value true
    Since Version 3.0.12
  • maxReconnects

    Maximum number of reconnects to attempt if 'autoReconnect' is "true".

    Default Value 3
    Since Version 1.1
  • reconnectAtTxEnd

    If 'autoReconnect' is set to "true", should the driver attempt reconnections at the end of every transaction?

    Default Value false
    Since Version 3.0.10
  • retriesAllDown

    When using load balancing or failover, the number of times the driver should cycle through available hosts, attempting to connect. Between cycles, the driver will pause for 250 ms if no servers are available.

    Default Value 120
    Since Version 5.1.6
  • initialTimeout

    If 'autoReconnect' is enabled, the initial time to wait between re-connect attempts (in seconds, defaults to "2").

    Default Value 2
    Since Version 1.1
  • queriesBeforeRetrySource

    When using multi-host failover, the number of queries to issue before falling back to the primary host when failed over. Whichever condition is met first, 'queriesBeforeRetrySource' or 'secondsBeforeRetrySource' will cause an attempt to be made to reconnect to the primary host. Setting both properties to "0" disables the automatic fall back to the primary host at transaction boundaries.

    Default Value 50
    Since Version 3.0.2
  • secondsBeforeRetrySource

    How long, in seconds, should the driver wait when failed over, before attempting to reconnect to the primary host? Whichever condition is met first, 'queriesBeforeRetrySource' or 'secondsBeforeRetrySource' will cause an attempt to be made to reconnect to the source host. Setting both properties to "0" disables the automatic fall back to the primary host at transaction boundaries.

    Default Value 30
    Since Version 3.0.2
  • allowReplicaDownConnections

    By default, a replication-aware connection will fail to connect when configured replica hosts are all unavailable at initial connection. Setting this property to "true" allows to establish the initial connection. It won't prevent failures when switching to replicas i.e. by setting the replication connection to read-only state. The property 'readFromSourceWhenNoReplicas' should be used for this purpose.

    Default Value false
    Since Version 6.0.2
  • allowSourceDownConnections

    By default, a replication-aware connection will fail to connect when configured source hosts are all unavailable at initial connection. Setting this property to "true" allows to establish the initial connection, by failing over to the replica servers, in read-only state. It won't prevent subsequent failures when switching back to the source hosts i.e. by setting the replication connection to read/write state.

    Default Value false
    Since Version 5.1.27
  • ha.enableJMX

    Enables JMX-based management of load-balanced connection groups, including live addition/removal of hosts from load-balancing pool. Enables JMX-based management of replication connection groups, including live replica promotion, addition of new replicas and removal of source or replica hosts from load-balanced source and replica connection pools.

    Default Value false
    Since Version 5.1.27
  • loadBalanceHostRemovalGracePeriod

    Sets the grace period to wait for a host being removed from a load-balanced connection, to be released when it is currently the active host.

    Default Value 15000
    Since Version 6.0.3
  • readFromSourceWhenNoReplicas

    Replication-aware connections distribute load by using the source hosts when in read/write state and by using the replica hosts when in read-only state. If, when setting the connection to read-only state, none of the replica hosts are available, an 'SQLException' is thrown back. Setting this property to "true" allows to fail over to the source hosts, while setting the connection state to read-only, when no replica hosts are available at switch instant.

    Default Value false
    Since Version 6.0.2
  • selfDestructOnPingMaxOperations

    If set to a non-zero value, the driver will report close the connection and report failure when 'com.mysql.cj.jdbc.JdbcConnection.ping()' or 'java.sql.Connection.isValid(int)' is called if the connection's count of commands sent to the server exceeds this value.

    Default Value 0
    Since Version 5.1.6
  • selfDestructOnPingSecondsLifetime

    If set to a non-zero value, the driver will close the connection and report failure when 'com.mysql.cj.jdbc.JdbcConnection.ping()' or 'java.sql.Connection.isValid(int)' is called if the connection's lifetime exceeds this value, specified in milliseconds.

    Default Value 0
    Since Version 5.1.6
  • ha.loadBalanceStrategy

    If using a load-balanced connection to connect to SQL servers in a MySQL Cluster configuration (by using the URL prefix "jdbc:mysql:loadbalance://"), which load balancing algorithm should the driver use: (1) "random" - the driver will pick a random host for each request. This tends to work better than round-robin, as the randomness will somewhat account for spreading loads where requests vary in response time, while round-robin can sometimes lead to overloaded nodes if there are variations in response times across the workload. (2) "bestResponseTime" - the driver will route the request to the host that had the best response time for the previous transaction. (3) "serverAffinity" - the driver initially attempts to enforce server affinity while still respecting and benefiting from the fault tolerance aspects of the load-balancing implementation. The server affinity ordered list is provided using the property 'serverAffinityOrder'. If none of the servers listed in the affinity list is responsive, the driver then refers to the "random" strategy to proceed with choosing the next server.

    Default Value random
    Since Version 5.0.6
  • loadBalanceAutoCommitStatementRegex

    When load-balancing is enabled for auto-commit statements (via 'loadBalanceAutoCommitStatementThreshold'), the statement counter will only increment when the SQL matches the regular expression. By default, every statement issued matches.

    Since Version 5.1.15
  • loadBalanceAutoCommitStatementThreshold

    When auto-commit is enabled, the number of statements which should be executed before triggering load-balancing to rebalance. Default value of "0" causes load-balanced connections to only rebalance when exceptions are encountered, or auto-commit is disabled and transactions are explicitly committed or rolled back.

    Default Value 0
    Since Version 5.1.15
  • loadBalanceBlocklistTimeout

    Time in milliseconds between checks of servers which are unavailable, by controlling how long a server lives in the global blocklist.

    Default Value 0
    Since Version 5.1.0
  • loadBalanceConnectionGroup

    Logical group of load-balanced connections within a class loader, used to manage different groups independently. If not specified, live management of load-balanced connections is disabled.

    Since Version 5.1.13
  • loadBalanceExceptionChecker

    Fully-qualified class name of custom exception checker. The class must implement 'com.mysql.cj.jdbc.ha.LoadBalanceExceptionChecker' interface, and is used to inspect 'SQLException' exceptions and determine whether they should trigger fail-over to another host in a load-balanced deployment.

    Default Value com.mysql.cj.jdbc.ha.StandardLoadBalanceExceptionChecker
    Since Version 5.1.13
  • loadBalancePingTimeout

    Time in milliseconds to wait for ping responses from each of load-balanced physical connections when using a load-balanced connection.

    Default Value 0
    Since Version 5.1.13
  • loadBalanceSQLExceptionSubclassFailover

    Comma-delimited list of classes/interfaces used by default load-balanced exception checker to determine whether a given 'SQLException' should trigger a failover. The comparison is done using 'Class.isInstance(SQLException)' using the 'SQLException' thrown.

    Since Version 5.1.13
  • loadBalanceSQLStateFailover

    Comma-delimited list of 'SQLState' codes used by the default load-balanced exception checker to determine whether a given 'SQLException' should trigger a failover. The 'SQLState' of a given 'SQLException' is evaluated to determine whether it begins with any of the values specified in the comma-delimited list.

    Since Version 5.1.13
  • loadBalanceValidateConnectionOnSwapServer

    Should the load-balanced connection explicitly check whether the connection is live when swapping to a new physical connection at commit/rollback?

    Default Value false
    Since Version 5.1.13
  • pinGlobalTxToPhysicalConnection

    When using XA connections, should the driver ensure that operations on a given XID are always routed to the same physical connection? This allows the 'XAConnection' to support "XA START ... JOIN" after "XA END" has been called.

    Default Value false
    Since Version 5.0.1
  • replicationConnectionGroup

    Logical group of replication connections within a class loader, used to manage different groups independently. If not specified, live management of replication connections is disabled.

    Since Version 8.0.7
  • resourceId

    A globally unique name that identifies the resource that this data source or connection is connected to, used for 'XAResource.isSameRM()' when the driver can't determine this value based on hostnames used in the URL.

    Since Version 5.0.1
  • serverAffinityOrder

    A comma separated list containing the host/port pairs that are to be used in load-balancing "serverAffinity" strategy. Only the sub-set of the hosts enumerated in the main hosts section in this URL will be used and they must be identical in case and type, i.e., can't use an IP address in one place and the corresponding host name in the other.

    Since Version 8.0.8