Code for Continuous Availability

Your applications achieve continuous availability when planned maintenance, unplanned outages , and load imbalances of the database are hidden from the application. A combination of application best practice, simple configuration, and Oracle Autonomous AI Database ensure that your applications are continuously available.

The best approach for hiding planned maintenance activities from your applications is to transparently drain work from each database workload location prior to the maintenance window for that workload location. Oracle’s connection pools and mid-tiers, including the WebLogic Server, Oracle Universal Connection Pool (UCP), OCI Session pool and ODP.NET Unmanaged Provider are Fast Application Notification (FAN ) aware and therefore are notified before database services are scheduled to move to allow graceful draining of work before maintenance. FAN notification automatically triggers closing idle connections, opening new connections in the new service location, and allows a configurable time for active work to complete in the soon-to-be-shutdown service location. The major third-party JDBC mid-tiers, such as IBM WebSphere, allow for the same behavior when configured with UCP. For JDBC-based applications that cannot use UCP, Oracle provides solutions using Oracle Drivers and connection tests.

In order to hide unplanned outages resulting from a component or communication failure Oracle provides:

Notification. FAN is the first step to hiding outages. FAN notifies clients and breaks them out of their current network wait when an outage occurs. This avoids stalling applications for long network waits. Importantly, FAN also invokes rebalancing of sessions when services are available again.
Recovery. After the client is notified, Transparent Application Continuity (TAC) or Application Continuity (AC) re-establish a connection to a new workload location (another database instance in the Real Application Clusters (RAC) configuration running the database) and replays in-flight (uncommitted) work when possible. By replaying in-flight work on the new location, the application can usually continue executing without knowing that any failure happened.

TAC or AC also executes during planned maintenance for those sessions that do not drain (complete their current database operation) during the allocated drain interval.

Application Configuration Checklist

You make your application continuously available by following these guidelines:

Connect Using Database Services
Configure Connection String for High Availability
Use Fast Application Notification (FAN)
Use Recommended Practices to Allow Draining
Enable Transparent Application Continuity (TAC) or Application Continuity (AC)

Tip: See Continuous Availability for Applications on ATP-Direct White Paper to know about the best practices in implementing continuous availability for applications using an Autonomous AI Database.

Connect Using Database Services

Database services provide transparency for the underlying infrastructure: FAN, connection data, Transparent Application Continuity (TAC), Application Continuity (AC), switchover, consumer groups and many other features and operations are predicated on the use of services.

Autonomous AI Database on Dedicated Exadata Infrastructure offers several pairs of predefined database services to choose from, as described in Predefined Database Service Names for Autonomous AI Databases. All provide FAN and draining, and the two transaction processing pairs have TAC enabled by default. An API is available to change the TAC or AC settings on all predefined services (see Enable Service Attributes for Failover).

Configure Connection String for High Availability

Oracle recommends the Connection String configuration shown below when connecting to Oracle Autonomous AI Database. Connect strings embedded in the Oracle-supplied tnsnames.ora file are configured in this fashion. Do not use Easy Connect Naming on the client because such connections have no high-availability capabilities.

Use this TNS for all Oracle clients version 12.2 or higher:

alias =
(DESCRIPTION =
(CONNECT_TIMEOUT= 120)(RETRY_COUNT=20)(RETRY_DELAY=3)(TRANSPORT_CONNECT_TIMEOUT=3)
 (ADDRESS_LIST =
   (LOAD_BALANCE=on)
   (ADDRESS = (PROTOCOL = TCP)(HOST=*scan-host*)(PORT=1521)))
 (CONNECT_DATA=(SERVICE_NAME = *service-name*)))

Use the following for JDBC connections using Oracle driver version 12.1 or earlier

alias =
(DESCRIPTION =
(CONNECT_TIMEOUT= 15)(RETRY_COUNT=20)(RETRY_DELAY=3)
(ADDRESS_LIST =
  (LOAD_BALANCE=on)
  (ADDRESS = (PROTOCOL = TCP)(HOST=*scan-host*)(PORT=1521)))
(CONNECT_DATA=(SERVICE_NAME = *service-name*)))

Use Fast Application Notification (FAN)

FAN provides immediate notification to an application in the event of an outage or resumption of service. Without FAN, applications can hang on TCP/IP timeout following hardware and network failures, and omit to rebalance when resources resume. All Oracle pools and all Oracle application servers use FAN. Third-party JAVA application servers can use UCP to enable FAN.

No application changes are required to use FAN. These are configuration changes only.

For continuous service during planned maintenance, use FAN with:

Oracle pools or
UCP with third-party JDBC application servers or
The latest Oracle client drivers

For continuous service during unplanned outages, use FAN with:

Transparent Application Continuity or
Application Continuity

FAN Coverage

FAN events are integrated with:

