Connecting to Oracle AI Autonomous Database with SQLcl the Easy Way

Third-party tools don’t always offer much flexibility when connecting to Oracle AI Autonomous Database. In many cases, the connection code is fixed and can’t be modified.

Many shell scripts follow a pattern similar to this, but this issue isn’t purely related to shell scripts. Java, Python, .Net, you name it, typically follow the username/password/connection string pattern.

Shell

			
#!/usr/bin/env bash
set -euo pipefail
USERNAME=${1:-"undefined"}
PASSWORD=${2:-"undefined"}
CONNECT_STRING=${3:-"undefined"}
if [[ ${USERNAME} == undefined || ${PASSWORD} == undefined || ${CONNECT_STRING} == undefined ]]; then
  printf 'Usage: %s <username> <password> <connect_string>\n' "${0##*/}"
  exit 1
fi
echo INFO: about to connect to "${CONNECT_STRING}" as user "${USERNAME}"
sql /nolog <<EOF
connect ${USERNAME}/${PASSWORD}@${CONNECT_STRING}
select user from dual;
exit
EOF

		

The question this post answers is: how do you use this script, or similar ones, to connect to an Autonomous AI database with mutual TLS connection enabled? Without changing any code, because it’s a 3rd party script you don’t (source) control any of it at all.

SQLcl is Oracle’s command-line interface for Oracle Database, and it makes connecting to an Autonomous Database particularly easy. Command-line access remains important in many scenarios, for example, when deploying through CI/CD pipelines, working over SSH, or taking advantage of SQLcl’s scripting capabilities in general.

Let’s assume the following:

Your Autonomous AI Database is publicly available with mutual TLS connectivity
You downloaded the database wallet and stored it in ~/tns/blogpost/Wallet_blogpost.zip
SQLcl version 26.2.0.0 Production Build: 26.2.0.181.2110
The target Autonomous AI Database is named blogpost. Directory names reference the name to make it easier to correlate files to databases

Here is one way to connect to an Autonomous AI database using the above script without making any changes to it. First, you need to unzip the wallet, in this example into ~/tns/blogpost but it’s totally up to you where to store the unzipped files.

			
$ unzip Wallet_blogpost.zip -d ~/tns/blogpost
Archive:  Wallet_blogpost.zip
  inflating: ewallet.pem      
  inflating: README           
  inflating: cwallet.sso      
  inflating: tnsnames.ora     
  inflating: truststore.jks   
  inflating: ojdbc.properties  
  inflating: sqlnet.ora       
  inflating: ewallet.p12      
  inflating: keystore.jks 

		

Once unzipped you will see a bunch of new files in the directory. Now you can call the script:

			
$ source ./utils.sh
$ USER=soe
$ PASSWORD=$(get_password_from_vault "ocid1.vaultsecret.oc1....5ha" )
$ CONNECT_STRING="blogpost_tp?tns_admin=/home/martin/tns/blogpost"
$ ./connect.sh "${USER}" "${PASSWORD}" "${CONNECT_STRING}"

		

… and your connection should succeed

			
$ ./connect.sh "${USER}" "${PASSWORD}" "${CONNECT_STRING}"                       
INFO: about to connect to blogpost_tp?tns_admin=/home/martin/tns/blogpost as soe
SQLcl: Release 26.2 Production on Wed Jul 15 11:46:55 2026
Copyright (c) 1982, 2026, Oracle.  All rights reserved.
Connected.
USER    
_______ 
SOE     
Disconnected from Oracle AI Database 26ai Enterprise Edition Release 23.26.3.1.0 - Production
Version 23.26.3.1.0

		

Here is what happens in plain English:

utils.sh is sourced into the current session
It contains a function to look a password up from an OCI vault, named get_password_from_vault. It takes the OCI secret’s OCID as an argument
The CONNECT_STRING variable is made up of 2 parts, separated by the ? question mark
- The Autonomous database’s TNS alias, blogpost_tp. The tp service is a good choice for transactional workloads (🔗 more about service names in Autonomous AI Database)
- tns_admin points to the path the wallet was unzipped. According to a few tests you can specify the parameter in lower or upper-case, both work. With one exception: you can’t use the shorthand ~/tns/blogpost notation, it must be the fully qualified directory name. The option to provide tns_admin is documented for JDBC connections to Autonomous AI Database requiring a wallet.

That’s all there is to it. By specifying tns_admin as part of the EZConnect Plus connect string and storing the lot in an environment variable, you can connect to an Autonomous AI Database without modifying a single line of third-party code.

There are of course easier ways of implementing connections against Autonomous AI Database if you can indeed make changes:

Use the connection manager feature: save username, wallet location, and other details with a named connection, then call sql -name myConnection and all is done
Use the cloudconfig flag or set cloudconfig to point towards the wallet

Happy scripting!

SQLcl