Pro 4.33: Use native executors with Oracle Database

Use native executors with Oracle Database

Last updated: January 23, 2026

This page describes how to use Liquibase with the SQL Plus native executor on an Oracle database.

Before you begin

Download and install Liquibase (version 3.10.0+).
Add SQL Plus to your PATH environment variable. Alternatively, pass its location in the liquibase.sqlplus.conf file or from the command prompt during runtime.
To use Liquibase and SQLCMD with Windows Integrated Security, follow the steps from Using Liquibase and MSSQL Server with Windows Integrated Security.

Procedure

Setup

Liquibase searches the executor location in the following order: runtime arguments, .conf file values, and then your PATH.

Add the runWith attribute to the needed changesets in the changelog:

SQL: runWith:sqlplus
XML: runWith="sqlplus"
YAML: runWith: sqlplus
JSON: "runWith": "sqlplus"

Specify the SQL Plus integration arguments in one of the following ways

Specify the SQL Plus integration arguments in one of the following ways:

Pass the values at runtime on the command line.
Add the values to liquibase.sqlplus.conf or the Liquibase properties file.
Set the values as environment variables.
Run the values as Java system properties (JAVA_OPTS) along with any command at the command prompt.

Setup examples

set JAVA_OPTS=-Dliquibase.sqlplus.<option>=<value> && liquibase <command> --changelog-file=my_script.sql

export JAVA_OPTS=-Dliquibase.sqlplus.<option>=<value> && liquibase <command> --changelog-file=my_script.sql

set JAVA_OPTS=-Dliquibase.sqlplus.<option>=<value> && liquibase <command> --changelog-file=my_script.sql

export JAVA_OPTS=-Dliquibase.sqlplus.<option>=<value> && liquibase <command> --changelog-file=my_script.sql

Run a Liquibase command

Any Liquibase command will work. You can use.

liquibase status --changelog-file=my_script.sql

Note: If the command fails, you will receive an error message. However, if you add a property that is not used in Liquibase to the liquibase.sqlplus.conf file, no error occurs. Liquibase only ignores it.

SQL Plus integration arguments

Note: Syntax for each parameter is specified in kebab-case (CLI and flow file), camelCase (properties file and JAVA_OPTS), and MACRO_CASE (environment variable).

Syntax (`--cli`, `propertiesFile`, `ENV_VAR`)	Type	Description
--sqlplus-args liquibase.sqlplus.args LIQUIBASE_SQLPLUS_ARGS	String	Defines extra arguments to pass to the `sqlplus` executable. For more information, see SQL Plus documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
--sqlplus-create-spool liquibase.sqlplus.createSpool LIQUIBASE_SQLPLUS_CREATE_SPOOL	Boolean	If `true`, create an Oracle spool file which captures the SQLPlus output. Default: `true`. When `create spool = false`, the spool file does not generate.
--sqlplus-keep-temp liquibase.sqlplus.keep.temp LIQUIBASE_SQLPLUS_KEEP_TEMP	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of SQL Plus. If `true`, the file is not deleted. This setting is not required to keep the temporary file, only `create-spool` is. Default: `false`.
--sqlplus-keep-temp-name liquibase.sqlplus.keep.temp.name LIQUIBASE_SQLPLUS_KEEP_TEMP_NAME	String	Indicates the name of a temporary SQL file after the execution of SQL Plus. If no file name is specified, a name is automatically generated. In Oracle, if no file extension is specified, the file is saved as `.lst`.
--sqlplus-keep-temp-overwrite liquibase.sqlplus.keep.temp.overwrite LIQUIBASE_SQLPLUS_KEEP_TEMP_OVERWRITE	Boolean	Overwrites any files in the specified directory with the same name. Default: `true`.
--sqlplus-keep-temp-path liquibase.sqlplus.keep.temp.path LIQUIBASE_SQLPLUS_KEEP_TEMP_PATH	String	Specify the path in which to store the temporary files after the execution of SQL Plus. If not specified, the files will be stored in the system's `temp` directory.
--sqlplus-password liquibase.sqlplus.password LIQUIBASE_SQLPLUS_PASSWORD	String	Liquibase 4.29.2+. Password to use with the native executor, such as the password for an account with SYSDBA privileges. Liquibase will attempt to use the password exactly as entered.
--sqlplus-path liquibase.sqlplus.path LIQUIBASE_SQLPLUS_PATH	String	Path to `sqlplus` executable. For example: Linux: `/opt/oracle/product/19.0.0/client/bin/sqlplus` or `/u01/app/oracle/product/19.0.0/dbhome_1/bin/sqlplus` Windows: `C:\oracle\product\19.0.0\dbhome_1\bin\sqlplus.exe`
--sqlplus-sqlerror liquibase.sqlplus.sqlerror LIQUIBASE_SQLPLUS_SQLERROR	String	Control the outcome when Liquibase returns a SQL error. The error clause is passed directly to Oracle. Default: `WHENEVER SQLERROR EXIT FAILURE`. Accepted values include: `WHENEVER SQLERROR EXIT FAILURE` `WHENEVER SQLERROR EXIT ROLLBACK` `WHENEVER SQLERROR EXIT ERROR` `WHENEVER SQLERROR EXIT WARNING` `WHENEVER SQLERROR EXIT SUCCESS`
--sqlplus-timeout liquibase.sqlplus.timeout LIQUIBASE_SQLPLUS_TIMEOUT	Integer	Indicates seconds to wait for the `sqlplus` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).
--sqlplus-username liquibase.sqlplus.username LIQUIBASE_SQLPLUS_USERNAME	String	Liquibase 4.29.2+. Username to use with the native executor, such as `account.username as sysdba` to access Liquibase with an account that has SYSDBA privileges. Liquibase will attempt to use the name exactly as entered.

