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

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.ipv4.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

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

1. Download the latest JDBC-thin driver.

   From the page Oracle Database JDBC driver and Companion Jars Downloads:

   • Select a driver version 23.4 or higher from the available drivers under Oracle Database 23ai 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

2. Download the Oracle JDBC TCP Fast Open (TFO) Library File.
   1. On the page Oracle Database JDBC driver and Companion Jars Downloads, expand Oracle JDBC TCP Fast Open (TFO) Library v1
   2. Download the native library .zip 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.

3. Load the native library in the environment where you run your application.

   Set the following environment variables in the library path:

   1. Export LD_PRELOAD.
      export LD_PRELOAD=path_to/libtfojdbc1.so;
   2. 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;
   3. 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;
4. 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 

     Or

     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)))

5. Run the application.

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

1. 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.

2. Add the use_tcp_fast_open connection parameter when you connect to an Autonomous Database instance.

   For example, use this option with one of:

   • oracledb.connect()

   • oracledb.connect_async()

   • oracledb.create_pool()

   • oracledb.create_pool_async()

   See Connect Python Applications to Autonomous AI Database for more information.

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.

1. 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.

2. 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