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


Connectors and APIs Manual  /  ...  /  Configuring Server Failover for Connections Using X DevAPI

3.8.2 Configuring Server Failover for Connections Using X DevAPI

When using the X Protocol, Connector/J supports a client-side failover feature for establishing a Session. If multiple hosts are specified in the connection URL, when Connector/J fails to connect to a listed host, it tries to connect to another one. This is a sample X DevAPI URL for configuring client-side failover:

mysqlx://sandy:mypassword@[host1:33060,host2:33061]/test

With the client-side failover configured, when there is a failure to establish a connection, Connector/J keeps attempting to connect to a host on the host list. The order in which the hosts are attempted for connection is as follows:

  • For connections with the priority property set for each host in the connection URL, hosts are attempted according to the set priorities for the hosts, which are specified by any numbers between 0 to 100, with a larger number indicating a higher priority for connection. For example:

    mysqlx://sandy:mypassword@[(address=host1:33060,priority=2),(address=host2:33061,priority=1)]/test

    In this example, host1 is always attempted before host2 when new sessions are created.

    Priorities should either be set for all or no hosts.

  • For connections with the priority property NOT set for each host in the connection URL:

    • For release 8.0.19 and later, hosts are attempted one after another in a random order.

    • for release 8.0.18 and earlier, hosts are attempted one after another in the order they appear in the connection URL—a host appearing earlier in the list will be attempted before a host appearing later in the list.

Notice that the server failover feature for X DevAPI only allows for a failover when Connector/J is trying to establish a connection, but not during operations after a connection has already been made.

Connection Pooling Using X DevAPI.  When using connection pooling with X DevAPI, Connector/J keeps track of any host it failed to connect to and, for a short waiting period after the failure, avoids connecting to it during the creation or retrieval of a Session. However, if all other hosts have already been tried, those excluded hosts will be retried without waiting. Once all hosts have been tried and no connections can be established, Connector/J throws a com.mysql.cj.exceptions.CJCommunicationsException and returns the message Unable to connect to any of the target hosts.

Configuring Server Failover Using X DevAPI with DNS SRV

See Section 3.5.14, “Support for DNS SRV Records” for details.