Using Oracle Wallet with Liquibase

Last updated: March 24, 2026

Oracle Wallet is a secure credential store that allows Liquibase to connect to Oracle Database without embedding usernames or passwords in configuration files. The Oracle JDBC Thin driver automatically resolves credentials from the wallet using a TNS alias. Your folder structure will look like this:

Before you begin

Install Liquibase
Ensure Java is installed. If you used the Liquibase Installer, Java is included automatically.
Install Oracle Client Tools (included with Oracle Database, Oracle Instant Client, or Oracle Database Client) to obtain the mkstore and orapki utilities used in this procedure.
Obtain connection details from your Oracle DBA: hostname, port, service name, username, and password.

Procedure

Download Oracle JDBC drivers

You need 4 JAR files to enable Oracle Wallet support. Choose your preferred method:

Go to the Oracle JDBC Downloads page.
Download the appropriate JDBC driver for your Oracle version.
Extract and copy these files to your Liquibase lib/ directory:
- ojdbc8.jar (or ojdbc11.jar for Oracle 21c+)
- oraclepki.jar
- osdt_core.jar
- osdt_cert.jar

# Find the JAR files
find $ORACLE_HOME -name "ojdbc*.jar"
find $ORACLE_HOME -name "oraclepki.jar"
find $ORACLE_HOME -name "osdt_core.jar"
find $ORACLE_HOME -name "osdt_cert.jar"

# Common locations:
# $ORACLE_HOME/jdbc/lib/ojdbc8.jar
# $ORACLE_HOME/jlib/oraclepki.jar
# $ORACLE_HOME/jlib/osdt_core.jar
# $ORACLE_HOME/jlib/osdt_cert.jar

# Pull Oracle image (free - no login required)
docker pull container-registry.oracle.com/database/express:21.3.0-xe

# Start container
docker run -d --name temp-oracle container-registry.oracle.com/database/express:21.3.0-xe

# Wait for startup (2-3 minutes)
sleep 180

# Copy JAR files out
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jdbc/lib/ojdbc8.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/oraclepki.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/osdt_core.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/osdt_cert.jar .

# Stop and remove container
docker stop temp-oracle && docker rm temp-oracle

Go to the Oracle JDBC Downloads page.
Download the appropriate JDBC driver for your Oracle version.
Extract and copy these files to your Liquibase lib/ directory:
- ojdbc8.jar (or ojdbc11.jar for Oracle 21c+)
- oraclepki.jar
- osdt_core.jar
- osdt_cert.jar

# Find the JAR files
find $ORACLE_HOME -name "ojdbc*.jar"
find $ORACLE_HOME -name "oraclepki.jar"
find $ORACLE_HOME -name "osdt_core.jar"
find $ORACLE_HOME -name "osdt_cert.jar"

# Common locations:
# $ORACLE_HOME/jdbc/lib/ojdbc8.jar
# $ORACLE_HOME/jlib/oraclepki.jar
# $ORACLE_HOME/jlib/osdt_core.jar
# $ORACLE_HOME/jlib/osdt_cert.jar

# Pull Oracle image (free - no login required)
docker pull container-registry.oracle.com/database/express:21.3.0-xe

# Start container
docker run -d --name temp-oracle container-registry.oracle.com/database/express:21.3.0-xe

# Wait for startup (2-3 minutes)
sleep 180

# Copy JAR files out
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jdbc/lib/ojdbc8.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/oraclepki.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/osdt_core.jar .
docker cp temp-oracle:/opt/oracle/product/21c/dbhomeXE/jlib/osdt_cert.jar .

# Stop and remove container
docker stop temp-oracle && docker rm temp-oracle

Create your wallet folder structure

Create the directory structure for your wallet and JAR files.

# Create your wallet directory (choose any location)
mkdir -p ~/oracle-wallet/wallet
mkdir -p ~/oracle-wallet/lib

# Copy the 4 JAR files to lib folder
cp ojdbc8.jar ~/oracle-wallet/lib/
cp oraclepki.jar ~/oracle-wallet/lib/
cp osdt_core.jar ~/oracle-wallet/lib/
cp osdt_cert.jar ~/oracle-wallet/lib/

