Configuring Application Continuity

Application Continuity (AC) requires using an Oracle Pool or an application that allows Transparent Application Continuity (TAC) to discover request boundaries.

Overview of Application Continuity Configuration Tasks

The Application Continuity features in various Oracle applications are used automatically if you set the required service attributes.

The main actions for ensuring transparent replay for an application are the following:

Ensure that you have the necessary CPU and memory resources.
- CPU: Application Continuity is managed on the client and server sides and requires minimal CPU overhead to operate.
At the client, CPU is used to build proxy objects and for garbage collection (GC).

At the server, CPU is used for validation. CPU overhead is reduced for platforms with current Intel and SPARC chips where validation is assisted in the hardware.
- Memory: When using Application Continuity, the replay driver requires more memory than the base driver because the calls are retained until the end of a request. At the end of the request, the calls are released to the garbage collector. This action differs from the base driver that releases closed calls.
The memory consumption of the replay driver depends on the number of calls per request. If this number is small, then the memory consumption of the replay driver is less, and comparable to the base driver.

To obtain the best performance, you must set the same value for both the -Xmx and -Xms parameters on the client. For example, if there is sufficient memory, then allocate 4 to 8 GB (or more) of memory for the Virtual Machine (VM), for example, by setting -Xms4g for 4 GB. If the -Xms parameter has a lower value, then the VM also uses a lower value from the operating system, and performance might suffer and garbage collection operations increase.
Determine whether the application borrows and returns connections from the connection pool, for example WebLogic Server Pool, Universal Connection Pool, OCI Session Pool, Oracle Tuxedo request, or ODP.NET connection pool, for each request, or whether to add beginRequest and endRequest APIs to the application's own connection pool to identify request boundaries for Java, only.

Caution:
Do not use the beginRequest and endRequest Java API calls or the OCIRequestBegin and OCIRequestEnd OCI
API calls anywhere other than at request boundaries (borrow and return
connections from your connection pool). endRequest indicates that the request is complete, and that it is now stateless. Replay
starts from the next beginRequest. If there is prior state,
it must be reestablished using FAILOVER_RESTORE or
callback.
Application Continuity replays all states in a request. If the application sets states before vending connections, FAILOVER_RESTORE or a callback is needed. When using Oracle WebLogic Server or the Universal Connection Pool, use FAILOVER_RESTORE, connection labeling, or triggers. When using Oracle Call Interface (OCI) session pool, Oracle Tuxedo or ODP.NET with Oracle Database 18c or later clients, use FAILOVER_RESTORE, and only add the Transparent Application Failover (TAF) callback if it is needed. The labeling is used for both runtime and replay. Oracle strongly recommends setting FAILOVER_RESTORE to AUTO, LEVEL1, or LEVEL2 with wallets, to use database templates.
Determine whether the application requires, and therefore needs to configure keeping original values for, SYSDATE, SYSTIMESTAMP, and SYS_GUID and sequences during failover.
Assess the application style for the session_state_consistency value, and set the appropriate value on the service:
- If session_state_consistency is set to AUTO, then Transparent Application Continuity monitors the session state and decides what to do. If you are unsure about state usage or know that states can change in the future, then use Transparent Application Continuity. With Oracle AI Database 26ai templates and wallets, modifiable parameters are restored. For .NET applications, use ODP.NET, Managed Driver 23ai or later, or ODP.NET Unmanaged Provider or later.
Use session state AUTO so that the session state is managed as the application evolves. Session state AUTO is available with TAC. When using TAC, both the client visible and server visible session states must match for a successful failover or session migration. When there is unrestorable session state at the beginning of a request, TAC does not enable as the state cannot be proven at the beginning of the request. Use ACCHK and the protection statistics to detect unrestorable session state at the beginning of request. Use RESET_STATE to clean session state automatically by Oracle AI Database between requests.
- If session_state_consistency is set to DYNAMIC, then the application changes the environment or settings during the request. Replay is disabled after the first COMMIT until the beginning of the next request. DYNAMIC is the default mode, appropriate for most applications.
Note:
The service attribute values FAILOVER_TYPE = TRANSACTION with SESSION_STATE_CONSISTENCY = STATIC are no longer a supported service attribute combination.
Determine if any requests in the application should not be replayed.
For example, replay may need to be disabled for requests using external PL/SQL actions.
Follow these configuration guidelines:
- For Java, use Oracle Database 12c release 1 (12.1.0.1), or later. For OCI-based applications, use Oracle Database 12c release 2 (12.2), or later.
- For .NET applications, use ODP.NET, Managed Driver 23ai or later, or ODP.NET, Unmanaged Provider 12.2, or later, connecting to an Oracle Database 12c Release 2 (12.2) or later. By default, Application Continuity is enabled for ODP.NET applications in this configuration. When using OCI-based applications that do not use the OCI Session Pool, including SQL*Plus, use Transparent Application Continuity that adds boundaries for you.
Note:
Oracle Data
Provider for .NET (ODP.NET), Unmanaged Driver is deprecated in Oracle AI
Database 26ai.
- Custom Java pools and standalone Java applications can also use the JDBC replay data source directly. When using custom Java pools and standalone applications, Oracle recommends that you use Transparent Application Continuity which adds boundaries for you. You can also add beginRequest and endRequest Java APIs to your application.
- If the application does not borrow and return from the Oracle connection pools, explicitly mark request boundaries. For example, if using custom JDBC pools, or other pools, Oracle recommends that you use Transparent Application Continuity which adds boundaries for you. You can also add beginRequest and endRequest Java APIs to your application. These APIs can also be used for standalone JDBC applications without a connection pool.
- Enable FAN for fast interrupt on errors. This is essential to eliminate a TCP delay occurring before the failover can start. In 12.2 FAN is built into the JDBC and OCI drivers and is on by default for Java.
- Use a database service to connect; never use a SID or an instance name, or the administration service that is the DB_NAME or DB_UNIQUE_NAME.
- Use a connection string that sets retries for new incoming connections and a delay between these retries.
- For the service, set FAILOVER_TYPE to TRANSACTION for Application Continuity or set FAILOVER_TYPE to AUTO for Transparent Application Continuity. Set COMMIT_OUTCOME to TRUE and, for OCI FAN, set NOTIFICATION to TRUE. Optionally to find the best connections to use, set GOAL to SERVICE_TIME and CLB_GOAL to LONG.
- Use the statistics for request boundaries and protection level to monitor the level of coverage. If you need more details, then use Application Continuity Check Coverage (with the ORAchk utility) to report the percentage of requests that are fully protected by Application Continuity, and the location of those requests that are not fully protected. Use this coverage check before deployment and after application changes. Developers and management will know how well protected an application release is from failures of the underlying infrastructure. If there is a problem, then it can be fixed before the application is released, or waived knowing the level of coverage.

