Connect Liquibase to Oracle Database using Oracle Internet Directory

Last updated: July 9, 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

If you are connecting using an inline LDAP URL (for example, jdbc:oracle:thin:@ldap://your_oid_host:port/...), skip to Step 4: Configure Liquibase. Steps 1–3 are only required if you are connecting using a TNS alias.

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

To connect using a TNS alias (Option A), you must also install Oracle Instant Client 23c. It provides the OCI native libraries (for example, ocijdbc23.dll on Windows) that the jdbc:oracle:oci driver requires. Earlier versions such as 19c will not work. The inline LDAP URL options (B and C) use the thin driver and do not need Instant Client.

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 enterprise setup. Liquibase resolves the TNS alias through OID at connect time using the Oracle OCI driver (which requires Oracle Instant Client 23c), so you never hard-code OID server details in your properties file. Options B and C use the thin driver, embed the OID server address directly in the URL, and do not require ldap.ora or sqlnet.ora. To use Oracle Wallet for credentials, see Using Oracle Wallet with Liquibase.

Be sure to:

Replace your_tns_alias with the service name registered in OID. For example, MYSERVICE, ORCL
Replace your_username with your database username
Replace your_password with your database password
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 dc=your_domain,dc=com with your LDAP admin context (Options B and C only). For example, dc=company,dc=com

# liquibase.properties — Oracle Internet Directory (OID) connection

# Option A: TNS alias via LDAP — OID resolves the service name (uses the OCI driver)
# Requires: Oracle Instant Client 23c installed (provides the OCI native libraries,
#   e.g. ocijdbc23.dll on Windows), plus ldap.ora + sqlnet.ora + ojdbc.properties configured
liquibase.command.url=jdbc:oracle:oci:/@your_tns_alias
liquibase.command.username=your_username
liquibase.command.password=your_password
liquibase.command.changelogFile=changelog.xml
liquibase.classpath=lib/ojdbc11.jar

# Option B: Inline LDAP URL — no ldap.ora or sqlnet.ora required
# Use when you prefer a self-contained URL or are not using TNS admin files
# liquibase.command.url=jdbc:oracle:thin:@ldap://your_oid_host:your_ldap_port/your_tns_alias,cn=OracleContext,dc=your_domain,dc=com
# liquibase.command.username=your_username
# liquibase.command.password=your_password
# liquibase.command.changelogFile=changelog.xml

# Option C: Inline LDAPS URL — when your OID server uses SSL (recommended for production)
# liquibase.command.url=jdbc:oracle:thin:@ldaps://your_oid_host:your_ldap_ssl_port/your_tns_alias,cn=OracleContext,dc=your_domain,dc=com
# liquibase.command.username=your_username
# liquibase.command.password=your_password
# liquibase.command.changelogFile=changelog.xml

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