Chapter 3

Connect to Autonomous Database

Feature Area Database Actions Cards

Development SQL, Data Modeler, REST, JSON, Charts, Scheduling, Oracle
Machine Learning, Graph Studio, and Oracle APEX
Data Studio Data Load, Catalog, Data Insights, Data Transforms, and Data
Analysis
Administration Database Users, APEX Workspaces, Data Pump, Download
Client Credentials, and Set Resource Management Rules
Monitoring Performance Hub and Database Dashboard
Downloads Download Oracle Instant Client and Download SODA Drivers
Related Services Restful Data Services (ORDS) and SODA and Access Oracle
Machine Learning Restful Services

See About Database Actions in Using Oracle Database Actions for more information.

Access Database Actions as ADMIN

Database Actions (also known as SQL Developer Web) is bundled with each
Autonomous Database instance.
Database Actions runs in Oracle REST Data Services and access is provided through
schema-based authentication. To use Database Actions, you must sign in as a
database user whose schema is enabled for Database Actions. By default the ADMIN
user is enabled to access Database Actions.
See Provide Database Actions Access to Database Users to enable another database
user's schema to access Database Actions.

Note:
If your Autonomous Database is configured to use a Private Endpoint, then
you can only access Database Actions from clients in the same Virtual Cloud
Network (VCN).
See Configuring Network Access with Private Endpoints for more
information.

To access Database Actions from the Oracle Cloud Infrastructure Console:

1. On the Autonomous Database Details page click the Database actions dropdown
list.
2. Select a quick link to go directly to a quick link action or select View all database
actions to access the full Database Actions Launchpad.
For example, click SQL to use a SQL Worksheet. On the SQL Worksheet you can
use the Consumer Group drop-down list to select the consumer group to run your
SQL or PL/SQL code. See Executing SQL Statements in the Worksheet Editor for
more information.
Depending on your browser, if the Console cannot access the database as ADMIN you
will be prompted for your database ADMIN username and password.

3-54
 Chapter 3
Connect to Autonomous Database

Provide Database Actions Access to Database Users

