Transaction Guard for Improving Client Failover

Transaction Guard is a developer feature that your applications can use to determine COMMIT_OUTCOME following recoverable errors.

About Transaction Guard

Transaction Guard provides a fully integrated tool for applications to use to achieve idempotence automatically and transparently, and in a manner that scales.

Transaction Guard uses Logical Transaction ID (LTXID) to avoid submitting duplicate transactions. This function is referred to as transaction idempotence. The LTXID persists on commit, and is reused following a rollback. During normal runtime, a LTXID is automatically held in the session at both the client and server for each database transaction. At commit, the LTXID is persisted as part of committing the transaction and the next LTXID to use is returned to the client.

Note:

Application Continuity protects outages only for normal applications. Administrative tasks through AC-enabled services are not supported and you must avoid them.

Applications have a problem if they fail to recognize that the last submission has committed, or that it will commit sometime soon, or that the last submission has not run to completion. Applications failing to recognize these submission states can result in users who resubmit or applications that use their own replay to issue duplicate requests, repeating changes that are already committed to the database, and other forms of logical corruption. Transaction Guard can be used to solve this problem.

Application Continuity automatically enables and uses Transaction Guard, but you can also enable Transaction Guard independently. If the application has implemented an application-level replay, then it requires the application to be integrated with Transaction Guard to provide idempotence.

Transaction Guard for XA Transactions

Transaction Guard also supports XA-based transactions, which are transactions that are an option for transaction managers, such as Oracle WebLogic Server, Oracle Tuxedo, and Microsoft Transaction Server (exposed to Oracle AI Database through Oracle ODP.NET) when using one-phase commit with XA.

Database Native Transaction Guard

Database Native Transaction Guard enhances the existing Transaction Guard protocols to use the database Transaction ID (DB XID) to impose at-most-once processing.

A server-side transaction is identified by a database transaction identifier or DB XID. Persisting the LTXID in the LTXID_TRANS table as part of the commit of each DB XID introduces overheads in normal transaction operation. This overhead with respect to performance and redo generation is visible in CPU overhead in the case of small transactions because the extra work required by Transaction Guard is not insignificant relative to the work done by the user transaction.

Note:

Database Native Transaction Guard is the default option when you use Application Continuity.

The DB XID is unique within a Pluggable Database (PDB) with local undo and uniquely identifies a transaction in the database. Using the DB XID does not require persistence in a separate table, thus does not incur extra redo generation or performance overheads. The FORCE_OUTCOME procedure takes advantage of the DB XID, instead of relying on the persistence of the LTXID in the separate table.

Database Native Transaction Guard provides the Transaction Guard functionality with lower overheads by avoiding extra writes to the LTXID_TRANS table. This feature does not affect any client-side APIs and does not require administrative changes.

By default, the COMMIT_OUTCOME_FAST_PATH service parameter is set to TRUE if COMMIT_OUTCOME is set to TRUE. Set the COMMIT_OUTCOME_FAST_PATH service parameter to FALSE to disable Database Native Transaction Guard.

Transaction Guard Support During Major Database Version Upgrades

Starting with Oracle AI Database 26ai, Transaction Guard works during DBMS_ROLLING operations to ensure continuous application functions during switchover, issued by DBMS_ROLLING to Transient Logical Standby.

Transaction Guard returns the commit outcome of the current in-flight transaction when an error or outage occurs. Applications embed the Transaction Guard APIs in their error handling procedures to ensure that work continues without any in-flight work lost or duplicate submissions after an outage. Transaction Guard provides idempotence support to ensure that a commit occurs not more than once when a transaction is re-processed (replay) after an outage.

Transaction Guard ensures continuous application operation during the DBMS_ROLLING switchover operation to Transient Logical Standby. Transaction Guard ensures that the last commit outcome of transactions in the in-flight sessions during a switchover outage is used to protect the applications from duplicate submissions of the transactions on replay.

