Configuring client reroute for applications that use DB2 databases

You can use the client reroute feature to configure your enterprise applications for a database to recover from a communication loss, and the applications can continue to work with minimal interruption. Rerouting is central to the support of continuous operations, but in some scenarios, rerouting is only possible when there is an alternative database server that is identified to the application server connection.

Before you begin

This task assumes that:

  • The DB2® data source to which your application connects is running:
    • DB2 for z/OS® Version 10.1 or later or
    • DB2 Database for Linux®, UNIX, and Windows Version 9.7 or later
    • DB2 for z/OS Version 10.1 or later or
    • DB2 Database for Linux, UNIX, and Windows Version 9.7 or later
    • DB2 for z/OS Version 10.1 or later or
    • DB2 Database for Linux, UNIX, and Windows Version 9.7 or later
  • You configured the DB2 database with a redundant setup or the ability to fail the DB2 server to a standby node.

About this task

You can use client reroute for DB2 to provide information about alternative servers in case the connection to the primary database server fails.

Without any configuration on the client side, the Java™ Common Connectivity (JCC) Java Database Connectivity (JDBC) driver for DB2 supports the client reroute capability, if it is enabled on the DB2 server, when the driver makes an initial connection to the DB2 server. When the JCC JDBC driver connects to a DB2 server that has one or more alternative servers that are configured, the primary server sends information about the alternative servers to the JCC JDBC driver. If the connection to the primary server fails, the JCC JDBC driver is able to reroute connections to an alternative server. If the application server process crashes, however, the alternative server information is lost and the client needs to connect to the primary server again. If the client cannot make an initial connection to the primary server, the client has no knowledge of the alternative servers and cannot reroute.

To overcome this problem, you can configure a DB2 data source in the application server with the Alternate server name and Alternate port number fields, or with the clientRerouteAlternateServerName and clientRerouteAlternatePortNumber data source custom properties, to support client reroute even on the initial connection attempt. If the JDBC driver is not able to connect to the primary DB2 server, the information that is necessary for a client reroute is already present, and the JDBC driver can reroute the connection to an alternate server.

Attention: The data source custom property, enableClientAffinitiesList, changes the semantics of the clientRerouteAlternateServerName and clientRerouteAlternatePortNumber properties.

When a connection is rerouted and the JCC JDBC driver is connected to the alternative DB2 server, the alternative server sends information about its own alternative server to the JCC JDBC driver. The JCC JDBC driver then has the information that is required to reroute the connection again if the alternative DB2 server is not available. The server that was originally the alternative server is now the primary server, and a new alternative server is established. However, this new state of the primary and alternative servers is no longer kept by the JCC JDBC driver. If the application server fails and is restarted, the JCC JDBC driver must start from the original server configuration and attempt to connect to the server that was originally considered the primary server.

You can use the automatic client rerouting feature within the following DB2 configurable environments:

Procedure

  1. Define your DB2 data source in the server.xml file with the following properties:
    • clientRerouteAlternateServerName
      • Type of valid values:
        • Domain name; for example: www.ibm.com
        • IP address (IPv4 and IPv6); for example: 23.72.11.219
      • Format of multiple values:
        • Comma separated; for example: host1, host2, host3
        • Space separated; for example: host1 host2 host3
      • Order significance:
        • The order of the provided host names is the order that the JCC JDBC driver uses to try to find the next available server to connect to.
    • clientRerouteAlternatePortNumber
      • Type of valid values:
        • Integer representing the port number; for example: 50000
      • Format of multiple values:
        • Comma separated; for example: port1, port2, port3
        • Space separated; for example: port1 port2 port3
      • Order significance:
        • The order of the provided ports must match the order of their associated servers.
  2. (Optional) You can add one or both of the following properties:
    • retryIntervalForClientReroute

      This property defines the number of seconds the JCC JDBC driver waits between each attempt to establish a connection.

      If no value is assigned, the default behavior is used. To learn more, see JDBC and SQL support.

    • maxRetriesForClientReroute

      This property defines the number of retries the JCC JDBC driver attempts to connect the server before it decides to move on to the next server. This property is only used when RetryIntervalForClientReroute property is set.

      If no value is assigned, the default behavior is used. To learn more, see JDBC and SQL support.

Example

<dataSource id="DefaultDataSource"jndiName="jdbc/db2">
     <properties.db2.jcc 
        databaseName="sampleDatabase"
        driverType="4"
        serverName="host"
        portNumber="50000"
        clientRerouteAlternateServerName="host01, host02, host03"
        clientRerouteAlternatePortNumber="50000, 50005, 50000"
        retryIntervalForClientReroute="2"
        maxRetriesForClientReroute="3" />
 ...
</dataSource>
Note: Ensure that an equal number of entries is specified for both ports and hosts. Otherwise, a warning is displayed and client reroute is not enabled.