Related Topics

Configuring Connections for High Availability and Application Continuity

These are general recommendations for configuring the connections used by applications for high availability.

If you are using Java, then you must use the oracle.jdbc.datasource.impl.OracleDataSource, oracle.jdbc.replay.OracleConnectionPoolDataSourceImpl, or oracle.jdbc.replay.driver.OracleXADataSourceImpl data source to obtain JDBC connections. These data sources support all the properties and configuration parameters of all the Oracle JDBC data sources, for example, the oracle.jdbc.pool.OracleDataSource.

For OCI based applications including SQL*Plus and ODP.NET, the OCI driver 12.2, and later, supports Application Continuity.

You must remember the following points while using the connection URL:

If the REMOTE_LISTENER setting for the database does not match the addresses in the ADDRESS_LIST at the client, then it does not connect, showing services cannot be found. So, the REMOTE_LISTENER setting for the database must match the addresses in the ADDRESS_LIST at the client:
If the connect string uses the SCAN Name, then REMOTE_LISTENER must be set to the SCAN name.
- If the connect string uses an ADDRESS_LIST of host VIPs, then REMOTE_LISTENER must be set to an address list that includes all SCAN VIPs and all host VIPs
Note:
Use SCAN for location independence, to avoid having to reconfigure the client when you add or delete nodes, or when databases change to running on different nodes.
Set RETRY_COUNT, RETRY_DELAY, CONNECT_TIMEOUT, and TRANSPORT_CONNECT_TIMEOUT parameters in the connection string. These settings improve acquiring new connections at runtime, at replay, and during work drains for planned outages.
The CONNECT_TIMEOUT parameter is equivalent to the SQLNET.OUTBOUND_CONNECT_TIMEOUT parameter in the sqlnet.ora file and applies to the full connection. The TRANSPORT_CONNECT_TIMEOUT parameter applies per address.
Set CONNECT_TIMEOUT to a high value to prevent an overabundance of log ins. Low values can result in log in storms to the application. Do not set (RETRY_COUNT+1)*RETRY_DELAY or CONNECT_TIMEOUT larger than your response time SLA. The application must either connect or receive an error within the response time SLA.
You are not recommended to use Easy*Connect for High Availability deployments.

Example: Recommended TNS Entry for High Availability

The following is an example of a Transparent Network Substrate (TNS entry). This is the required TNS format for Oracle Notification Service (ONS) to be auto configured. ONS is the transport system used for Fast Application Notification (FAN). Oracle recommends using FAN with Application Continuity to provide fast outage detection.

myAlias=(DESCRIPTION=
   (CONNECT_TIMEOUT=90)(RETRY_COUNT=30)(RETRY_DELAY=3)(TRANSPORT_CONNECT_TIMEOUT=3)
   (ADDRESS_LIST=
  (LOAD_BALANCE=ON)
  (ADDRESS=(PROTOCOL=TCP)(HOST=RAC-scan)(PORT=1521)))
   (ADDRESS_LIST=
  (LOAD_BALANCE=ON)
  (ADDRESS=(PROTOCOL=TCP)(HOST=DG-Scan)(PORT=1521)))
   (CONNECT_DATA=(SERVICE_NAME=service_name)))

