Oracle Bequeath Connection Explained: Complete Guide with SQLcl and ORDS Examples

Everything About Oracle Bequeath Connections

What's a Bequeath Connection?

A bequeath connection is an Oracle-specific connection method (protocol) that allows a client to connect directly to a database instance, bypassing the TNS listener.

Instead of using TCP/IP, the client requests a dedicated server process locally using IPC (inter-process communication).

📌 Key Requirement

The client and the database must be on the same server (same OS).

📌 Why Use Bequeath Connections?

• Improved performance: The connection does not use TCP/IP. Communication happens via local IPC, which is faster for local connections.
• OS authentication (no database password required): Since the connection is local, the database checks the OS user account instead of a database password. The user must belong to the OSDBA group (for example, the dba group on Linux).

How It Works: Connection Flow

1. The listener receives a client connection request.
2. The listener starts a dedicated server process.
3. The listener provides the location of the dedicated server process to the client in a redirect message.
4. The client connects directly to the dedicated server.

Examples with Common Clients

1. SQLcl and Bequeath Connection

Important Notes

• The connection is to CDB$ROOT. You cannot connect directly to a specific PDB because the listener is bypassed (you can switch containers later using ALTER SESSION).
• When connecting as SYS, no password is required because the database checks the OS user account instead.
• If you want to connect to a specific container using a specific user, you must use the regular connection method by providing credentials and the target container.

Connect as SYSDBA (no password needed):

sql / as sysdba

Connect with username/password:

sql user/password

Connect to a specific SID:

sql user/password@<SID>

2. ORDS and Bequeath Connections

Bequeath connections can be used to install or upgrade ORDS. Below are the full steps to follow.

Important Notes

• ORDS and the database must be on the same server.
• The following environment variable must be set: -DuseOracleHome=true. This forces ORDS to use the JDBC driver shipped with the database.
• If omitted, you may encounter JDBC incompatibility errors such as:

Incompatible version of libocijdbc[Jdbc:23702501, Jdbc-OCI:23902507]

This happens because the database JDBC version is 23.9.0.25.07 while ORDS ships with 23.7.0.25.01. Bequeath connections require the JDBC driver version to match the database version.

Step 1: Export Required Environment Variables

export LD_LIBRARY_PATH=<path-to-db-library>
export ORACLE_HOME=<path-to-oracle-home>
export ORACLE_SID=<SID>
export PATH=$PATH:$ORACLE_HOME/bin:.

Step 2: Launch Non-Interactive ORDS Install

Option A: Using basic connection parameters (hostname, port, SID)

./ords --java-options -DuseOracleHome=true \
  --config <PATH TO CONFIG> \
  install \
  --bequeath-connect \
  --db-hostname <DB HOST> \
  --db-port <DB PORT> \
  --db-sid <DB SID> \
  --feature-sdw true

Option B: Using TNS

First, create a tnsnames.ora entry:

<TNS ALIAS> =
  (DESCRIPTION =
    (ADDRESS =
      (PROTOCOL = TCP)
      (HOST = <DB HOST>)
      (PORT = <DB PORT>)
    )
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = <DB SERVICE NAME>)
    )
  )

Then run ORDS install with TNS:

./ords --java-options -DuseOracleHome=true \
  --config <PATH TO CONFIG> \
  install \
  --bequeath-connect \
  --db-tns-alias <TNS ALIAS> \
  --db-tns-dir <PATH TO TNS DIRECTORY> \
  --feature-sdw true

Summary

Bequeath connections are a powerful feature for local Oracle database connectivity. They offer better performance through IPC instead of TCP/IP and support OS authentication for simplified access. While they require the client and database to be on the same server, they're particularly useful for administrative tasks, installations, and local development environments.