com.mysql.cj.jdbc.ha.plugins.failover

Class AuroraTopologyService

java.lang.Object

com.mysql.cj.jdbc.ha.plugins.failover.AuroraTopologyService

All Implemented Interfaces:

ITopologyService

public class AuroraTopologyService
extends java.lang.Object
implements ITopologyService

An implementation of topology service for Aurora RDS. It uses information_schema.replica_host_status table to obtain cluster topology and caches it. Different instances of this service with the same 'clusterId' shares the same topology cache. Cache also includes a list of down hosts. That helps to avoid unnecessary attempts to connect them.

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	clusterId
protected HostInfo	clusterInstanceTemplate
static CacheMap<java.lang.String,java.util.Set<java.lang.String>>	downHostCache
static CacheMap<java.lang.String,HostInfo>	lastUsedReaderCache
protected Log	log The logger we're going to use.
protected IClusterAwareMetricsContainer	metricsContainer
static CacheMap<java.lang.String,java.lang.Boolean>	multiWriterClusterCache
protected static Log	NULL_LOGGER Null logger shared by all connections at startup.
static CacheMap<java.lang.String,java.util.List<HostInfo>>	topologyCache

Constructor Summary

Constructors

Constructor and Description
AuroraTopologyService(int refreshRateInMilliseconds, Log log, java.util.function.Supplier<IClusterAwareMetricsContainer> metricsContainerSupplier) Initializes a service with provided topology refresh rate.
AuroraTopologyService(Log log) Initializes a service with topology default refresh rate.

Method Summary

Modifier and Type	Method and Description
void	addToDownHostList(HostInfo downHost) Mark host as down.
void	clear() Clear topology cache for the current cluster.
void	clearAll() Clear topology cache for all clusters.
java.util.List<HostInfo>	getCachedTopology() Get cached topology.
java.lang.String	getClusterId() Returns the unique cluster identifier for topology service instance
java.util.Set<java.lang.String>	getDownHosts() Get a set of instance names that were marked down.
HostInfo	getHostByName(JdbcConnection conn) Return the HostInfo object that is associated with a provided connection from the topology host list.
HostInfo	getLastUsedReaderHost() Get details about the most recent reader that the driver has successfully connected to.
java.util.List<HostInfo>	getTopology(JdbcConnection conn, boolean forceUpdate) Get cluster topology.
boolean	isMultiWriterCluster() Check if cached topology belongs to multi-writer cluster.
protected com.mysql.cj.jdbc.ha.plugins.failover.AuroraTopologyService.ClusterTopologyInfo	queryForTopology(JdbcConnection conn) Query the database for the cluster topology and use the results to record information about the topology.
void	removeFromDownHostList(HostInfo host) Unmark host as down.
void	setClusterId(java.lang.String clusterId) Sets cluster Id for a service instance.
void	setClusterInstanceTemplate(HostInfo clusterInstanceTemplate) Sets host details common to each instance in the cluster, including the host dns pattern.
void	setLastUsedReaderHost(HostInfo reader) Set details about the most recent reader that the driver has connected to.
void	setRefreshRate(int refreshRateMillis) Set new topology refresh rate.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

topologyCache

public static final CacheMap<java.lang.String,java.util.List<HostInfo>> topologyCache

downHostCache

public static final CacheMap<java.lang.String,java.util.Set<java.lang.String>> downHostCache

lastUsedReaderCache

public static final CacheMap<java.lang.String,HostInfo> lastUsedReaderCache

multiWriterClusterCache

public static final CacheMap<java.lang.String,java.lang.Boolean> multiWriterClusterCache

clusterId

protected java.lang.String clusterId

clusterInstanceTemplate

protected HostInfo clusterInstanceTemplate

metricsContainer

protected IClusterAwareMetricsContainer metricsContainer

NULL_LOGGER

protected static final Log NULL_LOGGER

Null logger shared by all connections at startup.

log

protected transient Log log

The logger we're going to use.

Constructor Detail

AuroraTopologyService

public AuroraTopologyService(Log log)

Initializes a service with topology default refresh rate.

AuroraTopologyService

public AuroraTopologyService(int refreshRateInMilliseconds,
                             Log log,
                             java.util.function.Supplier<IClusterAwareMetricsContainer> metricsContainerSupplier)

Initializes a service with provided topology refresh rate.

Parameters:

refreshRateInMilliseconds - Topology refresh rate in millis

Method Detail

setClusterId

public void setClusterId(java.lang.String clusterId)

Sets cluster Id for a service instance. Different service instances with the same cluster Id share topology cache.

Specified by:

setClusterId in interface ITopologyService