Create Oracle Wallet

Set the following environment variables.

Be sure to:

Replace your_oracle_home with the path to your Oracle Client installation. For example, /opt/oracle/product/21c/dbhomeXE, /usr/lib/oracle/19c/client64, /opt/instantclient_21_1

export WALLET_DIR=~/oracle-wallet/wallet
export ORACLE_HOME=your_oracle_home

Create the wallet. When prompted, enter and confirm a wallet password.

mkstore -wrl $WALLET_DIR -create

Add your database credentials to the wallet, where your_tns_alias matches the TNS alias you will define in tnsnames.ora. Be sure to:

Replace your_tns_alias with your TNS alias. This must match the alias you define in tnsnames.ora. For example, MY_DB, PROD_DB, DEV_DB
Replace your_username with your database username. For example, myuser, system, admin
Replace your_password with your database password.

mkstore -wrl $WALLET_DIR -createCredential your_tns_alias your_username your_password

Verify the credential was stored.

mkstore -wrl $WALLET_DIR -listCredential

Create tnsnames.ora

Create tnsnames.ora in your wallet directory.

Be sure to:

Replace your_tns_alias with your TNS alias. This must match the alias used in the mkstore command. For example, MY_DB, PROD_DB, DEV_DB
Replace your_hostname with your hostname. For example, localhost, mydb.example.com, 192.168.1.100
Replace your_port with your port. Usually. For example, 1521
Replace your_service_name with your service name. For example, XEPDB1, ORCL, PROD

your_tns_alias =
  (DESCRIPTION =
    (ADDRESS = (PROTOCOL = TCP)(HOST = your_hostname)(PORT = your_port))
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = your_service_name)
    )
  )

Create sqlnet.ora

Create sqlnet.ora in your wallet directory to point the JDBC driver to your wallet.

Be sure to:

Replace your_wallet_dir with your absolute path to your wallet directory. For example, /home/user/oracle-wallet/wallet, /Users/name/oracle-wallet/wallet

NAMES.DIRECTORY_PATH = (TNSNAMES, EZCONNECT)
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = your_wallet_dir)
    )
  )
SQLNET.WALLET_OVERRIDE = TRUE
DISABLE_OOB = TRUE

Configure JDBC properties

Create ojdbc.properties in your wallet directory.

Be sure to:

Replace your_wallet_dir with your absolute path to your wallet directory. For example, /home/user/oracle-wallet/wallet, /Users/name/oracle-wallet/wallet

oracle.net.wallet_location=(SOURCE=(METHOD=FILE)(METHOD_DATA=(DIRECTORY=your_wallet_dir)))

Configure Liquibase

Create or update liquibase.properties in your project directory. The URL uses /@your_tns_alias. You don't need a username or password,

Be sure to:

Replace your_tns_alias with your TNS alias from tnsnames.ora. For example, MY_DB, PROD_DB, DEV_DB
Replace your_lib_path/ in the classpath with the absolute path to your JAR files. You must include all 4 JAR files for wallet support. For example, /home/user/oracle-wallet/lib/, /Users/name/oracle-wallet/lib/

liquibase.command.url=jdbc:oracle:thin:/@your_tns_alias
liquibase.command.changelogFile=db.changelog-master.xml
liquibase.classpath=your_lib_path/ojdbc11.jar:your_lib_path/oraclepki.jar:your_lib_path/osdt_core.jar:your_lib_path/osdt_cert.jar

Set environment variables

Set the following environment variables before running Liquibase.

export TNS_ADMIN=~/oracle-wallet

To make these permanent, add them to your shell profile.

echo 'export TNS_ADMIN=~/oracle-wallet' >> ~/.bashrc
source ~/.bashrc

Test your setup

Verify that all required files are in place.

# Check wallet files
ls -la ~/oracle-wallet/wallet/

# Check configuration files
ls -la ~/oracle-wallet/*.ora

# Check JAR files
ls -lh ~/oracle-wallet/lib/

Test the connection with Liquibase. Be sure to navigate to your Liquibase project.

liquibase validate

If validation passes, check the changelog status:

liquibase status

A successful connection returns the number of pending changesets (or confirms the changelog is up to date).