What support does Liquibase have for native executors with Microsoft SQL Server?

Last updated: July 14, 2025

SQLCMD 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

--sqlcmd-args liquibase.sqlcmd.args LIQUIBASE_SQLCMD_ARGS

String

Defines extra arguments to pass to the sqlcmd executable.

Note: The delimiter for arguments is a space " ". Do not use a comma "," or semicolon ";".

--sqlcmd-catalog-name liquibase.sqlcmd.catalogName LIQUIBASE_SQLCMD_CATALOG_NAME

String

Database to use when running SQLCMD.

--sqlcmd-keep-temp liquibase.sqlcmd.keep.temp LIQUIBASE_SQLCMD_KEEP_TEMP

Boolean

Indicates whether or not to keep a temporary SQL file after the execution of SQLCMD. If true, the file is not deleted. This setting is not required to keep the temporary file, only create-spool is. Default: false.

--sqlcmd-keep-temp-name liquibase.sqlcmd.keep.temp.name LIQUIBASE_SQLCMD_KEEP_TEMP_NAME

String

Indicates the name of a temporary SQL file after the execution of SQLCMD. If no file name is specified, a name is automatically generated.

--sqlcmd-keep-temp-overwrite liquibase.sqlcmd.keep.temp.overwrite LIQUIBASE_SQLCMD_KEEP_TEMP_OVERWRITE

Boolean

Overwrites any files in the specified directory with the same name. Default: true.

--sqlcmd-keep-temp-path liquibase.sqlcmd.keep.temp.path LIQUIBASE_SQLCMD_KEEP_TEMP_PATH

String

Specify the path in which to store the temporary files after the execution of SQLCMD. If not specified, the files will be stored in the system's temp directory.

--sqlcmd-log-file liquibase.sqlcmd.logFile LIQUIBASE_SQLCMD_LOG_FILE

String

Log file for SQLCMDoutput.

--sqlcmd-path liquibase.sqlcmd.path LIQUIBASE_SQLCMD_PATH

String

Path to sqlcmd executable. For example:

Linux:

/opt/mssql-tools/bin/sqlcmd

Windows:

C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\sqlcmd.exe

--sqlcmd-timeout liquibase.sqlcmd.timeout LIQUIBASE_SQLCMD_TIMEOUT

Integer

Indicates seconds to wait for the sqlcmd timeout. -1 disables the timeout. 0 returns an error. Default: 1800 (30 minutes).

Formatted SQL changeset using the runWith attribute

--liquibase formatted sql

--changeset myauthorname:2314 runWith:sqlcmd

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="sqlcmd">
    <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="sqlcmd">
    <sqlFile
path="my/path/file.sql"
... >
    </changeSet>

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

databaseChangeLog:
  - changeSet: null
id: 1-yaml
author: myauthorname
runWith: sqlcmd
changes:
  - sqlFile: null
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": "sqlcmd",
        "changes": [
          {
            "sqlFile": {
              "path": "person.sql",
              "relativeToChangelogFile": "true"
            }
          }
        ]
      }
    }
  ]
}

Best practices

  • Do not set the endDelimiter or splitStatements=true property on SQLCMD changesets. SQLCMD handles delimiters and statement splitting natively.

  • Prevent hanging queries by configuring the timeout. In your liquibase.sqlcmd.config file, add liquibase.sqlcmd.timeout=nn, where nn is the number of seconds to wait before stopping the process.

  • Save the output of your spool files to your temp directory by adding liquibase.sqlcmd.keep.temp=true to the liquibase.sqlcmd.conf file.

Example liquibase.sqlcmd.conf file

#### ## Note about relative and absolute paths: ## The liquibase.sqlcmd.path must be a valid path to the SQLCMD executable. ## The liquibase.sqlcmd.timeout value can be one of: ## -1 - disable the timeout ## Any integer value > 0 (measured in seconds) ## #### # The full path to the SQLCMD executable. # Sample Linux path # liquibase.sqlcmd.path=/opt/mssql-tools/bin/sqlcmd # Sample Windows path # liquibase.sqlcmd.path="C:\\Program Files\\Microsoft SQL Server\\Client SDK\\ODBC\\170\\Tools\\Binn\\SQLCMD.EXE" # A valid timeout value for the execution of the SQLCMD tool liquibase.sqlcmd.timeout=-1 # Flag to indicate whether or not to keep the temporary SQL file after execution of SQLCMD. # True = keep False = delete (default) liquibase.sqlcmd.keep.temp=true # OPTIONAL Flag to designate the location to store temporary SQL file after execution of SQLCMD. # Liquibase will attempt to use path exactly as entered, so please ensure it complies with your OS requirements. # liquibase.sqlcmd.keep.temp.path= # OPTIONAL Flag to designate the name of temporary SQL file after execution of SQLCMD. # Liquibase will attempt to use the name exactly as entered, so please ensure it complies with your OS requirements. # liquibase.sqlcmd.keep.temp.name= # OPTIONAL Args to pass directly to SQLCMD. # Learn about SQLCMD args at https://<link> # Note: The delimiter for args is a space eg:" " and not "," or ";" separated. # liquibase.sqlcmd.args= # OPTIONAL Path to a log file for the SQLCMD output # liquibase.sqlcmd.logFile=

What support does Liquibase have for native executors with Microsoft SQL Server? - Liquibase