runWith

Liquibase normally processes database changes in changelogs over a JDBC connection. However, the JDBC connection (or executor) sometimes cannot process highly specialized SQL. In these cases, you might want to use a different executor.

The changeset attribute runWith="<executor>" lets you specify a non-default executor to run your SQL.

Uses

The runWith="<executor>" capability works with the following changelogs:

  • Formatted SQL changelogs.
  • XML, JSON, and YAML changelogs that include inline sql or sqlFile tagged changesets.
  • Liquibase Pro: XML, JSON, and YAML changelogs that use the modifyChangeSets Change Type with include or includeAll to import nested changelogs. This sets an overarching executor for multiple changelogs, with the option of overriding that default for specific changesets.

For Liquibase Pro users, the PSQL, SQL Plus, and SQLCMD integrations are built-in.

Tip: Using SQLCMD allows you to generate one log file per changeset executed via runWith, any Update Commands, and any Rollback Commands . This allows for close inspection of each changeset once it has been run. These logs are stored in your liquibase.sqlcmd.config file and are labeled with the changeset author and ID.
Example: sqlcmd-<developername>-<id-1>.log

Native executors

A native executor is designed to run scripts in a way that is directly compatible with your target software environment. For example, if you use PostgreSQL's psql native executor to access your database, you may have written SQL scripts uniquely suited to psql. Liquibase uses the jdbc native executor by default, so some scripts written for another executor may have unexpected behavior.

However, Liquibase Pro lets you use runWith to call on the PSQL (PostgreSQL), SQL Plus (Oracle), and SQLCMD (MSSQL Server) native executor script runners when deploying changesets. This lets you continue using scripts that you wrote before installing Liquibase. If you use MongoDB, the mongosh native executor is required. You can also write a custom executor yourself.

Custom executor

To create and use a custom executor other than the built-in integrations, you must:

  1. Create a class that extends the AbstractExecutor class
  2. Register your new class in META-INF/services
  3. Specify your executor's name using the runWith attribute

For more information, see the Liquibase Contributor Docs: Add a Native Executor.

Attributes

Note: All changelog attributes use the camelCase format.

Attribute Value Notes
runWith jdbc Default value if none specified. See Class JdbcExecutor.
mongosh Executor for MongoDB. See Use Native Executors with MongoDB Pro.
psql Executor for PostgreSQL. See Use Native Executors with PostgreSQL.
sqlplus Executor for Oracle. See Use Native Executors with Oracle Database.
sqlcmd Executor for MSSQL Server. See Use native executors with Microsoft SQL Server.
<custom> Custom executor. See Add a Native Executor.

Note: The liquibase.mongosh.conf, liquibase.psql.conf, liquibase.sqlplus.conf, and liquibase.sqlcmd.conf files are the configuration files to pass arguments to your executor when running Liquibase Pro. In this file, you can specify key-value pairs for configuring the executor.

Syntax

In these examples, we use the sqlplus native executor. If you want to run a different executor, replace sqlplus with the name of your executor:

--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;
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"
            }
          }
        ]
      }
    ]
  }
}
<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>

Troubleshooting

If you specify a native executor other than JDBC using runWith, you cannot also set runInTransaction to true. If you do, Liquibase throws an UnexpectedLiquibaseException error:

Unexpected error running Liquibase: Migration failed for changeset runwith-tr.sql::1::runSQLTableWithPsql::Liquibase Pro User:
     Reason: liquibase.exception. DatabaseException: liquibase.exception.LiquibaseException: liquibase.exception. UnexpectedLiquibaseException: psql returned a code of 3

Related links