Related Topics

Configuring Oracle AI Database for Application Continuity

Before you can use Application Continuity, you must ensure that your system is configured correctly.

Your Oracle AI Database configuration must include the following to use Application Continuity:

If you are using Oracle Real Application Clusters (Oracle RAC) or Oracle RAC One Node, Oracle Data Guard, or Oracle Active Data Guard, then ensure that Fast Application Notification (FAN) is configured with Oracle Notification Service (ONS) to communicate with pools and drivers that are Oracle Database 12c or later.
Set the service attributes on the service for replay and load balancing. For example, set:
FAILOVER_TYPE = AUTO | TRANSACTION: Use FAILOVER_TYPE=AUTO for Transparent Application Continuity or FAILOVER_TYPE=TRANSACTION for Application Continuity. This attribute enables the replay functionality for the replay drivers and Application Continuity. Oracle drivers keep track of all replayable statements issued during a database session. If all of the statements are replayable, and any in-flight transactions did not commit or the session is in conversation, then Oracle replays the uncommitted work following a planned or unplanned database outage. This mode re-establishes transactional and non-transaction states automatically with no additional application steps.
REPLAY_INITIATION_TIMEOUT = n : For setting the duration, in seconds, to allow replay to start. For example, you might set the value of n to 300.
FAILOVER_RETRIES = 3: For specifying the number of connection retries for each replay. Oracle recommends that you set retry_count in the tnsnames.ora file, rather than on the service.
FAILOVER_DELAY = 3: For specifying the delay in seconds between connection retries. Oracle recommends that you set retry_count in the tnsnames.ora file, rather than on the service.
COMMIT_OUTCOME = TRUE: If you are using Transaction Guard, the COMMIT_OUTCOME service parameter determines whether the transaction commit outcome is accessible after the COMMIT has run and an outage has occurred. Starting with Oracle AI Database 26ai, COMMIT_OUTCOME defaults to using Native Transaction Guard. Native Transaction Guard is used whenever the XID can be sent to the driver in advance of the COMMIT. While Oracle AI Database has always made the COMMIT action durable, Transaction Guard makes the outcome of the COMMIT durable.
FAILOVER_RESTORE = AUTO | LEVEL1 | LEVEL2: Use FAILOVER_RESTORE=AUTO or FAILOVER_RESTORE=LEVEL1 for Transparent Application Continuity and FAILOVER_RESTORE=LEVEL1 | LEVEL2 for Application Continuity. To automatically restore client states that are preset on the connection pool or driver before replay begins-including NLS states, TAGS (MODULE, ACTION, ECID, CLIENT_ID, CLIENT_INFO) states, and all server modifiable session states that use FAILOVER_RESTORE=LEVEL1 | LEVEL2 with Wallets.

Caution:

Do not use the default database service corresponding to the DB_NAME or DB_UNIQUE_NAME. Also, do not use the default database service for high availability, because this service cannot be enabled or disabled, and cannot be relocated on Oracle RAC or switched over to Oracle Data Guard. This service is reserved for Oracle Enterprise Manager Cloud Control (Cloud Control) and for DBAs.

Establishing the Initial State Before Application Continuity Replays

At the beginning of replay, Application Continuity restores the initial session state.

The topics in this section describe how to configure the service and database to successfully restore the session state before replaying.

Checking Initial States for Application Continuity

Learn about the session state that is restored.

If your application sets an initial state for the connection before allowing applications to use the connection, then Application Continuity must establish this initial state before replay starts. With common states, which are listed in the topics in this section, FAILOVER_RESTORE restores the states. However, you must review the topics that describe common states. If the states that your application presets are not listed, and the application needs initial states, then you must add an additional callback.

Examples of states that can be preset include:

PL/SQL package state
NLS Setting
Optimizer setting

During a request, Application Continuity reestablishes the entire state for the request. This prerequisite is for the initial state before Application Continuity starts replaying.

A callback is not required if FAILOVER_RESTORE restores all required states, which is the case for most applications.

FAILOVER_RESTORE

Setting FAILOVER_RESTORE to LEVEL1 (for AC with older 19c versions), LEVEL2 (for AC with database templates), or LEVEL1 or AUTO (for TAC) automatically restores all modifiable parameters before replaying the request.

FAILOVER_RESTORE is a setting on your service. Available with Oracle Database 12.2 and later, FAILOVER_RESTORE automatically restores all session states available for your application at the client-side.

Oracle recommends setting FAILOVER_RESTORE to LEVEL2, LEVEL1, or AUTO for all applications.

Do not set FAILOVER_RESTORE to NONE when FAILOVER_TYPE is set to TRANSACTION. If you set FAILOVER_RESTORE to NONE, then the application must restore its own session state for each request. Manually restoring session state does not future-proof your application as requirements evolve.

Oracle recommends setting FAILOVER_RESTORE to AUTO, LEVEL2, or LEVEL1 with encryption. These settings restore session state automatically.

