Connect Liquibase to Oracle Database using Oracle Internet Directory

Last updated: March 24, 2026

Oracle Internet Directory (OID) is an LDAP-based directory service that centralizes TNS name resolution. When configured, Liquibase resolves database service names through LDAP instead of a local tnsnames.ora file. This requires an active OID server with the target service published in the directory.

Note: You can combine OID-based name resolution with Oracle Wallet credential storage. See Using Oracle Wallet with Liquibase to store credentials in a wallet rather than in liquibase.properties.

Before you begin

Install Liquibase
Ensure Java is installed.
Obtain the following from your Oracle DBA: OID server hostname, LDAP port (typically 389 for non-SSL, 636 for SSL), and the default admin context (e.g., dc=company,dc=com).

Procedure

Download Oracle JDBC driver

All JARs are available from the Oracle JDBC Downloads page and Maven Central. Replace 21.13.0.0 with the latest 21.x release.

Download the following JARs from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar — required
oraclepki.jar, osdt_core.jar, osdt_cert.jar — optional, required only when using Oracle Wallet alongside OID

# Required
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar

# Optional — only if using Oracle Wallet alongside OID
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"

# Optional — only if using Oracle Wallet alongside OID
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Download the following JARs from the Oracle JDBC Downloads page and place them in your lib/ directory.

ojdbc11.jar — required
oraclepki.jar, osdt_core.jar, osdt_cert.jar — optional, required only when using Oracle Wallet alongside OID

# Required
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/ojdbc11.jar

# Optional — only if using Oracle Wallet alongside OID
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/oraclepki.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_core.jar
wget https://download.oracle.com/otn-pub/otn_software/jdbc/211/osdt_cert.jar

mkdir -p lib
curl -L -o lib/ojdbc11.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/jdbc/ojdbc11/21.13.0.0/ojdbc11-21.13.0.0.jar"

# Optional — only if using Oracle Wallet alongside OID
curl -L -o lib/oraclepki.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/oraclepki/21.13.0.0/oraclepki-21.13.0.0.jar"
curl -L -o lib/osdt_core.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_core/21.13.0.0/osdt_core-21.13.0.0.jar"
curl -L -o lib/osdt_cert.jar \
  "https://repo1.maven.org/maven2/com/oracle/database/security/osdt_cert/21.13.0.0/osdt_cert-21.13.0.0.jar"

Configure ldap.ora

Create an Oracle Net administration directory (for example, ~/tns-admin) and add ldap.ora to point to your OID server.

Be sure to:

Replace your_admin_context with your LDAP admin context. For example, dc=company,dc=com, dc=myorg,dc=local
Replace your_oid_host with your OID server hostname. For example, oid.company.com, ldap.myorg.local
Replace your_ldap_port with your LDAP port. Usually, 389
Replace your_ldap_ssl_port with your LDAP SSL port. Usually, 636

# Base DN for your directory — matches your company's LDAP structure
DEFAULT_ADMIN_CONTEXT = "your_admin_context"

# OID server address(es): (host:ldap-port:ldaps-port)
# For failover, add multiple servers separated by commas:
# DIRECTORY_SERVERS = (oid1.company.com:389:636, oid2.company.com:389:636)
DIRECTORY_SERVERS = (your_oid_host:your_ldap_port:your_ldap_ssl_port)

# OID = Oracle Internet Directory
# AD = Microsoft Active Directory (also supports Oracle TNS resolution)
DIRECTORY_SERVER_TYPE = OID

Configure sqlnet.ora

Create sqlnet.ora in the same directory to set LDAP as the primary name resolution method.

# LDAP first — OID is queried before local tnsnames.ora
NAMES.DIRECTORY_PATH = (LDAP, TNSNAMES, EZCONNECT)

# Required for Oracle 19c+ JDBC
DISABLE_OOB = TRUE

# Optional: append this domain to unqualified service names
# NAMES.DEFAULT_DOMAIN = company.com

# Optional: wallet alongside OID (uncomment if using wallet for credentials)
# WALLET_LOCATION =
#   (SOURCE =
#     (METHOD = FILE)
#     (METHOD_DATA =
#       (DIRECTORY = /path/to/your/wallet)
#     )
#   )
# SQLNET.WALLET_OVERRIDE = TRUE

Configure JDBC properties

Create ojdbc.properties pointing to your TNS admin directory.

Be sure to:

Replace your_tns_admin_dir with your absolute path to your TNS admin directory. For example, /home/user/tns-admin, /Users/name/tns-admin

# Absolute path to the directory containing ldap.ora and sqlnet.ora
oracle.net.tns_admin=your_tns_admin_dir

# Optional: authenticated LDAP bind (only if your OID requires login to query)
# oracle.net.ldap.user=cn=orcladmin,dc=company,dc=com
# oracle.net.ldap.password=your-ldap-admin-password

Configure Liquibase

Create liquibase.properties in your working directory. Option A is the standard setup using a TNS alias resolved through OID. Options B and C are inline alternatives for when TNS_ADMIN cannot be set. Option D uses Oracle Wallet for credentials (no username or password in the file).

