Use SQL Plus and `runWith` on Oracle

Prerequisites

Use Liquibase 3.10 or later.
Specify how Liquibase can find SQL Plus by adding SQL Plus to your PATH. Alternatively, pass its location in the liquibase.sqlplus.conf file or from the command prompt during runtime. See liquibase.sqlplus.path in SQL Plus integration arguments.

Note: Liquibase searches the SQL Plus location in the following order: runtime arguments, .conf file values, your PATH.

Using the SQL Plus integration

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

runWith:sqlplus for an SQL changelog
runWith="sqlplus" for an XML changelog
"runWith": "sqlplus" for a JSON changelog
runWith: sqlplus for a YAML changelog

Note: See runWith and sqlplus examples.

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

Add the values to liquibase.sqlplus.conf or the Liquibase properties file.

Note: You can use the liquibase.sqlplus.conf file along with the Liquibase properties file. If you use Liquibase Pro and SQL Plus in automation, set arguments in the liquibase.sqlplus.conf file instead of running them every time at the command prompt.

Set the values as environment variables
Run the values as Java system properties (JAVA_OPTS) along with any command at the command prompt:

Windows

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

macOS/Linux

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

Run a Liquibase command:

Example: liquibase update --changelog-file=sqlplus_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), camelCase (properties file), and ENVAR_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-executor liquibase.sqlplus.executor LIQUIBASE_SQLPLUS_EXECUTOR`	String	Name of a custom executor you can specify.
`--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. 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.
`--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-path liquibase.sqlplus.path LIQUIBASE_SQLPLUS_PATH`	String	Path to `sqlplus` executable.
`--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).

runWith and sqlplus examples

Formatted SQL changeset using the `runWith` attribute

-- 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 changelog with the inline SQL changeset using the `runWith` attribute

<?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>

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

<?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>

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

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

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

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

SQL Plus best practices

Do not set the endDelimiter or splitStatements=true property on SQL Plus changesets. SQL Plus handles delimiters and statement splitting natively.
Prevent hanging queries by configuring the SQL Plus timeout. In your liquibase.sqlplus.config file, add liquibase.sqlplus.timeout=nn, where nn is time in seconds to wait before stopping the process.
Save the output of your SQL Plus spool files to your temp directory by adding liquibase.sqlplus.keep.temp=true to the liquibase.sqlplus.config file.

Use SQL Plus and runWith on Oracle