Refer to States Restored with FAILOVER_RESTORE for the client-side session states that are restored.

States Restored with FAILOVER_RESTORE

The following session states are restored when FAILOVER_RESTORE is set to LEVEL1, LEVEL2, or AUTO, with or without wallets.

Session States That Are Restored

NLS_CALENDAR
NLS_CURRENCY
NLS_DATE_FORMAT
NLS_DATE_LANGUAGE
NLS_DUAL_CURRENCY
NLS_ISO_CURRENCY
NLS_LANGUAGE
NLS_LENGTH_SEMANTICS
NLS_NCHAR_CONV_EXCP
NLS_NUMERIC_CHARACTER
NLS_SORT
NLS_TERRITORY
NLS_TIME_FORMAT
NLS_TIME_TZ_FORMAT
TIME_ZONE
NLS_TIMESTAMP_FORMAT
NLS_TIMESTAMP_TZ_FORMAT
CURRENT_SCHEMA
MODULE
ACTION
CLIENT_ID
AUTOCOMMIT states (for Java and SQL*Plus)
CONTAINER (PDB) and SERVICE
ROLES (excludes secure roles, which continue to require a call back)
ROW_ARCHIVAL
EDITION
ERROR_ON_OVERLAP_TIME
SQL_TRANSLATION_PROFILE
CLIENT_INFO. (JDBC)

Full FAILOVER_RESTORE with Database Templates

Oracle AI Database 26ai supports database templates. A database template is a set of session states with their values that describe a database session.

Database templates are created or assigned by the database automatically as the session state changes. TAC and AC use templates to restore the session state at replay.

Using database templates, a larger subset of sessions failover during planned maintenance and unplanned outages because their session states are restored and verified automatically, and clients use less memory. Database templates are enabled by default for TAC and you are recommended to use FAILOVER_RESTORE=LEVEL2 for AC.

At failover, FAILOVER_RESTORE restores session parameters that were altered in your session. Examples of session parameters restored include optimizer_capture_sql_plan_baselines and create_stored_outlines that were set in the session.

If you are already using a logon trigger, connection label, or callback to restore session parameters, you can continue to use them. Labels and callbacks are fully supported with and without extended FAILOVER_RESTORE. Using extended FAILOVER_RESTORE has the advantage that you do not need to update it as the application changes.

To use this feature, you must set FAILOVER_RESTORE to LEVEL2 or AUTO and ensure that the dictionary credentials are encrypted on your system. You can also set FAILOVER_RESTORE to LEVEL1 for AC and TAC that also restores all modifiable session parameters when wallets are used.

There are two methods of adding the wallet or keystore for dictionary credentials encryption:

Note:

You must use either one of the following methods to configure a keystore for FAILOVER_RESTORE.

Recommended: Use the WALLET_ROOT database instance initialization parameter to specify the wallet location. Using an initialization parameter for the wallet location ensures consistency across Oracle Real Application Clusters (Oracle RAC) and Oracle Data Guard . This method requires a rolling restart of the database.
Modify the sqlnet.ora file in your TNS_ADMIN directory on the database server to point to the wallet location. This method does not require a database restart,unless your database runs on the Microsoft Windows operating system. You are responsible for ensuring that the sqlnet.ora files are consistent in all ORACLE_HOME directories. Also, the sqlnet.ora might require additional maintenance when performing database upgrades.

Related Topics

FAILOVER_RESTORE with Database Templates

Starting with Oracle AI Database 26ai, Application Continuity uses database templates to checkpoint session state, restore the session state at the start of replay, and support session migration during planned maintenance.

Database templates restore server-side and client-visible session states at the beginning of the Application Continuity replay, thus increasing Application Continuity protection. To use this feature set FAILOVER_RESTORE=AUTO for Transparent Application Continuity or set FAILOVER_RESTORE=LEVEL2 for Application Continuity.

FAILOVER_RESTORE with database templates improves coverage for applications with a wider set of session states and lowers client memory usage. It enables you to migrate more sessions during planned maintenance and to have a higher number of successful and faster failovers during unplanned outages as protection by Application Continuity is higher.

Database templates for Application Continuity ensures the migration of sessions containing server-side session states that have not reached a boundary to drain during the draining period, and improves the Application Continuity protection for unplanned outages. Database templates for Application Continuity enables migration of sessions using secure and large session states for planned maintenance and for load balancing.

To enable this feature, you must set FAILOVER_RESTORE to LEVEL2 or AUTO. To retain the Oracle Database 19c restore functionality, set FAILOVER_RESTORE to LEVEL1 for both Application Continuity and Transparent Application Continuity. To restore all session states at failover, the database must have encryption enabled, for example using TDE wallets.

Configuring a Keystore using WALLET_ROOT for FAILOVER_RESTORE

Use these steps to configure encryption of dictionary credentials by using a software keystore (wallet) and Transparent Data Encryption (TDE) for use with FAILOVER_RESTORE.