Parameters:

clusterId - Topology cluster Id

getClusterId

public java.lang.String getClusterId()

Returns the unique cluster identifier for topology service instance

Specified by:

getClusterId in interface ITopologyService

Returns:

cluster Id

setClusterInstanceTemplate

public void setClusterInstanceTemplate(HostInfo clusterInstanceTemplate)

Sets host details common to each instance in the cluster, including the host dns pattern. "?" (question mark) in a host dns pattern will be replaced with a host instance name to form a fully qualified dns host endpoint.

Examples: "?.mydomain.com", "db-instance.?.mydomain.com"

Specified by:

setClusterInstanceTemplate in interface ITopologyService

Parameters:

clusterInstanceTemplate - Cluster instance details including host dns pattern.

getTopology

public java.util.List<HostInfo> getTopology(JdbcConnection conn,
                                            boolean forceUpdate)
                                     throws java.sql.SQLException

Get cluster topology. It may require an extra call to database to fetch the latest topology. A cached copy of topology is returned if it's not yet outdated (controlled by refreshRateNanos).

Specified by:

getTopology in interface ITopologyService

Parameters:

conn - A connection to database to fetch the latest topology, if needed.

forceUpdate - If true, it forces a service to ignore cached copy of topology and to fetch a fresh one.

Returns:

A list of hosts that describes cluster topology. A writer is always at position 0. Returns an empty list if topology isn't available or is invalid (doesn't contain a writer).

Throws:

java.sql.SQLException

queryForTopology

protected com.mysql.cj.jdbc.ha.plugins.failover.AuroraTopologyService.ClusterTopologyInfo queryForTopology(JdbcConnection conn)
                                                                                                    throws java.sql.SQLException

Query the database for the cluster topology and use the results to record information about the topology.

Parameters:

conn - A connection to database to fetch the latest topology.

Returns:

Cluster topology details.

Throws:

java.sql.SQLException

getCachedTopology

public java.util.List<HostInfo> getCachedTopology()

Get cached topology.

Specified by:

getCachedTopology in interface ITopologyService

Returns:

List of hosts that represents topology. If there's no topology in the cache or the cached topology is outdated, it returns null.

getLastUsedReaderHost

public HostInfo getLastUsedReaderHost()

Get details about the most recent reader that the driver has successfully connected to.

Specified by:

getLastUsedReaderHost in interface ITopologyService

Returns:

The host details of the most recent reader connection. Returns null if the driver has not connected to a reader within the refresh rate period.

setLastUsedReaderHost

public void setLastUsedReaderHost(HostInfo reader)

Set details about the most recent reader that the driver has connected to.

Specified by:

setLastUsedReaderHost in interface ITopologyService

Parameters:

reader - A reader host.

getHostByName

public HostInfo getHostByName(JdbcConnection conn)

Return the HostInfo object that is associated with a provided connection from the topology host list.

Specified by:

getHostByName in interface ITopologyService

Parameters:

conn - A connection to database.

Returns:

The HostInfo object from the topology host list. Returns null if the connection host is not found in the latest topology.

getDownHosts

public java.util.Set<java.lang.String> getDownHosts()

Get a set of instance names that were marked down.

Specified by:

getDownHosts in interface ITopologyService

Returns:

A set of instance dns names with port (example: "instance-1.my-domain.com:3306")

addToDownHostList

public void addToDownHostList(HostInfo downHost)

Mark host as down. Host stays marked down until next topology refresh.

Specified by:

addToDownHostList in interface ITopologyService

Parameters:

downHost - The HostInfo object representing the host to mark as down

removeFromDownHostList

public void removeFromDownHostList(HostInfo host)

Unmark host as down. The host is removed from the list of down hosts

Specified by:

removeFromDownHostList in interface ITopologyService

Parameters:

host - The HostInfo object representing the host to remove from the list of down hosts

isMultiWriterCluster

public boolean isMultiWriterCluster()

Check if cached topology belongs to multi-writer cluster.

Specified by:

isMultiWriterCluster in interface ITopologyService

Returns:

True, if it's multi-writer cluster.

setRefreshRate

public void setRefreshRate(int refreshRateMillis)

Set new topology refresh rate. Different service instances may have different topology refresh rate while sharing the same topology cache.

Specified by:

setRefreshRate in interface ITopologyService

Parameters:

refreshRateMillis - Topology refresh rate in millis.

clearAll

public void clearAll()

Clear topology cache for all clusters.

Specified by:

clearAll in interface ITopologyService

clear

public void clear()

Clear topology cache for the current cluster.

Specified by:

clear in interface ITopologyService