Transaction Guard maintains a transaction history table called LTXID_TRANS that has the mapping of logical transaction identifiers (LTXIDs) to database transactions. For a failover to succeed after an outage, the changes to LTXID_TRANS from the primary database must first replicate and apply to Transient Logical Standby. With supplemental logging enabled for the DBMS_ROLLING procedure, Transaction Guard uses SQL to allow supplemental capture of LTXID_TRANS at CDB and PDB levels. The capture process replicates the LTXID_TRANS table and the apply process reads and recreates the LTXID_TRANS tables for the logical standby, along with the committed user transactions.

As a part of its support for the DBMS_ROLLING procedure, Transaction Guard performs the following functions:

Tracks when the primary database is in DBMS_ROLLING mode (when the database upgrade is initiated)
Checks that supplemental logging is in use
Records the redo vector for the primary key (PK) at runtime while in supplemental logging mode
Waits for all current updates to finish and replicate to the logical standby before performing the LTXID replication
Replicates the LTXID_TRANS tables and applies the redo to Transient Logical Standby for each PDB
Provides a mechanism for failover to know about successful LTXID replication
Enforces last commit outcome for inflight sessions on replay after an outage
Handles new users during supplemental capture and apply process to ensure that any apply does not create mismatched logged-in UIDs (user IDs) at the target database

Transaction Guard Configuration Checklist

Oracle recommends that you use this configuration checklist before you configure services for Transaction Guard.

Before configuring services for Transaction Guard, complete each check on this list:

Grant permission to the application user who will call GET_LTXID_OUTCOME, as follows:
```
GRANT EXECUTE ON DBMS_APP_CONT to user_name;
```
Note:

Do not run this statement if you use Application Continuity.
Locate and define the transaction history table for optimal performance.

The transaction history table (LTXID_HIST) is created, by default, in the SYSAUX tablespace when you create or upgrade an Oracle AI Database. New partitions are added when you add instances, using the storage of the last partition. If the location of transaction history table is not optimal for performance, then you can move it to another tablespace and create partitions there. For example, the following statement moves the transaction history table to a tablespace named FastPace:
```
ALTER TABLE LTXID_TRANS move partition LTXID_TRANS_1 tablespace FastPace
   storage ( initial 10G next 10G minextents 1 maxextents 121 );
```
Set values for the COMMIT_OUTCOME and RETENTION_TIMEOUT service parameters.
If you are using Oracle Real Application Clusters (Oracle RAC), Oracle Data Guard, or Oracle Active Data Guard, then to obtain rapid notification of an outage, Oracle recommends that you use Fast Application Notification (FAN).

Configuring Services for Transaction Guard

To configure services to use Transaction Guard, review and set the required service parameters.

Review and set the following parameters:

COMMIT_OUTCOME: Set the COMMIT_OUTCOME service parameter to TRUE.
The COMMIT_OUTCOME service parameter determines whether the transaction commit outcome is accessible after the COMMIT has run and an outage has occurred. While Oracle AI Database has always made COMMIT durable, Transaction Guard makes the outcome of the COMMIT durable. Applications use this durability of a commit to enforce the status of the last transaction run before an outage.
RETENTION_TIMEOUT: Use the RETENTION_TIMEOUT service parameter with COMMIT_OUTCOME. The RETENTION_TIMEOUT service parameter determines the amount of time, in seconds, that the COMMIT outcome is retained. Oracle recommends that most installations use the default value.

In the following example, the SRVCTL command configures a service named sales for Transaction Guard:

$ srvctl add service -db crm -service sales -preferred crm_1,crm_2
  -available crm_3,crm_4 -commit_outcome TRUE -retention 86400
  -notification TRUE

You can also modify an existing service to configure it for Transaction Guard by using the srvctl modify service command.

Note:

Do not use the default database service, the service which has the name set to the value of db_name or db_unique_name. The default service is used for administrative purposes and does not have the same properties as user-created services.