Concept
Version · 6.0
Create

Use native executors with PostgreSQL

Last updated: August 12, 2026

This page describes how to use Liquibase with the PSQL native executor on a PostgreSQL database.

Before you begin

Use Liquibase 4.13.0 or later.
Add PSQL to your PATH environment variable. Alternatively, pass its location in the liquibase.psql.conf file or from the command prompt during runtime. See liquibase.psql.path in the PSQL integration arguments section.
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 instructions.

Setup

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

1. Add the runWith attribute to the needed changesets in the changelog:

SQL: runWith:psql
XML: runWith="psql"
YAML: runWith: psql
JSON: "runWith": "psql"

2. Specify the PSQL integration arguments in one of the following ways:

Pass the values at runtime on the command line.
Add the values to liquibase.psql.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 example:

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

macOS & Linux example:

export JAVA_OPTS=-Dliquibase.psql.<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.psql.conf file, no error occurs. Liquibase only ignores it.

PSQL 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
--psql-args liquibase.psql.args LIQUIBASE_PSQL_ARGS	String	Defines extra arguments to pass to the `psql` executable. For more information, see PSQL documentation. Note: The delimiter for arguments is a space `" "`. Do not use a comma `","` or semicolon `";"`.
--psql-keep-temp liquibase.psql.keep.temp LIQUIBASE_PSQL_KEEP_TEMP	Boolean	Indicates whether or not to keep a temporary SQL file after the execution of PSQL. If `true`, the file is not deleted. This setting is not required to keep the temporary file, only `create-spool` is. Default: `false`.
--psql-keep-temp-name liquibase.psql.keep.temp.name LIQUIBASE_PSQL_KEEP_TEMP_NAME	String	Indicates the name of a temporary SQL file after the execution of PSQL. If no file name is specified, a name is automatically generated.
--psql-keep-temp-path liquibase.psql.keep.temp.path LIQUIBASE_PSQL_KEEP_TEMP_PATH	String	Specify the path in which to store the temporary files after the execution of PSQL. If not specified, the files will be stored in the system's `temp` directory.
--psql-log-file liquibase.psql.logFile LIQUIBASE_PSQL_LOG_FILE	String	Log file for PSQLoutput.
--psql-path liquibase.psql.path LIQUIBASE_PSQL_PATH	String	Path to `psql` executable. For example: Linux: `/usr/pgsql-15/bin/psql` Windows: `C:\Program Files\PostgreSQL\15\bin\psql.exe`
--psql-timeout liquibase.psql.timeout LIQUIBASE_PSQL_TIMEOUT	Integer	Indicates seconds to wait for the `psql` timeout. `-1` disables the timeout. `0` returns an error. Default: 1800 (30 minutes).

runWith and psql examples

--liquibase formatted sql

--changeset myauthorname:2314 runWith:psql

	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 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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">

<changeSet id="2" author="myauthorname" runWith="psql"> 
<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 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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">					

<changeSet id="2315" author="myauthorname" runWith="psql">  
	<sqlFile
	path="my/path/file.sql"
... > 
</changeSet>

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

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

--liquibase formatted sql

--changeset myauthorname:2314 runWith:psql

	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 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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">

<changeSet id="2" author="myauthorname" runWith="psql"> 
<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 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:secure="http://www.liquibase.org/xml/ns/secure"
    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/secure
        http://www.liquibase.org/xml/ns/secure/liquibase-secure-latest.xsd">					

<changeSet id="2315" author="myauthorname" runWith="psql">  
	<sqlFile
	path="my/path/file.sql"
... > 
</changeSet>

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

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

Best practices

Do not set the endDelimiter or splitStatements=true property on PSQL changesets. PSQL
handles delimiters and statement splitting natively. Prevent hanging queries by configuring the timeout. In your
liquibase.psql.config file, add liquibase.psql.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.
psql.keep.temp=true to the liquibase.psql.conf file.

Example liquibase.psql.conf file

# The full path to the psql executable.
# Sample Linux path
# liquibase.psql.path=/usr/local/bin/psql
# Sample Windows path
# liquibase.psql.path="C:\\Program Files\\PostgreSQL\\<version>\\bin\\psql.exe"

# Timeout value for the execution of the psql tool
# Measured in seconds. -1 to disable.
liquibase.psql.timeout=-1

# Flag to indicate whether or not to keep the temporary SQL file after execution of psql.
# True = keep False = delete (default)
liquibase.psql.keep.temp=false

# OPTIONAL Flag to designate the location to store temporary SQL file after execution of psql.
# Liquibase will attempt to use path exactly as entered, so please ensure it complies with your OS requirements.
# liquibase.psql.keep.temp.path=

# OPTIONAL Flag to designate the name of temporary SQL file after execution of psql.
# Liquibase will attempt to use the name exactly as entered, so please ensure it complies with your OS requirements.
# liquibase.psql.keep.temp.name=

# OPTIONAL Args to pass directly to psql.
# Note: The delimiter for args is a space eg:" " and not "," or ";" separated.
# liquibase.psql.args=

# OPTIONAL Path to a log file for the psql output
# liquibase.psql.logFile=

PreviousConnect to Cloud SQL for PostgreSQL using GCP IAM authentication NextWhat support does Liquibase have for Snowflake?

Use native executors with PostgreSQL

Before you begin

Setup

PSQL integration arguments

runWith and psql examples

Formatted SQL changeset using the runWith attribute

XML changelog with the inline SQL changeset using the runWith attribute

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

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

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

Best practices

Example liquibase.psql.conf file