IBM Support

WebSphere Application Server: Storing transaction and compensation logs in a relational database for high availability

Product Documentation


Abstract

You can choose to store your WebSphere Application Server transaction and compensation logs in a relational database rather than as operating system files. This feature provides high availability (HA) support without having to use a shared file system.

Content

The WebSphere Application Server transaction service writes information to a transaction log for every global transaction that involves two or more resources, or that is distributed across multiple servers. These transactions are started or stopped, either by applications or by the container in which they are deployed. The transaction service maintains transaction logs to ensure the integrity of transactions. Information is written to the transaction logs in the prepare phase of a distributed transaction. If a WebSphere Application Server with active transactions restarts after a failure, the transaction service can use the logs to replay any in-doubt transactions. The transaction service enables the overall system to return to a consistent state.

In previous releases of WebSphere Application Server, the transaction logs were stored as operating system files. In WebSphere Application Server Version 8.5.5, this remains the default configuration. You can also choose to store the transaction logs in a relational database. This configuration option is primarily used when working in a high availability (HA) environment. Also in previous releases of WebSphere Application Server, HA transaction support required the use of a shared file system to host the transaction logs, such as an NFSv4-mounted network attached storage (NAS) or a storage area network (SAN). This new feature enables you, particularly if you have an investment in HA database technology, to use your HA database as a shared repository for the transaction logs as an alternative to using a shared file system.

Note: The current implementation for storing the transaction and compensation logs in a relational database supports High Availability capabilities in DB2 and Oracle. For example, client-specific features such as DB2 HADR or Oracle RAC DataGuard, which enable reconnection to another database instance if a failure occurs, are supported. High availability capabilities in relational databases from other vendors are not currently supported.



In WebSphere Application Server Version 8.5.5, you can use a similar facility, also aimed at customers working in a HA environment, to store the compensation recovery logs in a relational database. The WebSphere Application Server compensation service enables applications on disparate systems to coordinate activities that are more loosely coupled than atomic transactions. It stores information that is necessary to perform compensation after a system failure in its own dedicated recovery logs.

Procedure

You must configure the transaction log location and the compensation log location for each server in the cluster before enabling high availability, by setting the TransactionLogDirectory and CompensationLogDirectory attributes for each server. Each server in a cluster must reference unique transaction log and compensation log locations by specifying a distinct tablesuffix property. Multiple servers do not contend for relational database management system (RDBMS) resources. For example, if you have a cluster named AppCluster with the following four member servers:

  • AppClusterMember1
  • AppClusterMember2
  • AppClusterMember3
  • AppClusterMember4
You can define the following table suffices for AppCluster:
  • App1 for AppClusterMember1
  • App2 for AppClusterMember2
  • App3 for AppClusterMember3
  • App4 for AppClusterMember4

Each server in the cluster must reference the same data source to enable peer recovery.

Complete the following steps:



1. Configure a non-transactional data source for transaction and compensation recovery log storage:

      a. Create a JDBC provider for your specific RDBMS implementation. Specify an implementation type of non-XA.

      b. Create a JAAS J2C authentication data alias. This defines the security credentials that are used to connect to the RDBMS. The credentials defined in the RDBMS must have sufficient authority to create tables in the database.

      c. Create a new data source by using the JDBC provider created in step a. Its component managed authentication alias must be set to the JAAS alias created in step b. Define the URL for your data source to specify a connection to the RDBMS.

      d. Configure the new data source to be non-transactional by completing the following steps:
          i. Open your newly created data source.
          ii. Under Additional Properties, click WebSphere Application Server data source properties.
          iii. Select the Non-transactional data source check box.
          iv. Save your changes.

2. Configure the transaction service to store transactions in a relational database:

      a. In the WebSphere Application Server administrative console, click Servers > Server Types > WebSphere application servers > server_name. The properties of the specified application serve are displayed.

      b. In the Container Settings section, click Container Services > Transaction service. The transaction service settings page is displayed.

      c. Select the Configuration tab if it is not already displayed.

      d. In the Transaction log directory field, enter a custom string to indicate that you want your logs to be stored in a database. The string must have the following format:

      custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=data_source_jndi_name,tablesuffix=suffix

      where data_source_jndi_name is the JNDI name of the non-transactional data source created previously, and suffix is a string that you must set to uniquely label each member of your HA cluster.

      Restriction: If you are using an Oracle database, the length of the suffix string must not exceed 15 characters.

3. (Optional) Configure the compensation service to store transactions in a relational database if you plan to use Compensation or Activity services in WebSphere Application Server:

      a. In the WebSphere Application Server administrative console, click Servers > Server Types > WebSphere application servers > server_name. The properties of the specified application serve are displayed.

      b. In the Container Settings section, click Container Services > Compensation service. The compensation service settings page is displayed.

      c. Select the Configuration tab if it is not already displayed.

      d. In the Recovery log directory field, enter a custom string to indicate that you want your logs to be stored in a database. The string must have the following format:

      custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=data_source_jndi_name,tablesuffix=suffix

      where data_source_jndi_name is the JNDI name of the non-transactional data source created previously, and suffix is a string that you must set to uniquely label each member of your HA cluster.

      Restriction: If you are using an Oracle database, the length of the suffix string must not exceed 15 characters.

