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)

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 Database on Dedicated Exadata Infrastructure offers several pairs of predefined database services to choose from, as described in Predefined Database Service Names for Autonomous 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).

Oracle recommends the Connection String configuration shown below when connecting to Oracle Autonomous 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)))

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.

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.

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.