Native Executors

A native executor is designed to run scripts in a way that directly matches your target software environment.

Liquibase primarily uses JDBC drivers to connect and deploy changesets to a database. However, there are instances when the JDBC driver is insufficient to process highly specialized SQL. Instead, you may need to deploy this complex SQL over a native executor, which is a platform-specific command-line tool.

Using native executors with Liquibase Pro can provide distinct advantages, such as the ability to process database client-specific settings and environment variables within the SQL script.

During execution time, Liquibase invokes a native executor for changesets that request it to deploy a payload to a target database.

Flow chart of the Liquibase deployment process using a native executor.

Compatible Native Executors

Four native executors can be used with Liquibase Pro:

Database native executors are not shipped with Liquibase. Users need to install the compatible native executor specific to their database type.

Configure Changesets to Use Native Executors

Liquibase decides whether to use the native executor based on the presence of the runWith attribute.

  1. In your changelog, apply runWith to each changeset you want to deploy using a native executor:
    • In Formatted SQL changelogs, you can apply runWith to any changeset.
    • In XML, YAML, and JSON changelogs, you can only apply runWith to changesets using the sql and sqlFile Change Types.

    For example, using sqlplus:

    --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>
  2. In your command line, run a command to deploy your change, such as update:
    3. liquibase update

    When successful, Liquibase displays "Liquibase command 'update' was executed successfully."

Liquibase applies the native executor you specify in runWith during update and rollback operations. If you don't specify runWith, Liquibase uses the JDBC driver to deploy the changeset.

Related Links

For more information on the sql and sqlFile Change Type, visit the following documentation pages:

Liquibase Resources

Liquibase Help

Visit the Liquibase Forum to ask questions, find answers from other Liquibase users, and learn about new Liquibase version releases.

Tutorials