Oracle Fusion Middleware and Oracle WebLogic Server
Oracle Data Guard Broker
Oracle JDBC Universal Connection Pool or Driver for both JDBC thin and Oracle Call Interface (OCI) interfaces
ODP.NET Connection Pool for Unmanaged and Managed Providers
Oracle Tuxedo
SQL*Plus
Oracle Database drivers for languages such as Python, Node.js and PHP
Global Data Services
Third party JDBC application servers using Oracle JDBC Universal Connection Pool
Listeners

To Enable FAN in the Client

Use the TNS alias shown in Configure Connection String for High Availability. This connection string is used to auto-configure the Oracle Notification Service (ONS) subscription at the client for FAN-event receipt when using an Oracle Database 12c or later client driver. ONS provides a secure communication path between the database tier and the client-tier allowing the client to be notified of service availability (components stopping or starting) as well as runtime load balancing advice for better work placement during normal operation.

Depending on the client, enable FAN in the application configuration properties as follows:

Universal Connection Pool or JDBC thin driver (starting 12.2)

Set the property FastConnectionFailoverEnabled.
WebLogic Active GridLink for Oracle

RAC FAN and Fast Connection Failover are enabled by default.
Oracle WebLogic Server, IBM WebSphere, IBM Liberty, Apache Tomcat, Red Hat WildFly (JBoss), JDBC Applications

Use Universal Connection Pool as a connection pool replacement.
ODP.Net clients (Managed and Unmanaged Providers)

Set "HA events = true;pooling=true" in the connect string if using ODP.Net 12.1 or earlier.
Oracle Call Interface (OCI) clients and OCI-based drivers

Oracle Call Interface (OCI) clients without native settings can use an oraacces.xml file and set events to true.

Python, Node.js and PHP have native options. In Python and Node.js you can set an events mode when creating a connection pool. In PHP, edit php.ini add the entry oci8.events=on.
SQL*Plus

FAN is enabled by default.

The predefined database services offer TCPS connections that use TLS wallet-based authentication. Depending upon the type of application (JDBC or Oracle Call Interface), the wallet configuration must follow particular rules, as described in Configure Clients for FAN Including Optional Wallets.

Use Recommended Practices to Allow Draining

Best practice for application usage is to check out connections for the time that they are needed, and then check them back in to the pool when the current action is complete. This is important to achieve good performance, for the rebalancing of work at runtime, and during maintenance windows for draining the work.

Oracle recommends using a FAN-aware Oracle connection pool for hiding planned maintenance. There is no impact to users when your application uses an Oracle Pool with FAN and returns connections to the pool between requests. You do not need to make any application changes to use FAN. When an Oracle connection pool receives the FAN event for planned downtime, it marks all connections at the instance to be drained. Immediately, checked-in connections are closed so that they are not re-used. As in-use connections are returned to the pool they are closed. This allows all connections to be closed gracefully over time.

If you are using a third-party, Java-based application server, then the most effective method to achieve draining and failover is to replace the pooled data source with UCP. Many application servers support this approach, including Oracle WebLogic Server, IBM WebSphere, IBM Liberty, Apache Tomcat, Red Hat WildFly (JBoss), Spring, Hibernate, and others. White papers from Oracle and other providers, such as IBM, describe how to use UCP with these application servers. Using UCP as the data source allows UCP features such as Fast Connection Failover, Runtime Load Balancing, Application Continuity and Transparent Application Continuity to be used with full certification.

Enable Transparent Application Continuity (TAC) or Application Continuity (AC)

TAC transparently tracks and records session and transactional state so that a database session can be recovered following recoverable outages. The two transaction processing pairs of predefined database services have TAC enabled by default.

AC is customizable, allowing you to choose to replay side effects or to add complex callbacks at failover that TAC does not allow. Use AC if you are using Oracle 12c drivers (JDBC-thin or Oracle Call Interface), or you want to customize with side effects or callbacks, or have an application that uses state such as session duration temp tables and does not clean up across requests.

Steps for Using Transparent Application Continuity

If you need to enable Transparent Application Continuity in the database service you are using, see Enable Service Attributes for Failover.
Use one of the following supported clients.

Oracle strongly recommends that you use the latest client drivers. Oracle Database 19c client drivers and later provide full support for TAC.
- Oracle JDBC Replay Driver 18c or later. This is a JDBC driver feature provided with Oracle Database 18c for Application Continuity.
- Oracle Universal Connection Pool (UCP) 18c or later with Oracle JDBC Replay Driver 18c or later.
- Oracle WebLogic Server Active GridLink, or third-party JDBC application servers using UCP with Oracle JDBC Replay Driver 18c or later.
- Java connection pools or standalone Java applications using Oracle JDBC Replay Driver 18c or later.
- Oracle Call Interface Session Pool 19c or later.
- SQL*Plus 19c (19.3) or later
- ODP.NET pooled, Unmanaged Driver 18c or later ("Pooling=true" default in 12.2 and later).
- Oracle Call Interface based applications using 19c OCI driver or later.
Return Connections to the Connections Pool.