If you are using Oracle Autonomous AI Database, you do not need to perform these steps.
For Oracle Autonomous AI Database, a software keystore already exists and dictionary credentials are encrypted
If you are not using Oracle Autonomous AI Database, then check if your system is already configured to enforce dictionary credential encryption.
1. Verify a wallet (a Keystore) exists using the following SQL query:
```
SELECT con_id, wrl_type, status , wallet_type FROM V$ENCRYPTION_WALLET
ORDER BY con_id;
    CON_ID WRL_TYPE     STATUS   WALLET_TYPE
---------- ------------ -------- -----------
         0 FILE         OPEN     PASSWORD
```
  If no rows are returned by this SQL query, then a wallet, or keystore, does not exist.
2. Verify that dictionary credentials are encrypted using the following SQL query:
```
SQL> SELECT enforcement FROM DICTIONARY_CREDENTIALS_ENCRYPT;
ENFORCEMENT
---------------
ENABLED
```
  If this SQL query returns DISABLED, then the dictionary is not encrypted.
If you have a wallet and dictionary credentials encrypted, you can use extended FAILOVER_RESTORE by setting the attribute on your service. You do not need to complete any more of the steps in this procedure.

If you do not have an existing wallet, or if you need to enable dictionary credentials encryption, then continue with the following steps.
Configure the database to use a software keystore.
1. If necessary, create a directory to store the wallet.
  The location selected needs to be shared across Oracle RAC nodes and replicated to Oracle Data Guard sites. For Oracle RAC, the directory must be on shared storage.
2. Change the initialization parameter WALLET_ROOT.
  The parameter value should be the directory where the wallet is stored.
```
SQL> CONNECT / AS SYSDBA
SQL> ALTER SYSTEM SET WALLET_ROOT='/myOracleBase/admin/wallet/' SCOPE=spfile;
```
  You can also change the WALLET_ROOT initialization parameter using the init.ora file on all RAC nodes by adding wallet_root='/myOracleBase/admin/wallet/'.
  
  Starting with Oracle AI Database 26ai, the parameter ENCRYPTION_WALLET_LOCATION is desupported.
  
  To store and retrieve the TDE wallet, use the WALLET_ROOT structure (introduced with Oracle Database 18c).
  
  Note:
  
  If Transparent Data Encryption (TDE) is enabled, but WALLET_ROOT is not configured, then you will be blocked from upgrading to Oracle AI Database 26ai. This block for upgrades of databases using TDE is to prevent the possibility of not being able to open the database after the upgrade.
3. Change the initialization parameter TDE_CONFIGURATION to specify a software keystore.
```
SQL> CONNECT / AS SYSDBA
SQL> ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" SCOPE=BOTH SID='*'
```
  You can also change the TDE_CONFIGURATION initialization parameter using the init.ora file on all RAC nodes by adding TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" .
4. Perform a rolling restart of the database instances to activate the new initialization parameters.
  For example, for a two node clustered database named orcl, where the instances are named orcl1 and orcl2, you would use the following commands to stop and restart each instance individually to avoid a complete outage of your database.
```
$ srvctl stop instance -db orcl -instance orcl1 -drain_timeout 600 -stopoption IMMEDIATE
$ srvctl start instance -db orcl -instance orcl1

$ srvctl stop instance -db orcl -instance orcl2 -drain_timeout 600 -stopoption IMMEDIATE
$ srvctl start instance -db orcl -instance orcl2
```
  Note:
  
  Fleet Patching and Provisioning, if used, automates this process and can be used instead if you are modifying the parameters during a patch upgrade.
5. Verify that the parameters are set to the correct values after restarting the instances.
```
SQL> SHOW PARAMETER WALLET_ROOT;
SQL> SHOW PARAMETER TDE_CONFIGURATION;
```
Create a keystore with a password, if one does not already exist.

In the following example password is the password for the keystore. The password is case sensitive. Keystore passwords adhere to the same rules as database user passwords.
```
SQL> CONNECT / AS SYSKM 
SQL> ADMINISTER KEY MANAGEMENT CREATE KEYSTORE IDENTIFIED BY "password";
```
Open a keystore and set an encryption key.

If your database is configured as an Oracle Multitenant database, then a keystore and encryption key must be set for each PDB using the CONTAINER=all clause. In the following example password is the password for the keystore.
```
SQL> CONNECT / AS SYSKM
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "password" CONTAINER=all;
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "password" 
SQL> WITH BACKUP CONTAINER=all;
```
If your database is not configured as an Oracle Multitenant database, then use the following SQL commands, where password is the password for the keystore:
```
SQL> CONNECT / AS SYSKM
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "password";
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "password" WITH BACKUP;
```
Encrypt the database dictionary credentials.

Use an operator with the SYSKM role to run the following SQL command from within the Container Database (CDB) root and each PDB.
```
SQL> CONNECT / AS SYSKM
SQL> ALTER DATABASE DICTIONARY ENCRYPT CREDENTIALS;
```

Encryption and decryption of the information occurs automatically at the server during failover restoration.

