Failure transparency in Transparent Connectivity

High Availability Guide : Using HotStandby with applications : Transparent Connectivity : Failure transparency in Transparent Connectivity

Failure transparency handles the masking of failures. The failure transparency level is set with the TF_LEVEL attribute.

Three failure transparency levels are available:

TF_LEVEL=NONE

Failure transparency is disabled (default).

TF_LEVEL=CONNECTION

The server connection is preserved, that is, it is unnecessary to reconnect in the case of failover or switchover.

TF_LEVEL=SESSION

Most non‑default session level settings are preserved. Additionally, prepared statements are preserved. However, open cursors are closed, and ongoing transactions are aborted.

Principles of connection switch handling

A connection switch refers to a situation where the driver changes the active server connection. Generally, the reason for a connection switch is a failover to the Secondary server or a switchover between the servers.

More specifically, a need for a connection switch is detected from one of the following events:

▪Event from the Secondary server about the state change to PRIMARY ALONE (failover) or PRIMARY ACTIVE (switchover). This is the main (and the fastest) mode of performing the connection switch.

▪Indication of the state change at Primary.

▪Link failure on the active connection.

▪Connection timeout on the active connection.

The driver executes the connection switch in two steps:

1 The need for the connection switch is detected. The driver returns the following connection switch error on a pending request, or the following request:

SQLSTATE	Native code	Message text and description
HY000	25216	Connection switch, some session context may be lost. Description: The driver has discovered the need of the connection switch. The client is expected to issue a transaction rollback call to finalize the connection switch. This error code and message will be received at each consecutive network request call until the rollback call is issued

2 The Client program issues a rollback command (ODBC: SQLEndTran() with SQL_ROLLBACK; JDBC: Connection.rollback()). If the rollback is successful, a new active connection has been mapped to the TC connection that may be used.

Note The connection switch error may be returned on a few consecutive ODBC calls. Therefore, a provision must be made to always respond with a rollback to this error, on any ODBC network request. If this happens in the middle of a transaction, the transaction must be re-executed.

On the other hand, if a new active connection cannot be established, the following error code is returned:

SQLSTATE	Native code	Message text and description
08S01	14503	Communication link failure Description: The driver has failed to establish a new active connection. The TF connection is lost and the Client has to reconnect (using a Data Source Info) in order to continue.

After receiving the rollback call, the driver will use a few alternative ways of finding the new active connection. In the simplest case, it will use the standby connection for the purpose. If that connection is not in the right state, the driver will wait for two seconds for the proper event to arrive. If the event does not arrive, and in other cases, the driver will fall back to the address list in the TC connect info and will repeat the connect sequence iteratively for a maximum time of 10 seconds. If all the efforts fail, the driver returns the above error.

The effect of the error is that the connection is lost, as seen by the application. Any further request issued on that connection will result in the same error.

Preservation of session state

When the connection switch is executed by the driver, some of the session context can be lost and the application must reconstruct it. The amount of the preserved state is dictated by the Transparent Failover level, expressed with the TC Info attribute TF_LEVEL.

With the TF level CONNECTION, no state is preserved. With the SESSION level, most of the session state is preserved. The preservation of the session state is implemented by caching the necessary data in the driver. The higher transparency level is achieved at the expense of the response time of the requests requiring caching, as well as increased memory usage in the driver.

Regardless of the TF level, the following applies in the case of failovers:

▪The updates of the current transactions are lost (because of the transaction rollback).

▪Open cursors and their positions are lost.

TF_LEVEL	Preserved state
CONNECTION	No session state is preserved.
SESSION	Prepared statements ▪The prepared states are preserved. The effects of the following statements are preserved: ▪SET CATALOG ▪SET SQL INFO ▪SET SQL SORTARRAYSIZE ▪SET SQL CONVERTORSTOUNIONS ▪SET SQL JOINPATHSPAN ▪SET LOCK TIMEOUT <seconds> ▪SET IDLE TIMEOUT ▪SET OPTIMISTIC LOCK TIMEOUT ▪SET STATEMENT MAXTIME ▪SET ISOLATION LEVEL ▪SET DURABILITY ▪SET SAFENESS ▪SET SCHEMA ▪SET SYNC USER ▪SET SYNC MODE The following standard ODBC attributes are preserved ▪SQL_ATTR_ACCESS_MODE (SET READ ONLY, SET READ WRITE) ▪SQL_ATTR_CURRENT_CATALOG (duplicates SET CATALOG above) ▪SQL_ATTR_AUTOCOMMIT

TF_LEVEL

Preserved state

CONNECTION

No session state is preserved.

SESSION

Prepared statements

▪The prepared states are preserved.

The effects of the following statements are preserved:

▪SET CATALOG

▪SET SQL INFO

▪SET SQL SORTARRAYSIZE

▪SET SQL CONVERTORSTOUNIONS

▪SET SQL JOINPATHSPAN

▪SET LOCK TIMEOUT <seconds>

▪SET IDLE TIMEOUT

▪SET OPTIMISTIC LOCK TIMEOUT

▪SET STATEMENT MAXTIME

▪SET ISOLATION LEVEL

▪SET DURABILITY

▪SET SAFENESS

▪SET SCHEMA

▪SET SYNC USER

▪SET SYNC MODE

The following standard ODBC attributes are preserved

▪SQL_ATTR_ACCESS_MODE

(SET READ ONLY, SET READ WRITE)

▪SQL_ATTR_CURRENT_CATALOG

(duplicates SET CATALOG above)

▪SQL_ATTR_AUTOCOMMIT