The ADMIN user provides access to Database Actions for other database users.
Database users who are not service administrators do not have access to the Oracle Cloud
Infrastructure Console. The ADMIN user provides access to Database Actions as follows:
• Use Database Actions to create a user and assign roles to the user. If the user already
exists, check that Web Access is selected for the schema (with Web Access selected, the
user's card shows REST Enabled).
See Create Users on Autonomous Database for information on adding database users.
See Required Roles to Access Tools from Database Actions for information on required
roles for Database Actions.
• Provide the user with a URL to access Database Actions.
After adding a user and selecting Web Access, the ADMIN provides a user with the URL to
access Database Actions:

1. In Database Actions, click to show the available actions.

2. Under Administration select Database Users.
This displays information about users, such as user names, whether a user is REST
Enabled, and the last login date and time. On a user's card, the icon on the left displays
the user status with one of the following colors: green (Open), blue (Locked), or red
(Expired).
The default view is Card View. You can select either grid view or card view by clicking the
Card View or Grid View icons.
3. A URL is displayed in the user's card only if the user is REST Enabled. It provides the
URL to access Database Actions. Click to copy the URL to the clipboard.

3-55
 Chapter 3
Connect to Autonomous Database

4. Provide the user with the URL you copied.

After you provide the URL to a user, to access Database Actions the user pastes the
URL into their browser and then enters their Username and Password in the Sign-in
dialog.
See Manage Users and User Roles on Autonomous Database - Connecting with
Database Actions for more information.

Required Roles to Access Tools from Database Actions

Lists the database roles required to use the built-in Autonomous Database tools.
When you connect to Database Actions as the ADMIN user, many database roles are
set to allow you to access the available Autonomous Database tools. When you
connect to Database Actions as a non-ADMIN user, some of the Database Actions
cards for Autonomous Database tools are hidden if you do not have required
permissions.
As the ADMIN user, set the appropriate roles to allow user access to Autonomous
Database tools. See Manage User Roles and Privileges on Autonomous Database for
more information.

Autonomous Database Required Role More Information

Tool
Oracle Machine Learning OML_DEVELOPER Oracle Machine Learning
(OML)
Graph Studio GRAPH_DEVELOPER Using Oracle Graph with Autonomous
Database
Data Studio (including: DWROLE The Data Studio Overview Page
Catalog, Data Load, Data
Analysis, Data Insights)
Data Transforms DATA_TRANSFORM_US
ER

3-56
 Chapter 3
Connect to Autonomous Database

Access Database Actions, Oracle APEX, Oracle REST Data Services, and
Developer Tools Using a Vanity URL
By default you access Oracle APEX apps, REST endpoints, and developer tools on
Autonomous Database using the oraclecloudapps.com domain name. You can optionally
configure a vanity URL or custom domain name that is easy to remember to help promote
your brand identity.
After you acquire a desired domain name and matching SSL certificate from a vendor of your
choice, deploy an Oracle Cloud Infrastructure Load Balancer in your Virtual Cloud Network
(VCN) using your Autonomous Database as the backend. Your Autonomous Database
instance must be configured with a private endpoint in the same VCN. See Configuring
Network Access with Private Endpoints for more information.
To learn more, see the following:
• Introducing Vanity URLs for APEX and ORDS on Oracle Autonomous Database
• Automate Vanity URL Configuration Using Terraform

Connect with JDBC Thin Driver

Autonomous Database mandates a secure connection that uses Transport Layer Security
(TLSv1.2).
Java applications that use JDBC Thin driver connect with one of the following:
• Mutual TLS (mTLS) Authentication: requires either Oracle Wallet or Java KeyStore
(JKS) where both the client and Autonomous Database authenticate each other.
The wallet and keystore files are included in the client credentials .zip file that is
available by clicking Database connection on the Oracle Cloud Infrastructure Console
• TLS Authentication: The client computer matches the server’s CA root certificate
against the client’s list of trusted CAs. If the issuing CA is trusted, the client verifies that
the certificate is authentic. This allows the client and Autonomous Database to establish
the encrypted connection before exchanging any messages.
• JDBC Thin Connections with a Wallet (mTLS)
Autonomous Database mandates a secure connection that uses Transport Layer Security
(TLSv1.2). Depending on the network configuration options, Autonomous Database
supports mTLS and TLS authentication.
• JDBC Thin TLS Connections Without a Wallet
Autonomous Database mandates a secure connection that uses Transport Layer Security
(TLSv1.2). Depending on the configuration options, Autonomous Database supports
mTLS and TLS authentication. This section covers using JDBC Thin Connections with
TLS authentication without a wallet.

3-57
 Chapter 3
Connect to Autonomous Database

JDBC Thin Connections with a Wallet (mTLS)

Autonomous Database mandates a secure connection that uses Transport Layer
Security (TLSv1.2). Depending on the network configuration options, Autonomous
Database supports mTLS and TLS authentication.

Note:
If you use TLS (instead of mTLS) for your connections using JDBC Thin
Driver with JDK8u162 or higher, a wallet is not required.

TLS connections are enabled for the following network configurations:

• Private endpoint access only: network configuration with a private

endpoint
• Secure access from allowed IPs and VCNs only: configuration with an
Access Control List (ACL)
If your Autonomous Database is on a public endpoint without any ACL,
you can add 0.0.0.0/0 as your CIDR ACL and enable TLS
authentication. Adding 0.0.0.0/0 as your CIDR ACL is identical to
having your Autonomous Database on public endpoint with no ACL.
See About TLS Authentication for more information.

• JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS)

Applications that use JDBC Thin driver support TLS and mutual TLS (mTLS)
authentication. Using mTLS authentication requires that you supply Oracle
database credentials including the Oracle wallets or Java KeyStore (JKS) files
when connecting to the database.
• Using a JDBC URL Connection String with JDBC Thin Driver and Wallets
The connection string is found in the file tnsnames.ora which is part of the client
credentials download. The tnsnames.ora file contains the predefined service
names. Each service has its own TNS alias and connection string.
• Using a JDBC Connection with 18.3 JDBC Driver
Applications that use JDBC Thin driver can connect to Autonomous Databases
using either Oracle Wallets or Java KeyStore (JKS).
• Connecting Using JDBC Thin Driver 12.2 or Older
If you are using the JDBC driver 12.2.0.2 or older, set the Java properties prior to
starting the application. Usually you set the properties in the application's startup
script.
• JDBC Thin Connections with an HTTP Proxy
If the client is behind a firewall and your network configuration requires an HTTP
proxy to connect to the internet, you need to use the JDBC Thin Client 18.1 or
higher which enables connections through HTTP proxies.

3-58
 Chapter 3
Connect to Autonomous Database

JDBC Thin Driver Connection Prerequisites Connections with Wallets (mTLS)