Examples

--liquibase formatted sql

--changeset myauthorname:2314 runWith:sqlplus

    DECLARE l_emp_name VARCHAR2(250);
    l_emp_no NUMBER;
    l_salary NUMBER;

    l_manager VARCHAR2(250);
    BEGIN
    INSERT INTO emp(emp_name,emp_no,salary,manager) VALUES('BBB',1000,25000,'AAA');

    ...
    END;
    /

<?xml version="1.0" encoding="UTF-8"?>

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/pro
        http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">

    <changeSet id="2" author="myauthorname" runWith="sqlplus"> 
        <sql>
            DECLARE l_emp_name VARCHAR2(250);
            l_emp_no NUMBER;
            l_salary NUMBER;
            l_manager VARCHAR2(250);
               BEGIN
            INSERT INTO emp(emp_name,emp_no,salary,manager) VALUES('BBB',1000,25000,'AAA');
            ...
            END;
            /
        </sql> 

    </changeSet>

</databaseChangeLog>

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/pro
        http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">					

    <changeSet id="2315" author="myauthorname" runWith="sqlplus">  
        <sqlFile
        path="my/path/file.sql"
    ... > 
    </changeSet>

</databaseChangeLog>

databaseChangeLog:
   - changeSet:
       id: 1-yaml
       author: myauthorname
       runWith: sqlplus
       changes:
       - sqlFile:
           path: person.sql
           relativeToChangelogFile: true

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1-json",
        "author": "myauthorname",
        "runWith": "sqlplus",
        "changes": [
          {
            "sqlFile": {
              "path": "person.sql",
              "relativeToChangelogFile": "true"
            }
          }
        ]
      }
    ]
  }
}

####
##   Note about relative and absolute paths:
##      The liquibase.sqlplus.path must be a valid path to the SQLPlUS executable.
##      The liquibase.sqlplus.timeout value can be one of:
##      -1    - disable the timeout
##      Any integer value > 0 (measured in seconds)
##      
####

# The full path to the SQLPLUS executable.
# Sample Linux path
# liquibase.sqlplus.path=/apps/app/12.2.0.1.0/oracle/product/12.2.0.1.0/client_1/bin/sqlplus
# Sample Windows path
# liquibase.sqlplus.path=c:\\oracle\\product\\11.2.0\\client_1\\bin\\sqlplus.exe

# A valid timeout value for the execution of the SQLPLUS tool
liquibase.sqlplus.timeout=-1

# Flag to indicate whether or not to keep the temporary SQL file after execution of SQLPLUS.
# True = keep False = delete (default)
liquibase.sqlplus.keep.temp=true

# OPTIONAL Flag to designate the location to store temporary SQL file after execution of SQLPLUS.
# Liquibase will attempt to use path exactly as entered, so please ensure it complies with your OS requirements.
# liquibase.sqlplus.keep.temp.path=

# OPTIONAL Flag to designate the name of temporary SQL file after execution of SQLPLUS.
# Liquibase will attempt to use the name exactly as entered, so please ensure it complies with your OS requirements.
# liquibase.sqlplus.keep.temp.name=

# OPTIONAL Args to pass directly to SQLPLUS.
# Learn about SQLPLUS args at https://docs.oracle.com/cd/B10501_01/server.920/a90842/ch4.htm
# Note: The delimiter for args is a space eg:" " and not "," or ";" separated.
# liquibase.sqlplus.args=

Use native executors with Oracle Database

Before you begin

Procedure

Setup

Specify the SQL Plus integration arguments in one of the following ways

Setup examples

Windows

macOS/Linux

Run a Liquibase command

SQL Plus integration arguments

Examples

Formatted SQL changeset using the runWith attribute

XML changelog with the inline SQL changeset using the runWith attribute

XML changelog pointing to a SQL file with raw SQL in it

YAML changelog pointing to an SQL file with raw SQL in it

JSON changelog pointing to an SQL file with raw SQL in it

Example liquibase.sqlplus.conf file