You do not need to make any changes to your application for identifying request boundaries if the application uses connections:
- from the Oracle connection pools or
- from the Oracle JDBC Replay Driver 18c or later or
- from the Oracle Call Interface based applications using 19c or later
When using connection pools, the application should return the connection to the pool on completion of each request. Oracle recommends that an application checks out a connection only for the time it needs it. Holding a connection when not in use is not good practice. Transparent Application Continuity with the listed drivers also detects where boundaries can be added and makes its own boundaries.
Use FAILOVER_RESTORE

Enabling Transparent Application Continuity automatically restores preset session states. If you find that you need preset session states in addition to the standard set, then you can register a callback or UCP label to restore these states. If you find that you need complex session states, such as temporary tables or SYS_CONTEXT, restored, then use Application Continuity that offers this flexibility.
Enable Mutable Use in the Application

Mutable functions are functions that can return a new value each time they are executed. Support for keeping the original results is provided for SYSDATE, SYSTIMESTAMP, SYS_GUID, and sequence.NEXTVAL. Application Continuity 19c and later automatically KEEPs mutables for SQL. If your application uses, or is sensitive to, mutable functions, then a DBA must issue the GRANT KEEP privilege. When KEEP privilege is granted, replay applies the original function result at replay. For example:
```
SQL> GRANT [KEEP DATE TIME | KEEP SYSGUID] ... TO USER
```
```
SQL> GRANT KEEP SEQUENCE mySequence TO myUser ON sequence.object
```
Side Effects Are Disabled

A side effect is an external action such as sending mail, transferring files or using TCP. Transparent Application Continuity detects side effects and does not replay them. If you want the side effects replayed, then use Application Continuity that allows this extra flexibility.

Steps for Using Application Continuity

If you need to enable Application Continuity in the database service you are using, see Enable Service Attributes for Failover.
Use one of the following supported clients.
- Oracle JDBC Replay Driver 12c or later. This is a JDBC driver feature provided with Oracle Database 12c for Application Continuity.
- Oracle Universal Connection Pool (UCP) 12c or later with Oracle JDBC Replay Driver 12c or later.
- Oracle WebLogic Server Active GridLink and third-party JDBC application servers using UCP with Oracle JDBC Replay Driver 12c or later.
- Java connection pools or standalone Java applications using Oracle JDBC Replay Driver 12c or later with Request Boundaries or Pooled Data Source.
- Applications and language drivers using Oracle Call Interface Session Pool 12c Release 2 or later.
- SQL*Plus 19.3 or later.
- ODP.NET pooled, Unmanaged Driver 12c Release 2 or later ("Pooling=true";"Application Continuity=true" default in 12.2 and later)
Return Connections to the Connections Pool.

You do not need to make any changes to your application for identifying request boundaries if the application is using an Oracle connection pool or a third-party JDBC pool that supports request boundaries. It is best practice to use an Oracle pool and return the connections to that pool between requests. Oracle recommends that an application checks out a connection only for the time it needs it. Holding a connection when not in use is not good practice, and it will prevent transparent planned maintenance.
Use FAILOVER_RESTORE

Most common states are restored automatically with FAILOVER_RESTORE=LEVEL1. If your application presets session states in addition to the standard set, then you must register a callback, or UCP label, to restore these states. Set FAILOVER_RESTORE=LEVEL1 on the service and use:
- Connection Initialization Callback for Java or the (older) TAF Callback for Oracle Call Interface or
- Universal Connection Pool or WebLogic Server Connection Labelling
Enable Mutable Use in the Application

Mutable functions are functions that can return a new value each time they are executed. Support for keeping the original results is provided for SYSDATE, SYSTIMESTAMP, SYS_GUID, and sequence.NEXTVAL. Application Continuity 19c and later automatically KEEPs mutables for SQL, so no action is required. If you need mutables for PL/SQL, then a DBA must issue the GRANT KEEP privilege. When KEEP privilege is granted, replay applies the original function result at replay. For example:
```
SQL> GRANT [KEEP DATE TIME | KEEP SYSGUID] ... TO USER
```
```
SQL> GRANT KEEP SEQUENCE mySequence TO myUser ON sequence.object
```
Decide If You Want to Replay Side Effects

A side effect is an external action such as sending mail, transferring files or using TCP. With Application Continuity, side effects are replayed unless the application specifies otherwise. If a request has an external action that should not be replayed, then that request can use a connection that does not have Application Continuity enabled, or replay can be disabled for that request using the disableReplay() API for Java or OCIRequestDisableReplay() for Oracle Call Interface. If you do not wish to replay all side effects, use Transparent Application Continuity.