Applications that use JDBC Thin driver support TLS and mutual TLS (mTLS) authentication.
Using mTLS authentication requires that you supply Oracle database credentials including
the Oracle wallets or Java KeyStore (JKS) files when connecting to the database.
Perform the following steps before connecting to the database:
1. Provision Autonomous Database: Create a database and obtain your database
credentials (username and password).
2. For mutual TLS connections, Download Client Credentials: Unzip the
wallet_databasename.zip to a secure location. Make sure that only authorized users
have access to these files.
See Download Client Credentials (Wallets) for information on downloading client
credentials for Autonomous Database.
3. Verify your JDK version for security: If you are using JDK11, JDK10, or JDK9 then you
don’t need to do anything for this step. If your JDK version is less than JDK8u162 then
you need to download the JCE Unlimited Strength Jurisdiction Policy Files. Refer to the
README file for installation notes. Download the JCE files from Java Cryptography
Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 Download.
4. Check JDBC Driver Version: Download a supported JDBC Thin driver (ojdbc8.jar
and ucp.jar). You also need the additional jars: oraclepki.jar, osdt_core.jar,
and osdt_cert.jar for use with Oracle wallets.
Supported versions are:
• JDBC Thin: 11.2.0.4 (or later with one-off patch for Bug 28492769), 12.2 (or later
with one-off patch for Bug 28492769), 18 (base release or later with one-off patch for
Bug 28492769), 19 (base release or later), or 21 (base release or later)
For applications that use the Universal Connection Pool (UCP) feature of JDBC, it is
highly recommended to use 19.13 or higher or 21.3 or higher versions of the JDBC driver.
These versions include proper draining behavior to minimize impact to applications when
planned maintenance is performed in Autonomous Database. UCP will replenish
connections in the pool proactively so that active connections are not impacted by
maintenance.
For older versions of the driver, a patch for bug 31112088 can also be requested by filing
a Service Request.
Download supported versions: Oracle Database JDBC driver and Companion Jars
Downloads .

Using a JDBC URL Connection String with JDBC Thin Driver and Wallets
The connection string is found in the file tnsnames.ora which is part of the client
credentials download. The tnsnames.ora file contains the predefined service names. Each
service has its own TNS alias and connection string.
A sample entry, with dbname_high as the TNS alias and a connection string in
tnsnames.ora follows:

dbname_high= (description=
(address=(protocol=tcps)(port=1522)(host=adb.example.oraclecloud.com))

3-59
 Chapter 3
Connect to Autonomous Database

(connect_data=(service_name=dbname_high.oraclecloud.com))
(security=(ssl_server_dn_match=yes)))

Set the location of tnsnames.ora with the property TNS_ADMIN in one of the following
ways:
• As part of the connection string (only with the 18.3 or newer JDBC driver)
• As a system property, -Doracle.net.tns_admin
• As a connection property (OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN)
Using the 18.3 JDBC driver, the connection string includes the TNS alias and the
TNS_ADMIN connection property.

Sample connection string using 18.3 JDBC driver (Linux):

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/
wallet_dbname"

Sample connection string using 18.3 JDBC driver (Windows):

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=C:\\Users\\test\
\wallet_dbname"

The TNS_ADMIN connection property specifies the following:

• The location of tnsnames.ora.

• The location of Oracle Wallet (ewallet.sso, ewallet.p12) or Java KeyStore
(JKS) files (truststore.jks, keystore.jks).
• The location of ojdbc.properties. This file contains the connection properties
required to use Oracle Wallets or Java KeyStore (JKS).

Note:
If you are using 12.2.0.1 or older JDBC drivers, then the connection string
contains only the TNS alias. To connect using older JDBC drivers:
• Set the location of the tnsnames.ora, either as a system property with
-Doracle.net.tns_admin or as a connection property
(OracleConnection.CONNECTION_PROPERTY_TNS_ADMIN).
• Set the wallet or JKS related connection properties in addition to
TNS_ADMIN.
For example, in this case you set the TNS alias in the DB_URL without the
TNS_ADMIN part as:

DB_URL=”jdbc:oracle:thin:@dbname_high”

See Predefined Database Service Names for Autonomous Database for more details.

3-60
 Chapter 3
Connect to Autonomous Database

Using a JDBC Connection with 18.3 JDBC Driver

Applications that use JDBC Thin driver can connect to Autonomous Databases using either
Oracle Wallets or Java KeyStore (JKS).

Using Oracle Wallet

To use Java and the 18.3 JDBC Thin Driver to connect to Autonomous Database with the
Oracle Wallet, do the following:
1. Make sure that the prerequisites are met: See JDBC Thin Driver Connection
Prerequisites Connections with Wallets (mTLS) for more information.
2. Verify the connection: You can either use a Java program, a servlet, or IDEs to verify
the connection to the database. A simple test is to download DataSourceSample.java or
UCPSample.java from JDBC code samples and update the connection URL to have the
required TNS alias and pass TNS_ADMIN, providing the path for tnsnames.ora and the
wallet files. Also, in the sample source code update the database username and
password. For example:

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/wallet_dbname"