Be sure to:

Replace your_tns_alias with the service name published in OID. For example, MYSERVICE, ORCL
Replace your_username with your database username (Options A, B, C only)
Replace your_password with your database password (Options A, B, C only)
Replace your_oid_host with your OID server hostname (Options B and C only). For example, oid.company.com
Replace your_ldap_port with your LDAP port (Option B only). Usually, 389
Replace your_ldap_ssl_port with your LDAPS port (Option C only). Usually, 636
Replace your_admin_context with your LDAP admin context (Options B and C only). For example, dc=company,dc=com
Replace your_wallet_dir with the absolute path to your Oracle Wallet directory (Option D only). For example, /home/user/oracle-wallet

# liquibase.properties — Oracle OID connection

# Option A: TNS alias via LDAP — standard enterprise setup; requires TNS_ADMIN
url=jdbc:oracle:thin:/@your_tns_alias
driver=oracle.jdbc.OracleDriver
username=your_username
password=your_password
changeLogFile=changelog.xml
classpath=lib/ojdbc11.jar

# Option B: Inline LDAP URL — when you cannot set TNS_ADMIN
# url=jdbc:oracle:thin:@ldap://your_oid_host:your_ldap_port/your_tns_alias,cn=OracleContext,your_admin_context
# driver=oracle.jdbc.OracleDriver
# username=your_username
# password=your_password
# changeLogFile=changelog.xml
# classpath=lib/ojdbc11.jar

# Option C: Inline LDAPS URL — when your OID uses SSL (recommended for production)
# url=jdbc:oracle:thin:@ldaps://your_oid_host:your_ldap_ssl_port/your_tns_alias,cn=OracleContext,your_admin_context
# driver=oracle.jdbc.OracleDriver
# username=your_username
# password=your_password
# changeLogFile=changelog.xml
# classpath=lib/ojdbc11.jar

# Option D: With Oracle Wallet (no username or password — the wallet supplies credentials)
# url=jdbc:oracle:thin:/@your_tns_alias
# driver=oracle.jdbc.OracleDriver
# changeLogFile=changelog.xml
# classpath=lib/ojdbc11.jar:lib/oraclepki.jar:lib/osdt_core.jar:lib/osdt_cert.jar
# # ojdbc.properties must point oracle.net.wallet_location to your_wallet_dir

Set environment variables

Set the following environment variables before running Liquibase.

export TNS_ADMIN=~/tns-admin
export LIQUIBASE_ORACLE_DISABLE_OOB=true

Register your Oracle service in OID (DBA task)

Your DBA or directory admin must create an LDAP entry in OID for each Oracle service that Liquibase should connect to. Create a file named service.ldif with the following content.

Be sure to:

Replace MYSERVICE with your Oracle service name
Replace dc=company,dc=com with your LDAP admin context
Replace db.company.com with your Oracle DB hostname

dn: cn=MYSERVICE,cn=OracleContext,dc=company,dc=com
objectClass: top
objectClass: orclNetService
cn: MYSERVICE
orclNetDescString: (DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCP)(HOST=db.company.com)(PORT=1521))
  (CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=MYSERVICE)))

For SSL (TCPS), replace the orclNetDescString with:

orclNetDescString: (DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCPS)(HOST=db.company.com)(PORT=2484))
  (CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=MYSERVICE))
  (SECURITY=(SSL_SERVER_CERT_DN="CN=db.company.com,OU=...,O=...")))

Load the LDIF file with ldapadd.

Be sure to:

Replace oid.company.com with your OID server hostname
Replace cn=orcladmin,dc=company,dc=com with your LDAP admin DN
Replace your_admin_password with your LDAP admin password

ldapadd -h oid.company.com -p 389 \
        -D "cn=orcladmin,dc=company,dc=com" \
        -w your_admin_password \
        -f service.ldif

Run Liquibase

Run Liquibase against your OID-configured database. The inline option at the end lets you run without a liquibase.properties file.

Be sure to:

Replace your_oid_host with your OID server hostname (inline option only)
Replace your_ldap_port with your LDAP port (inline option only). Usually, 389
Replace your_tns_alias with your service name (inline option only)
Replace your_admin_context with your LDAP admin context (inline option only). For example, dc=company,dc=com
Replace your_username and your_password with your database credentials (inline option only)

# Check connection and pending changesets
liquibase --defaults-file=liquibase.properties status

# Apply all pending changesets
liquibase --defaults-file=liquibase.properties update

# Roll back the last N changesets
liquibase --defaults-file=liquibase.properties rollback-count 1

# Roll back to a tag
liquibase --defaults-file=liquibase.properties rollback myTagName

# Run without a properties file (inline LDAP URL)
liquibase \
  --classpath=lib/ojdbc11.jar \
  --url="jdbc:oracle:thin:@ldap://your_oid_host:your_ldap_port/your_tns_alias,cn=OracleContext,your_admin_context" \
  --username=your_username \
  --password=your_password \
  --changeLogFile=changelog.xml \
  update