Driver Overview

The drivers tab allows you to manage the jdbc jar file that will be provided to the application or used by the proxy.

Fields

  • Version: The version ID of the driver, for reference only
  • Example URL: Used as a reference, not required
  • Writer URL: Used in handling AWS RDS cluster tracking (see below)
  • Reader URL: Used in handling AWS RDS cluster tracking (see below)
  • Website URL: Used as a reference, not required
  • JDBC Class: Required: provided by jdbc driver vendor
  • Data Source Class: Optional: used in some situations, provided by JDBC driver vendor
  • XA Data Source Class: Optional: used in some situations when using XA transactions, provided by JDBC driver vendor
  • Notes: Optional text field for notes on the driver
  • Maven ID: Optional field. Used to provide automatic download of jdbc jar file from maven central. Text should match a pattern: "groupId:artifactId:version" e.g. for mysql: mysql:mysql-connector-java:5.1.49. Jar file will be downloaded on driver creation and during update if not exists.
  • Driver Upload: Upload your driver file(s) here. If a driver happens to be incompatible with our remote download scheme, this driver file can be left blank, as long as the driver is available on the server using the Heimdall Driver itself. This is a known issue with the AWS Redshift driver.

AWS Cluster Tracking

In order to account for various configurations that may be desired, if load balancing is enabled, and cluster tracking is enabled, the reader and writer URL patterns will be used to generate the actual JDBC URL's to represent the various nodes of the cluster. The reader and write URL's can contain the following variables for substitution, which should be used based on the information extracted from the AWS configuration:

  • ${listener}: For SQL Server, this will represent the listener URL, which points to the IP that tracks between the primary writer node during a failover. Empty for non-SQL Server cluster types
  • ${writeEndpoint}: For Aurora clusters, this will point to the primary endpoint hostname, which uses DNS to fail between primary nodes.
  • ${readerEndpoint}: For Aurora clusters, this will point to the reader endpoint hostname, which uses DNS over time to spray load across reader nodes. For a single node reader setup, this is appropriate, but in multi-node reader configurations, this can result in uneven distribution.
  • ${writer}: For any cluster type, this will point to the actual active writer. If more than one writer is detected, then multiple nodes will be created, one with each writer.
  • ${writers}: Like with writer, but will fill in all writer hostnames in a comma separated list. Useful for URL types that allow multiple hosts to be included in a single URL
  • ${reader}: Generates one node per reader, including a node for the writer, for the purpose of reading. The read weight of readers will be set to 10, but the read weight of the writer will be set to 1.
  • ${readers}: Generate one reader node, with all readers in a comma seperated list. The writer(s) will be first in the list.
  • ${replica}: Include all the readers as distinct servers, not including writer nodes
  • ${replicas}: Include all the readers in one URL, not including writer nodes

If the writer URL includes the string ":replication:" AND there is only one node in the cluster, then the value for the writer will be duplicated twice in the reader list. This is to avoid a degenerate case for the MySQL driver where a "replication" url requires two hosts to be defined, or it will fail to connect to any host. By duplicating the host twice, it passes the check, and will work as expected.

Advanced

When a vendor driver is used by the Heimdall driver, we will first attempt to load the driver remotely, i.e. by downloading the driver from the central manager. This provides a single source for the drivers, simplifying the management of the drivers. If this fails, it will attempt to use the local class loader in order to find the driver. In an OSGI Java environment, it may be necessary to package the database driver with the Heimdall driver as a dependency in order for all behaviors to work as expected if the remote load feature does not work.

Proxy vs. JDBC Driver Behavior

When using Heimdall in proxy mode, it is highly recommended that the drivers provided in the Heimdall install package be used. This is as a result of the tight integration work that is done with Heimdall to operate with these drivers, and may be broken between release builds of the vendor driver. In JDBC mode, this requirement can be ignored, and the application recommended version of the drivers should be used.