Use Native Executors with PostgreSQL

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

Prerequisites

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:
  3. Run a Liquibase command:
  4. 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. 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 PSQL output.

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

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.

Related links