Failover

The driver provides the following levels of failover protection to ensure continuous, uninterrupted access to data.

• Connection failover provides failover protection for new connections only. The driver fails over new connections to an alternate, or backup, database server if the primary database server is unavailable, for example, because of a hardware failure or traffic overload. If a connection to the database is lost, or dropped, the driver does not fail over the connection. This failover method is the default.
• Extended connection failover provides failover protection for new connections and lost database connections. If a connection to the database is lost, the driver fails over the connection to an alternate server, preserving the state of the connection at the time it was lost, but not any work in progress.
• Select Connection failover provides failover protection for new connections and lost database connections. In addition, it provides protection for Select statements that have work in progress. If a connection to the database is lost, the driver fails over the connection to an alternate server, preserving the state of the connection at the time it was lost and preserving the state of any work being performed by Select statements.

To configure failover:

• Configure the basic connection properties required for a connection:
  • Set the DatabaseName property to specify the name of the database to which you want to connect. Valid only on Db2 for Linux, UNIX, and Windows; Db2 Hosted; and Db2 Warehouse on Cloud
  • Set the LocationName property to specify the name of the Db2 location that you want to access. Valid only on Db2 for z/OS and Db2 for I.
  • Set the PortNumber property to specify the TCP port of the primary database server that is listening for connections to the database
  • Set the ServerName property to specify either the IP address in IPv4 or IPv6 format, or the server name (if your network supports named servers) of the primary database server.
• Set the AlternateServers property to specify one or multiple alternate servers.
  Note: To turn off failover, do not specify a value for the AlternateServers property.
• Set the FailoverMode connection property to one of the following failover methods. The default is connection failover (FailoverMode=connect).
  • If set to connect, the driver provides failover protection for new connections only.
  • If set to extended, the driver provides failover protection for new and lost connections, but not any work in progress.
  • If set to select, the driver provides failover protection for new and lost connections. In addition, it preserves the state of work performed by the last Select statement executed on the Statement object.
• If Extended Connection Failover (FailoverMode=extended) or Select Connection Failover (FailoverMode=select) is enabled, set the FailoverGranularity property to specify how you want the driver to behave if exceptions occur while trying to reestablish a lost connection:
  • If set to nonAtomic, the driver continues with the failover process and posts any exceptions on the statement on which they occur. This is the default value.
  • If set to atomic, the driver fails the entire failover process if an exception is generated as the result of restoring the state of the connection. The driver stops trying to connect to an alternative server and returns an exception indicating that the connection was lost. If an exception is generated as a result of restoring the state of work in progress by re-executing the Select statement, the driver continues with the failover process, but generates an exception warning that the Select statement must be reissued.
  • If set to atomicWithRepositioning, the driver fails the entire failover process if any exception is generated as the result of restoring the state of the connection or the state of work in progress. The driver stops trying to connect to an alternative server and returns an exception indicating that the connection was lost.
• Optionally, set the ConnectionRetryCount property to specify the number of times the driver retries connection attempts to the primary database server, and if specified, alternate servers until a successful connection is established. The default is 5 times.
• Optionally, set the ConnectionRetryDelay property to specify the number of seconds the driver waits between connection retry attempts. The default is 1second.
• Optionally, set the FailoverPreconnect property if you want the driver to establish a connection with the primary and an alternate server at the same time. The default behavior is to connect to an alternate server only when failover is caused by an unsuccessful connection attempt or a lost connection (FailoverPreconnect=false).

The following examples configure the driver to use connection failover in conjunction with connection retry.

Connection URL

jdbc:datadirect:db2://myserver1:50000;Database=payroll;
User=jsmith;Password=secret;AlternateServers=(myserver2:50001;
Database=account,myserver3:50002;Database=sample);
ConnectionRetryCount=2;ConnectionRetryDelay=5;

In this example:

...myserver1:50000;Database=payroll...

is the part of the connection URL that specifies connection information for the primary server. Alternate servers are specified using the AlternateServers property. For example:

...;AlternateServers=(myserver2:50001;Database=account,myserver3:50002;Database=sample)  

If a successful connection is not established on the Db2 driver’s first pass through, the list of database servers (primary and alternate), the driver retries the list of servers in the same sequence twice (ConnectionRetryCount=2). Because the connection retry delay has been set to five seconds (ConnectionRetryDelay=5), the driver waits five seconds between retry passes.

DB2DataSource mds = new DB2DataSource();
mds.setDescription("My Db2 Data Source");
mds.setServerName("myserver");
mds.setPortNumber("50000");
mds.setDatabase("payroll");
mds.setUser("jsmith");
mds.setPassword("secret");
mds.setAlternateServers("myserver2:50001;Database=account,myserver3:50002;Database=sample");