2.2.2 Connecting to One of Multiple Hosts and Connection Failover

You can provide multiple MySQL Router or server endpoints (as host and an optional port, or Unix sockets) when creating a session. You specify a URI-like string which contains multiple hosts, ports, and optional priority. This enables the connector to perform automatic connection failover selection when any of the endpoints are not available. When multiple endpoints are available, the choice of which server is used for the session depends on whether you specify priority. If a priority is specified for each endpoint, the available endpoint with the highest priority is used. If you do not specify priority, a random available endpoint is used. This section describes how to configure multiple endpoints in a URI-like string. For more information on URI-like connection strings, see Connecting Using URI-Like Connection Strings.

Note

The user and password you supply in the URI-like string apply to all of the possible endpoints and therefore the same MySQL account must exist on each of the endpoints.

To specify multiple hosts without priority, the URI-like connection string is formatted as:

user:password@[(address=[host]:[port]), (address=[host]:[port]) ..]

The collection of endpoints is listed as either host, port, or host and port. When setting up multiple endpoints without priority, any of the available endpoints is chosen for the connection.

To specify priorities for the endpoints, the URI-like connection string is formatted as:

user:password@[(address=[host]:[port], priority=value), (address=[host]:[port], priority=value) ..]

This sets up endpoints with explicit priority, for example to failover the connection to a specific endpoint in the event of another endpoint not being available. Specified priorities can range from 0 (lowest priority) to 100 (highest priority). When two endpoints share the same priority, one of them is chosen randomly.

For example, suppose you connect using an URI-like string such as:

mysqlx://user:password@[(address=example1.com:33060,priority=99),(address=example2.com:33060,priority=100)]

In this case, there are two possible endpoints, and example2:33060 has a higher priority. When both endpoints are available, the connector connects to example2.com:33060. In the event that example2.com:33060 is not available, the connector connects to example1:33060.