Database Failover

Overview

Since version 4.0.2, JBoss supports database failover for local and XA datasources. What does that actually mean? It means that when a user calls javax.sql.DataSource.getConnection() and the connection to the database could not be allocated (or it was pooled and became invalid), the connection factory will (transparently to the user) choose another database connection URL, try to allocate a connection using it and, in case of success, return the connection back to the user.

This functionality is supported for both local datasources and datasources that implement XA interface.

What policy is used to select the next URL during failover?

It's sticky round-robin. It means that first we try the first connection URL in the list. If it worked, we stick to it until it fails. When it fails, we try the second one and if it worked, we stick to it. And so on. When the last URL in the list was tried and it failed, we will come back to the first URL again, then the second and so on. If for a connection request we tried all the URLs in the list and none worked, an exception will be thrown with a message saying that none of the URLs worked.

How to deploy

1. Deploy HA managed connection factories

There are special managed connection factories for datasources that support failover. These connection factories are deployed as resource adapters (RAR packaged). So, the first step is to deploy these resource adapters that are not deployed in the default configuration.

In  directory you will find  and  packages that contain resource adapters for local and XA datasources that support failover. Depending on whether you are going to use local or XA datasources, or both of them, just copy one or both of the packages to the server's  directory.

2. Configure the datasource for failover

Both, local and XA datasources, are configured in a -ds.xml file.

2.1. Configure local datasource for failover

The root element for local datasources that support failover is ha-local-tx-datasource which has only one new element that is not present in local-tx-datasource: url-delimiter which contains a string that is used as a delimeter between URLs in connection-url element.

For example:

   <ha-local-tx-datasource>
      <jndi-name>HADefaultDS</jndi-name>

      <!-- list of connection URLs -->
      <connection-url>jdbc:hsqldb:hsql://host1:1702|jdbc:hsqldb:hsql://host2:1703|...</connection-url>
      <url-delimiter>|</url-delimiter>

      <!-- The driver class -->
      <driver-class>org.hsqldb.jdbcDriver</driver-class>
      <!-- The login and password -->
      <user-name>sa</user-name>
      <password></password>

      <!-- this will be run before a managed connection is removed from the pool for use by a client-->
      <check-valid-connection-sql>select count(*) from a</check-valid-connection-sql>
   </ha-local-tx-datasource>

2.2. Configure XA datasource for failover

The root element for XA datasources that support failover is ha-xa-datasource. This element has two additional elements not present in xa-datasource. The first is url-property which defines the name of an xa-datasource-property that contains the list of URLs. And the second one is url-delimiter the definition of which is exactly the same as for the ha-local-tx-datasource.

For example:

   <ha-xa-datasource>
      <jndi-name>MockedHaXaDS</jndi-name>
      <track-connection-by-tx></track-connection-by-tx>
      <isSameRM-override-value>false</isSameRM-override-value>
      <xa-datasource-class>org.jboss.test.jca.adapter.MockedXADataSource</xa-datasource-class>

      <!-- list of connection URLs -->
      <xa-datasource-property name="URL">haXaUrl1|haXaUrl2</xa-datasource-property>

      <url-property>URL</url-property>
      <url-delimiter>|</url-delimiter>
      <check-valid-connection-sql>VALUES CURRENT TIMESTAMP</check-valid-connection-sql>
   </ha-xa-datasource>

Note: both examples include <check-valid-connection-sql>. Checking whether the connection is valid before it is given to the caller is required for transparent failover.

Tests

Testcases for this functionality can be found in JBoss' testsuite in org.jboss.test.jca.test.HAConnectionFactoryUnitTestCase.

4.2 Changes

  As of JBoss 4.2.x the url-delimeter property has been updated to fix the typo. The property is now correctly named url-delimiter.

5.0 Changes

  As of JBoss 5.0.x the url-delimeter property has been added to the main datasource configuration.  The ha-local-tx-datasource and ha-xa-datasource elements are no longer supported in -ds.xml configuration files as you can simply use the url-delimiter property on "regular" datasources and provide multiple connection URLs.