Documentation Home
MySQL Connector/J 8.0 Developer Guide
Related Documentation Download this Manual
PDF (US Ltr) - 0.8Mb
PDF (A4) - 0.8Mb
HTML Download (TGZ) - 146.6Kb
HTML Download (Zip) - 166.0Kb


MySQL Connector/J 8.0 Developer Guide  /  ...  /  High Availability and Clustering

6.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 a 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 (defaults to 'false')

    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 is '3'.

    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 loadbalancing or failover, the number of times the driver should cycle through available hosts, attempting to connect. Between cycles, the driver will pause for 250ms 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

    Number of queries to issue before falling back to the primary host when failed over (when using multi-host failover). 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. Defaults to 50.

    Default Value 50
    Since Version 3.0.2
  • secondsBeforeRetrySource

    How long 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. Time in seconds, defaults to 30

    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 Connection.ping() or 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 Connection.ping() or Connection.isValid(int) is called if the connection's lifetime exceeds this value (in milliseconds).

    Default Value 0
    Since Version 5.1.6
  • ha.loadBalanceStrategy

    If using a load-balanced connection to connect to SQL nodes in a MySQL Cluster/NDB 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 classloader, 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 SQLExceptions 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 response from each of load-balanced physical connections when using 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 failover. The comparison is done using Class.isInstance(SQLException) using the thrown SQLException.

    Since Version 5.1.13
  • loadBalanceSQLStateFailover

    Comma-delimited list of SQLState codes used by default load-balanced exception checker to determine whether a given SQLException should trigger failover. The SQLState of a given SQLException is evaluated to determine whether it begins with any value 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 XAConnections, 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 classloader, 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 datasource 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