4. (optional) Create the database tables.

WebSphere Application Server attempts to create the necessary database tables when it first starts. When this is not possible, due to insufficient permission for example, the server fails to start. Under these circumstances, you must create the required database tables manually.

The following DDL is representative and appropriate to a standalone server environment. In a standalone environment, two database tables, a transaction log and a partner log table are required to support the transaction service. If you plan to use Compensation or Activity Services, then a third compensation log table is also required.

The table names should be tailored for your environment.
For example, you must create four transaction log tables, four partner log tables and optionally, four compensation log tables if you have a cluster named AppCluster with the following four member servers:
  • AppClusterMember1
  • AppClusterMember2
  • AppClusterMember3
  • AppClusterMember4
So you can define the following tables for AppCluster:

Cluster Name Server Name Transaction Log Table Partner Log TableCompensation Log Table
AppCluster AppClusterMember1 WAS_TRAN_LOGApp1WAS_PARTNER_LOGApp1WAS_COMP_LOGApp1

AppClusterMember2 WAS_TRAN_LOGApp2WAS_PARTNER_LOGApp2WAS_COMP_LOGApp2

AppClusterMember3 WAS_TRAN_LOGApp3WAS_PARTNER_LOGApp3WAS_COMP_LOGApp3

AppClusterMember4 WAS_TRAN_LOGApp4WAS_PARTNER_LOGApp4WAS_COMP_LOGApp4



The following DDL shows how to create the database tables with the App1 table suffix on DB2:

CREATE TABLE WAS_TRAN_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID BIGINT,
 RUSECTION_ID BIGINT,
 RUSECTION_DATA_INDEX SMALLINT,
 DATA LONG VARCHAR FOR BIT DATA)


CREATE TABLE WAS_PARTNER_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID BIGINT,
 RUSECTION_ID BIGINT,
 RUSECTION_DATA_INDEX SMALLINT,
 DATA LONG VARCHAR FOR BIT DATA)


CREATE TABLE WAS_COMP_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID BIGINT,
 RUSECTION_ID BIGINT,
 RUSECTION_DATA_INDEX SMALLINT,
 DATA LONG VARCHAR FOR BIT DATA)


The following DDL structures shows how to create the database tables with the App1 table suffix on Oracle:

CREATE TABLE WAS_TRAN_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID NUMBER(19),
 RUSECTION_ID NUMBER(19),
 RUSECTION_DATA_INDEX SMALLINT,
 DATA BLOB)


CREATE TABLE WAS_PARTNER_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID NUMBER(19),
 RUSECTION_ID NUMBER(19),
 RUSECTION_DATA_INDEX SMALLINT,
 DATA BLOB)


CREATE TABLE WAS_COMP_LOGAPP1(
 SERVER_NAME VARCHAR(128),
 SERVICE_ID SMALLINT,
 RU_ID NUMBER(19),
 RUSECTION_ID NUMBER(19),
 RUSECTION_DATA_INDEX SMALLINT,
 DATA BLOB)

Example Configuration



If you have a cluster named AppCluster, with four member servers AppClusterMember1, AppClusterMember2, AppClusterMember3 and AppClusterMember4, then you can configure the log locations like this:

Cluster Name Server Name Transaction Log Location Compensation Log Location
AppCluster AppClusterMember1 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App1 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App1 

AppClusterMember2 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App2 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App2 

AppClusterMember3 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App3 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App3 

AppClusterMember4 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App4 custom://com.ibm.rls.jdbc.SQLRecoveryLog?datasource=jdbc/tranlog,tablesuffix=App4
In this example, the table suffix is set to as follows:
  • AppClusterMember1
  • AppClusterMember2
  • AppClusterMember3
  • AppClusterMember4.
The database tables with the following names will be created:
  • WAS_TRAN_LOGApp1
  • WAS_TRAN_LOGApp2
  • WAS_TRAN_LOGApp3
  • WAS_TRAN_LOGApp4
  • WAS_PARTNER_LOGApp1
  • WAS_PARTNER_LOGApp2
  • WAS_PARTNER_LOGApp3
  • WAS_PARTNER_LOGApp4
  • WAS_COMP_LOGApp1
  • WAS_COMP_LOGApp2
  • WAS_COMP_LOGApp3
  • WAS_COMP_LOGApp4

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"--","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF012","label":"IBM i"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"},{"code":"PF035","label":"z\/OS"}],"Version":"8.5.5","Edition":"","Line of Business":{"code":"LOB15","label":"Integration"}}]

Document Information

Modified date:
17 June 2018

UID

swg27038432