Use TCP Fast Open (TFO) to Connect Clients to Autonomous AI Database

If your application is sensitive to network latency and you want to decrease the network latency between your application and the database, you can enable TCP Fast Open (TFO).

Depending on the characteristics of your application, TFO connections can improve application performance by decreasing network latency for client connections.

Prerequisites for TCP Fast Open (TFO) Connections

Lists the prerequisites to use TCP Fast Open (TFO) connections with Autonomous AI Database.

To use TCP Fast Open (TFO) to connect to an Autonomous AI Database instance, the client application requires the following:

The client must run on a VM in Oracle Cloud Infrastructure.
One of the following must be true:
- The Autonomous AI Database is on a private endpoint.
- When the Autonomous AI Database is on a public endpoint, the routing rules between the client VM and the database must be configured so that the traffic goes through a Service Gateway.
  
  See Access Autonomous AI Database with Service Gateway and Configure Network Access with Private Endpoints for more information.
The VM must be running on Linux. Supported platforms are: Oracle Linux x86_64 and Oracle Linux Arm (aarch64).
The following OS level kernel parameters must be set:
- As root user, set the following parameters:
  - sysctl -w net.ipv 4.tcp_fastopen=5
  - sysctl -w net.ipv4.tcp_fastopen_blackhole_timeout_sec=0
  Verify the OS level kernel parameter values:
```
cat /proc/sys/net/ipv4/tcp_fastopen
5
cat /proc/sys/net/ipv4/tcp_fastopen_blackhole_timeout_sec
0
```

JDBC Thin Connections with TCP Fast Open

Describes the requirements to use JDBC Thin connections with TCP Fast Open (TFO) on Autonomous AI Database.

Assure that the client environment and client prerequisites are met. See Prerequisites for TCP Fast Open (TFO) Connections for more information.

To use JDBC with TCP Fast Open (TFO), perform the following steps:

Download the latest JDBC-thin driver.

From the page Oracle AI Database JDBC driver and Companion Jars Downloads:
- Select a driver version 23.4 or higher from the available drivers under Oracle AI Database 26ai JDBC Driver & UCP Downloads - Free Release.
- Select a driver version 19.23 or higher from the available drivers under Oracle Database 19c JDBC Driver & UCP Downloads - Long Term Release
Download the Oracle JDBC TCP Fast Open (TFO) Library File.
- On the page Oracle AI Database JDBC driver and Companion Jars Downloads, expand Oracle JDBC TCP Fast Open (TFO) Library v1
- Download the native library compressed file for your client platform:
  - JDBC TFO Library for Linux x86_64, library file for “x86_64” for Linux on Intel.
  - JDBC TFO Library for Linux AARCH64 library file for “arm64” for Linux on Arm.
Load the native library in the environment where you run your application.

Set the following environment variables in the library path:
- Export LD_PRELOAD.
  
  export LD_PRELOAD=path_to/libtfojdbc1.so;
- If you are using JDK 8, export LD_LIBRARY_PATH.
  
  For example:
  
  export LD_LIBRARY_PATH=path_of_libtfojdbc1.so:path_to/jdk_8_home/jre/lib/amd64:path_to/jdk_8_home/jre/lib/amd64/server;
- If you are using JDK 17, export LD_LIBRARY_PATH.
  
  For example:
  
  export LD_LIBRARY_PATH=extracted_binaries_path:path_to/jdk_17_home/lib;

Enable the TCP Fast Open (TFO) option for your application.

The following shows some of the options for enabling TFO in the client connection to the database:

In the client application, set the following connection property:

properties.put(OracleConnection.CONNECTION_PROPERTY_NET_USE_TCP_FAST_OPEN, "true");

By default the property OracleConnection.CONNECTION_PROPERTY_NET_USE_TCP_FAST_OPEN is set to false (disabled).

Add the TFO property in the JDBC URL.

For example:

jdbc:oracle:thin:@tcps://xxx.adb.yyy.oraclecloud.com:1521/zzz.adb.oraclecloud.com?oracle.net.useTcpFastOpen=true

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=xxx.adb.yyy.oraclecloud.com) (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=zzz.adb.oraclecloud.com)))?oracle.net.useTcpFastOpen=true

Add the following TNS parameter in the CONNECT_DATA section of the connection URL.

For example:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=xxx.adb.yyy.oraclecloud.com)(PORT=1521))
        (CONNECT_DATA=(USE_TCP_FAST_OPEN =ON)(SERVICE_NAME=zzz.adb.oraclecloud.com)))

Add the following TNS parameter in the CONNECT_DATA section of the connection URL.

For example:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcps)(HOST=xxx.adb.yyy.oraclecloud.com)(PORT=1521))(CONNECT_DATA=(TFO=ON)(SERVICE_NAME=zzz.adb.oraclecloud.com)))

Run the application.

TCP Fast Open Connections with Python

Describes the requirements to use Python with TCP Fast Open (TFO) connections on Autonomous AI Database.

Assure that the client environment and client prerequisites are met. See Prerequisites for TCP Fast Open (TFO) Connections for more information.

To use Python with TCP Fast Open (TFO), perform the following steps:

Install Python and the python-oracledb Driver.

Use the latest version of python-orabledb (Version 2.1.0 or newer is required).

See Install Python and the python-oracledb Driver for more information.
Add the use_tcp_fast_open connection parameter when you connect to an Autonomous AI Database instance.

For example, use this option with one of:
See Connect Python Applications to Autonomous AI Database for more information.

TCP Fast Open Connections with Oracle Call Interface Client for C or SQL*Plus Connections

Describes the requirements to use Oracle Call Interface Client with TCP Fast Open (TFO) to connect with C or SQL*Plus to Autonomous AI Database.

Assure that the client environment and client prerequisites are met. See Prerequisites for TCP Fast Open (TFO) Connections for more information.

Note: You can enable TCP Fast Open (TFO) with either mTLS or TLS connections. See Secure Connections to Autonomous AI Database with mTLS or with TLS and Update Network Options to Allow TLS or Require Only Mutual TLS (mTLS) Authentication on Autonomous AI Database for more information.

To use Oracle Call Interface with TCP Fast Open (TFO), perform the following steps:

Download the latest Oracle instant client for Linux, either version 23.4 or higher or 19.23 or higher.

See Oracle Instant Client Downloads for Linux x86-64 (64-bit) for Linux x86-64.

See Oracle Instant Client Downloads for Linux ARM (aarch64) for Linux ARM.

Connect with the USE_TCP_FAST_OPEN parameter set to the value YES.

For example, add the parameter USE_TCP_FAST_OPEN to connect_data in the connection string you use to connect to Autonomous AI Database:

(description= (retry_count=20)(retry_delay=3)(address=(protocol=tcps)
   (port=1522)(host=example.us-phoenix-1.oraclecloud.com))
   (connect_data= (USE_TCP_FAST_OPEN=yes)(service_name=example_medium.adb.oraclecloud.com))
       (security=(ssl_server_dn_match=yes)))

Or set the sqlnet.ora parameter:

USE_TCP_FAST_OPEN=yes