Warning:

It is recommended to backup the software keystore and the wallet location. Do not lose your TDE software keystore or WALLET_ROOT location. If you do, for Application Continuity or Transparent Application Continuity, a new keystore can be created but encrypted dictionary credentials will need to be re-instantiated. Failover will not succeed while there is a mismatch in the wallet keys.

Related Topics

Configuring a Keystore using SQLNET.ORA for FAILOVER_RESTORE

Use these steps to configure encryption of dictionary credentials by using SQLNET.ORA to point to the wallet location for use with FAILOVER_RESTORE.

Note:

Oracle recommends that you configure a Keystore using WALLET_ROOT for FAILOVER_RESTORE in preference to SQLNET.ORA.

This method does not require a database restart, unless your database runs on the Microsoft Windows operating system. You are responsible for ensuring that the sqlnet.ora files are consistent in all ORACLE_HOME directories.

If you are using Oracle Autonomous AI Database, you do not need to perform these steps.
For Oracle Autonomous AI Database, a software keystore already exists and dictionary credentials are encrypted
If you are not using Oracle Autonomous AI Database, then check if your system is already configured to enforce dictionary credential encryption.
1. Verify a wallet exists using the following SQL query:
```
SQL> SELECT con_id, wrl_type, status , wallet_type FROM V$ENCRYPTION_WALLET
ORDER BY con_id;
    CON_ID WRL_TYPE     STATUS   WALLET_TYPE
---------- ------------ -------- -----------
         0 FILE         OPEN     PASSWORD
```
  If no rows are returned by this SQL query, then a wallet, or keystore, does not exist.
2. Verify that dictionary credentials are encrypted using the following SQL query:
```
SQL> SELECT enforcement FROM DICTIONARY_CREDENTIALS_ENCRYPT;
ENFORCEMENT
---------------
ENABLED
```
  If this SQL query returns DISABLED, then the dictionary is not encrypted.
If you have a wallet and dictionary credentials encrypted, you can use extended FAILOVER_RESTORE by setting the attribute on your service. You do not need to complete any more of the steps in this procedure.

If you do not have an existing wallet, or if you need to enable dictionary credentials encryption, then continue with the following steps.
Configure the database to use a wallet.
1. View the TNS_ADMIN environment variable to find the location of the network configuration files used by your database.
  - On Linux and UNIX systems, as the Oracle Home software owner, view the current setting of the TNS_ADMIN environment variable.
```
$ env | grep TNS_ADMIN
```
  - On Microsoft Windows systems, check the value set for TNS_ADMIN as both an environment variable and in the registry in the path Computer\HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_ HOME_NAME.
  If the TNS_ADMIN variable is not set, then the default location of $ORACLE_BASE_HOME/network/admin is used for the Oracle Net configuration files with read-only Oracle homes.
2. If necessary, create a directory to store the wallet.
  The location selected needs to be shared across Oracle RAC nodes and replicated to Oracle Data Guard sites. For Oracle RAC, the directory must be on shared storage.
3. Change the initialization parameter TDE_CONFIGURATION to specify a software keystore.
```
SQL> CONNECT / AS SYSDBA
SQL> ALTER SYSTEM SET TDE_CONFIGURATION="KEYSTORE_CONFIGURATION=FILE" SCOPE=BOTH SID='*'
```
Create a keystore with a password, if one does not already exist.

In the following example myOracleWalletLoc is the full path name of the directory created to store the wallet (or keystore) and password is the password for the keystore. The password is case sensitive. Keystore passwords adhere to the same rules as database user passwords.
```
SQL> CONNECT / AS SYSKM 
SQL> ADMINISTER KEY MANAGEMENT CREATE KEYSTORE '/myOracleWalletLoc' IDENTIFIED BY "password";
```
Open a keystore and set an encryption key.

If your database is configured as an Oracle Multitenant database, then a keystore and encryption key must be set for each PDB using the CONTAINER=all clause. In the following example password is the password for the keystore.
```
SQL> CONNECT / AS SYSKM
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "password" CONTAINER=all;
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "password" WITH BACKUP CONTAINER=all;
```
If your database is not configured as an Oracle Multitenant database, then use the following SQL commands, where password is the password for the keystore:
```
SQL> CONNECT / AS SYSKM
SQL> ADMINISTER KEY MANAGEMENT SET KEYSTORE OPEN IDENTIFIED BY "password";
SQL> ADMINISTER KEY MANAGEMENT SET ENCRYPTION KEY IDENTIFIED BY "password" WITH BACKUP;
```
Encrypt the database dictionary credentials.

Use an operator with the SYSKM role to run the following SQL command from within the Container Database (CDB) root and each PDB.
```
SQL> CONNECT / AS SYSKM
SQL> ALTER DATABASE DICTIONARY ENCRYPT CREDENTIALS;
```

Encryption and decryption of the information occurs automatically at the server during failover restoration.

Caution:

