Use Native Executors with Microsoft SQL Server

This page describes how to use Liquibase with the SQLCMD native executor on a Microsoft SQL Server database.

Prerequisites

• Use Liquibase 4.8.0 or later.
• Add SQLCMD to your PATH environment variable. Alternatively, pass its location in the liquibase.sqlcmd.conf file or from the command prompt during runtime. See liquibase.sqlcmd.path in the SQLCMD integration arguments section.

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

Setup

Tip: To use Liquibase and SQLCMD with Windows Integrated Security, follow the steps from Using Liquibase and MSSQL Server with Windows Integrated Security and proceed with the following instruction.

1. Add the runWith attribute to the needed changesets in the changelog:
• SQL: runWith:sqlcmd
• XML: runWith="sqlcmd"
• YAML: runWith: sqlcmd
• JSON: "runWith": "sqlcmd"

Tip: For more information, see the runWith and sqlcmd examples section.

2. Specify the SQLCMD integration arguments in one of the following ways:
• Pass the values at runtime on the command line
• Add the values to liquibase.sqlcmd.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:
Windows

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

macOS/Linux

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

3. Run a Liquibase command:

Example: 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.sqlcmd.conf file, no error occurs. Liquibase only ignores it.

Use the SQLCMD integration with multiple databases

To use Liquibase and sqlcmd utility on an instance with multiple databases:

1. Create the liquibase.sqlcmd.conf file for each database you use and ensure it is in the directory from which Liquibase runs the files
2. In each liquibase.sqlcmd.conf file, add a line like the following one:

   liquibase.sqlcmd.args=-v MYDATABASE=db_dev

3. Add USE $(MYDATABASE) to each changeset that uses the runWith attribute

Example:

USE $(MYDATABASE)
CREATE TABLE [dbo].[course] (
[CourseId] INT IDENTITY (1, 1) NOT NULL,
[Name] VARCHAR (30) NOT NULL,
[Detail] VARCHAR (200) NULL,
CONSTRAINT [PK_Course] PRIMARY KEY CLUSTERED ([CourseId] ASC) 8);

The update command will replace the correct value at runtime.

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).

--sqlcmd-args
liquibase.sqlcmd.args
LIQUIBASE_SQLCMD_ARGS

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

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

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

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

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

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

--sqlcmd-path
liquibase.sqlcmd.path
LIQUIBASE_SQLCMD_PATH

--sqlcmd-timeout
liquibase.sqlcmd.timeout
LIQUIBASE_SQLCMD_TIMEOUT

runWith and sqlcmd examples

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:
       id: 1-yaml
       author: myauthorname
       runWith: sqlcmd
       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": "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 time in 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=

Related links

• runWith
• runWithSpoolFile
• modifyChangeSets
• Using Liquibase with Microsoft SQL Server