Quick Start: Java applications with Oracle AI Database

1. Provision an Oracle AI Database and consider connection options

Oracle Autonomous AI Database Serverless

Click here to provision an ADB-S instance.

Secure connections are required. Both TLS and mTLS are supported.

On-premises Oracle AI Database, Oracle AI Database Free, and Oracle AI Database cloud instance

Click here to provision an Oracle AI Database Free instance.Configurations support but do not require TLS or mTLS and they are not configured by by default.

Depending on the database and security configuration, the connection may use one of the following:

• TCP: Unencrypted TCP/IP connection.
• TCPS with TLS: Encrypted connection where the client validates the database server certificate.
• TCPS with mTLS: Encrypted connection where both the client and the database authenticate each other. This requires a wallet or Java KeyStore containing the client credential

You can configure security, download wallets, and see connection strings on the Oracle AI Database console pages.

2. Install and verify a supported JDK

Install a Java Development Kit that is supported by the Oracle JDBC driver version you plan to use.

Install the JDK: JDK8, JDK11, JDK17, JDK21 and JDK25 are long term support releases.

The selected JDK, JDBC driver artifact, and Oracle AI Database version must be compatible.

For Oracle AI Database 26ai JDBC drivers, use the current Oracle JDBC download and support guidance to choose the correct driver artifact for your JDK. For example, use ojdbc17.jar when your application runs on JDK 17, ojdbc11.jar for JDK 11, and ojdbc8.jar for JDK 8.

For Maven or Gradle projects, confirm that the build tool uses the same supported JDK version that the application will use at runtime.

3. Download and update the sample Java program

Download the appropriate sample Java file and update with connection information

Download the appropriate sample file. Be sure to save the file in a directory with path src/main/java/com/oracle/jdbctest

• For Oracle AI Database Autonomous Serverless, use ADBQuickStart.java (com.oracle.jdbctest.ADBQuickStart) and update the following values
  • DB_USER - database user name (for example, ADMIN or your application user)
  • DB_PASSWORD - database password
  • DB_URL - TNS connection string or TNS alias. The TNS alias is listed in the tnsnames.ora file in the wallet directory.
    • TLS:  jdbc:oracle:thin:@<TLS_connection_string>
    • mTLS: jdbc:oracle:thin:@<TNS_alias>?TNS_ADMIN=/path/to/wallet
  • TNS_ADMIN - Wallet directory (mTLS only)
• For Oracle AI Database Free, on-premises Oracle AI Database, and Oracle AI Database cloud instances, use QuickStart.java (com.oracle.jdbctest.QuickStart).src/main/java/com/oracle/jdbctest 

  and update:

  • DB_USER – Database user (for example, SYSTEM, HR, or your application user)
  • DB_PASSWORD – Database password
  • DB_URL – JDBC Thin connection string. For example, for Oracle AI Database Free...
    • jdbc:oracle:thin:@//<host>:<port>/<service_name>
    • jdbc:oracle:thin:@//localhost:1521/FREEPDB1
  
  

4. Build and run (standalone, with Maven, with Gradle)

Build and run standalone (no frameworks)

Download the Oracle JDBC full archive that matches your JDK from here and extract it to a local `lib` directory.

Compile the appropriate java file:

• javac -classpath "./lib/*" com/oracle/jdbctest/ADBQuickStart.java
  
• javac -classpath "./lib/*" com/oracle/jdbctest/QuickStart.java

Run the appropriate class:

• java -classpath "./lib/*:." com.oracle.jdbctest.ADBQuickStart
• java -classpath "./lib/*:." com.oracle.jdbctest.QuickStart

You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database.

Build and run with Maven

• Create a Maven project and add the Oracle JDBC production dependency to the pom.xml:

  <dependency>             

     <groupId>com.oracle.database.jdbc</groupId>       <artifactId>ojdbc17-production</artifactId>   

     <version>23.26.2.0.0</version>              

     <type>pom</type></dependency>

• Build and run appropriate class:
  • mvn compile ; mvn exec:java -Dexec.mainClass=com.oracle.jdbctest.ADBQuickStart
  • mvn compile ; mvn exec:java -Dexec.mainClass=com.oracle.jdbctest.QuickStart
You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database.

Build and run with Gradle

• Add the Oracle JDBC dependency to your build.gradle:
• .dependencies {         
  implementation("com.oracle.database.jdbc:ojdbc8-production:23.26.2.0.0")
}
• Set the appropriate main class:
  • application { mainClass =     'com.oracle.jdbctest.ADBQuickStart' }
  • application { mainClass =     'com.oracle.jdbctest.ADBQuickStart }
    
    
• Run: gradle run
You will see the queried rows returned from the database and a message Congratulations! You have successfully used Oracle Autonomous Database

5. Troubleshooting

If the sample fails, check the following:

• Confirm that you selected the correct database environment and sample Java file.
• Confirm that DB_USER, DB_PASSWORD, and DB_URL are correct.
• For Oracle AI Database Autonomous Serverless using TLS, confirm that the database allows TLS connections.
• For Oracle AI Database Autonomous Serverless using mTLS, confirm that TNS_ADMIN points to the directory where you unzipped the wallet.
• For Oracle AI Database Free, on-premises Oracle AI Database, or an Oracle AI Database cloud instance, confirm that the host, port, service name, listener, and database user are correct.
• Confirm that your command line or IDE is using a supported JDK.
• Confirm that the Oracle JDBC and UCP JAR files match the JDK you are using.
• If you connect to ADB from behind a firewall, you will likely encounter a connection timeout error. Make sure to be outside the firewall while running this sample or update the tnsnames.ora file to use an HTTPS proxy. Learn how to do this in "JDBC Thin Connections with an HTTP Proxy" section of the ADB documentation.