It is recommended to backup the wallet location. Do not lose your wallet or location. If you do, for Application Continuity or Transparent Application Continuity, a new wallet can be created but encrypted dictionary credentials will need to be re-instantiated.

Failover will not succeed while there is a mismatch in the wallet keys.

Related Topics

Connection Labeling

Connection Labeling is not required unless you want to restore more complex states, such as proxying a session.

This scenario is applicable to Universal Connection Pool (UCP) and Oracle WebLogic server. Connection Labeling APIs are required to match secure session states- SYS_CONTEXT and password protected roles. They are also useful in reporting a failover on the driver side. When a connection is borrowed, Connection Labeling populates the gap by using a callback.

Related Topics

Oracle Universal Connection Pool Developer's Guide

Connection Initialization Callback

Use the Connection Initialization Callback only if you need to restore session states such as SYS_CONTEXT and password protected roles. FAILOVER_RESTORE with wallets restores all modifiable parameters.

If your replaying driver uses an application callback to set the initial state of the session during runtime and replay, then the callback interface depends on whether the driver is a Java Database Connectivity (JDBC) driver or an Oracle Call Interface (OCI) driver.

In this scenario, with either JDBC or OCI, the driver uses an application callback to set the initial state of the session during runtime and replay. With the JDBC replay driver, the driver provides a connection initialization callback interface and methods to register and unregister connection initialization callbacks in the oracle.jdbc.replay.OracleDataSource interface. With OCI and Oracle Data Provider for .NET (ODP.NET), you register the Transparent Application Failover (TAF) callback.

When registered, the initialization callback is run every time a connection is borrowed from the pool, and at each successful reconnection following a recoverable error. (This is true for the JDBC/UCP initialization callback, and should be the same for TAF.) Using the same callback during both runtime and replay ensures that the same initialization is established at replay, as it was when the session was first established. An application is responsible for ensuring that the initialization actions are the same as that on the original connection before failover. If the callback invocation fails, then replay is disabled on that connection. Use the connection initialization callback only when the application has not implemented UCP and WebLogic Connection Labeling and the state cannot be restored automatically by setting either FAILOVER_RESTORE=AUTO or FAILOVER_RESTORE=LEVEL1 for Transparent Application Continuity or FAILOVER_RESTORE=LEVEL2 for Application Continuity.

FAILOVER_RESTORE = NONE and No Callback

FAILOVER_RESTORE = NONE does not restore session state at failover.

Oracle recommends setting FAILOVER_RESTORE to LEVEL2, LEVEL1, or AUTO for all applications.

Potential Side Effects of Application Continuity

When you use Application Continuity with the service attribute FAILOVER_TYPE set to TRANSACTION, statements that perform side effects are replayed.

When you use Transparent Application Continuity with the FAILOVER_TYPE service attribute set to AUTO, then replay is disabled when a side effect is detected. Replay re-enables at the next discovered or explicit boundary.

Note:

As an application owner you can elect to disable replay for requests that contain side effects that you do not want to repeat. The simplest way to disable side effects is to use Transparent Application Continuity (set the service attribute FAILOVER_TYPE to AUTO, which disables side effects for you.

Application Continuity replays PL/SQL chronologically to restore database state. This serves to rebuild the session as if the user submission was delayed. Most applications want the full state rebuilt as if the submission was repeated, such as writing a report or completing some auditing. However, the actions that are replayed to build the state might include some for which you want to take action to accommodate or mitigate the effects of the replay. Some applications elect to disable replay for requests that contain calls that they do not want to repeat.

Examples of actions that create side effects include the following:

DBMS_ALERT calls (email or other notifications)
DBMS_FILE_TRANSFER calls (copying files)
DBMS_PIPE and RPC calls (to external sources)
UTL_FILE calls (writing text files)
UTL_HTTP calls (making HTTP callouts)
UTL_MAIL calls (sending email)
UTL_SMTP calls (sending SMTP messages)
UTL_TCP calls (sending TCP messages)
UTL_URL calls (accessing URLs)

For applications with external actions (such as autonomous transactions or using UTL_HTTP to issue a service-oriented application (SOA) call), Application Continuity is transparent when the application is satisfied with replaying external actions, such as resending email, auditing, and transferring a file.

Allowing and Disallowing Side Effects for 26ai

Replay disabled for side effect by default for TAC, use DBMS_APP_CONT_ADMIN.SET_REPLAY_RULES or DBMS_APP_CONT.APPLY_REPLAY_RULE to allow or disallow side effects.

Replayable Interface Side Effect Use Cases

The following use cases cover various scenarios for replayable interface side effects:

Use the following interface to allow side effects with TAC for entire service:

SQL> execute DBMS_APP_CONT_ADMIN.SET_REPLAY_RULES('Service_name',TRUE,dbms_app_cont.side_effects); 
PL/SQL procedure successfully completed.

SQL> execute DBMS_APP_CONT_ADMIN.CHECK_REPLAY_RULES('Service_name'); 
PL/SQL procedure successfully completed. 
ResultSet #1 
TARGETS                     REPLAY
-----------------------     --------------------------------
PL/SQL Side Effects         enabled
Autonomous Transactions     disabled
Database Links              disabled

Use the following interface to allow side effects with TAC:

begin 
insert into file_tab values (1,'file1.txt');
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => TRUE, TARGETS => DBMS_APP_CONT.SIDE_EFFECTS);
DBMS_FILE_TRANSFER.COPY_FILE(source_directory_object=>'SOURCEDIR', source_file_name=>'file1.txt', destination_directory_object=>'DGROUP', destination_file_name=>'file1.txt');
commit;
end