Note:
If you are using Microsoft Active Directory with a database, then in the sample
source code update the username with the Active Directory username and
update the password with the Active Directory user password. See Use
Microsoft Active Directory with Autonomous Database for more information.

3. Set the wallet location: The properties file ojdbc.properties is pre-loaded with the
wallet related connection property.

oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=$
{TNS_ADMIN})))

Note:
You do not modify the file ojdbc.properties. The value of TNS_ADMIN
determines the wallet location.

4. Compile and Run: Compile and run the sample to get a successful connection. Make
sure you have oraclepki.jar , osdt_core.jar, and osdt_cert.jar, in the classpath.
For example:

java –classpath
./lib/ojdbc8.jar:./lib/ucp.jar:./lib/oraclepki.jar:./lib/
osdt_core.jar:./lib/osdt_cert.jar:. UCPSample

3-61
 Chapter 3
Connect to Autonomous Database

Note:
The auto-login wallet part of Autonomous Database downloaded client
credentials zip file removes the need for your application to use username/
password authentication.

Using Java KeyStore

To use Java and the 18.3 JDBC Thin Driver to connect to Autonomous Database with
Java KeyStore (JKS), do the following:
1. Make sure that the prerequisites are met: See JDBC Thin Driver Connection
Prerequisites Connections with Wallets (mTLS) for more information.
2. Ready the database details: You can either use a Java program, a servlet, or
IDEs to check the connection to your database. A simple test is to download
DataSourceSample.java or UCPSample.java from JDBC code samples. In this
sample, use the connection URL as shown. Note that the connection DB_URL
contains the TNS alias, for example, dbname_high present in tnsnames.ora. You
can provide the path for tnsnames.ora file through TNS_ADMIN property as shown
in the URL. Make sure to use the database username and password related to
your database.

DB_URL="jdbc:oracle:thin:@dbname_high?TNS_ADMIN=/Users/test/
wallet_dbname"

Note:
If you are using Microsoft Active Directory with Autonomous Database,
then make sure to change the sample source code to use the Active
Directory username and the Active Directory user password. See Use
Microsoft Active Directory with Autonomous Database for more
information.

3. Set JKS related connection properties: Add the JKS related connection
properties to ojdbc.properties file. The keyStore and truststore password are
the password specified when you downloading the client credentials .zip file.
To use SSL connectivity instead of Oracle Wallet, specify the keystore and
truststore files and their respective password in the ojdbc.properties file as
follows:

# Properties for using Java KeyStore (JKS)

oracle.net.ssl_server_dn_match=true
javax.net.ssl.trustStore==${TNS_ADMIN}/truststore.jks
javax.net.ssl.trustStorePassword=password
javax.net.ssl.keyStore==${TNS_ADMIN}/keystore.jks
javax.net.ssl.keyStorePassword=password

3-62
 Chapter 3
Connect to Autonomous Database

Note:
Make sure to comment the wallet related property in ojdbc.properties. For
example:

# Property for using Oracle Wallets

# oracle.net.wallet_location=(SOURCE=(METHOD=FILE)
(METHOD_DATA=(DIRECTORY=${TNS_ADMIN})))

4. Compile and Run: Compile and run the sample to get a successful connection. For
example:

java –classpath ./lib/ojdbc8.jar:./lib/ucp.jar UCPSample

Connecting Using JDBC Thin Driver 12.2 or Older

If you are using the JDBC driver 12.2.0.2 or older, set the Java properties prior to starting the
application. Usually you set the properties in the application's startup script.
If you are not able to use the latest 18.3 JDBC drivers, then you can connect to Autonomous
Database using 12.2.0.2 or other older JDBC drivers. The 12.2 or older JDBC drivers do not
support the ojdbc.properties file. With older JDBC driver versions, you need to pass
wallets or JKS related properties either as system properties or as connection properties to
establish a connection.

Using Oracle Wallet

To use Java and the 12.2 or older JDBC Drivers to connect to Autonomous Database with the
Oracle Wallet, do the following:
1. Make sure that the prerequisites are met: See JDBC Thin Driver Connection
Prerequisites Connections with Wallets (mTLS) for more information.
2. Verify the connection: You can either use a Java program, a servlet, or IDEs to verify
the connection to the database. A simple test is to download DataSourceSample.java or
UCPSample.java from JDBC code samples and update the connection URL to have the
required TNS alias. Also, update the sample source code to use the database username
and password. For example:

DB_URL="jdbc:oracle:thin:@dbname_high”

Note:
If you are using Microsoft Active Directory with Autonomous Database, then
update the sample source code to use the Active Directory username and
Active Directory user password. See Use Microsoft Active Directory with
Autonomous Database for more information.

3-63