Use the following interface to disallow side effects with AC:

begin 
insert into file_tab values (1,'file1.txt');
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => FALSE, TARGETS => DBMS_APP_CONT.SIDE_EFFECTS);
DBMS_FILE_TRANSFER.COPY_FILE(source_directory_object=>'SOURCEDIR', source_file_name=>'file1.txt', destination_directory_object=>'DGROUP', destination_file_name=>'file1.txt');
commit;
end

Use the following statement to wrap a replayable interface function for TAC:

create or replace procedure mark_replayable as 
begin
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => TRUE, TARGETS => DBMS_APP_CONT.SIDE_EFFECTS, SCOPE => DBMS_APP_CONT.SCOPE_PARENT);
end mark_replayable;

begin 
insert into file_tab values (1,'file1.txt');
mark_replayable;
DBMS_FILE_TRANSFER.COPY_FILE(source_directory_object=>'SOURCEDIR', source_file_name=>'file1.txt', destination_directory_object=>'DGROUP', destination_file_name=>'file1.txt');
commit;
end

Replayable Interface Autonomous Transaction Use Cases

Replay is also disabled for autonomous transaction and DB link by default for TAC. Use DBMS_APP_CONT_ADMIN.SET_REPLAY_RULES or DBMS_APP_CONT.APPLY_REPLAY_RULE to allow or disallow autonomous transaction and DB link.

Use the following interface to allow autonomous transaction with TAC for entire service:

SQL> execute DBMS_APP_CONT_ADMIN.SET_REPLAY_RULES('Service_name',TRUE,dbms_app_cont.autonomous_transactions);
PL/SQL procedure successfully completed.

SQL> execute DBMS_APP_CONT_ADMIN.CHECK_REPLAY_RULES('Service_name'); 
PL/SQL procedure successfully completed. 
ResultSet #1 
TARGETS                     REPLAY
-----------------------     --------------------------------
PL/SQL Side Effects         disabled
Autonomous Transactions     enabled
Database Links              disabled

Use the following interface to allow autonomous transaction with TAC:

create or replace procedure log_update(description VARCHAR2) as 
    PRAGMA AUTONOMOUS_TRANSACTION;
BEGIN 
    INSERT INTO update_history VALUES (description, sysdate);
    COMMIT;
END log_update;  

begin 
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => TRUE, TARGETS => DBMS_APP_CONT.AUTONOMOUS_TRANSACTIONS);
insert into emp_tab('Andy', 100);
log_update('ID updated for user Andy');
commit;
end

Use the following interface to disallow autonomous transaction with AC:

create or replace procedure log_update(description VARCHAR2) as
    PRAGMA AUTONOMOUS_TRANSACTION;
BEGIN
    INSERT INTO update_history VALUES (description, sysdate); 
    COMMIT; 
END log_update;  

begin 
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => FALSE, TARGETS => DBMS_APP_CONT.AUTONOMOUS_TRANSACTIONS);
insert into emp_tab('Andy', 100);
log_update('ID updated for user Andy');
commit;
end

Use the following interface to allow DB Link with TAC for entire service:

SQL> execute DBMS_APP_CONT_ADMIN.SET_REPLAY_RULES('Service_name',TRUE,dbms_app_cont.database_links); 
PL/SQL procedure successfully completed.

SQL> execute DBMS_APP_CONT_ADMIN.CHECK_REPLAY_RULES('Service_name'); 
PL/SQL procedure successfully completed. 
ResultSet #1 
TARGETS                     REPLAY
-----------------------     --------------------------------
PL/SQL Side Effects         disabled
Autonomous Transactions     disabled
Database Links              enabled

Use the following interface to allow DB Link with TAC for the current code block:

create database link dblink connect to scott identified by tiger using 'dblink_service';
begin
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => TRUE, TARGETS => DBMS_APP_CONT.DATABASE_LINKS);
select emp_id,emp_name from emp@dblink_servie;
commit;
end

Use the following interface to disallow DB Link with AC for the current code block:

create database link dblink connect to scott identified by tiger using 'dblink_service';
begin
DBMS_APP_CONT.APPLY_REPLAY_RULE(REPLAYABLE => FALSE, TARGETS => DBMS_APP_CONT.DATABASE_LINKS);
select emp_id,emp_name from emp@dblink_service;
commit;
end

Related Topics

Understanding Enabling and Disabling Replay in Application Continuity