flow

flow lets you run a series of commands contained in one or more stages, as configured in a Liquibase flow file. This command is available in Liquibase 4.15.0 and later.

Uses

Liquibase flow files let you create portable, platform-independent Liquibase workflows that can run anywhere without modification. This includes Jenkins, GitHub actions, a developers desktop, or any other CI/CD support tool.

You can use the flow command to run your flow file and execute many other commands all in one place. For more information, see Liquibase Flow Files.

Syntax

Before running the flow command, ensure that your flow file is in the directory you want it. Then navigate to that directory in your command line.

To run the flow command, specify the driver, classpath, and URL in Liquibase properties file. For more information, see Create and Configure a liquibase.properties File. You can also specify these properties in your command line.

Then run the flow command:

liquibase flow

Parameters

Global parameters

Attribute Definition Requirement

--license-key=<string>

Your Liquibase Pro license key

 Required

Command parameters

Attribute Definition Requirement

--flow-file=<string>

The path to the configuration YAML file which contains one or more "stages" of commands to be executed in a liquibase flow operation. Default: liquibase.flowfile.yaml.

 Optional

--flow-file-strict-parsing=<true|false>

If true, parse flow file YAML to allow only Liquibase flow file-specific properties, indentations, and structures. Default: true.

 Optional

--flow-shell-interpreter=<string>

The default interpreter used to execute shell commands. Examples include bash, sh, and cmd.

 Optional

--flow-shell-keep-temp-files=<true|false>

If true, do not delete temporary files created by the shell command execution. Default: false.

 Optional

Global parameters

Attribute Definition Requirement

globalArgs: { license-key: "<string>" }

Your Liquibase Pro license key

 Required

Command parameters

Attribute Definition Requirement

cmdArgs: { flow-file: "<string>" }

The path to the configuration YAML file which contains one or more "stages" of commands to be executed in a liquibase flow operation. Default: liquibase.flowfile.yaml.

 Optional

cmdArgs: { flow-file-strict-parsing: "<true|false>" }

If true, parse flow file YAML to allow only Liquibase flow file-specific properties, indentations, and structures. Default: true.

 Optional

cmdArgs: { flow-shell-interpreter: "<string>" }

The default interpreter used to execute shell commands. Examples include bash, sh, and cmd.

 Optional

cmdArgs: { flow-shell-keep-temp-files: "<true|false>" }

If true, do not delete temporary files created by the shell command execution. Default: false.

 Optional

Global parameters

Attribute Definition Requirement

liquibase.licenseKey: <string>

Your Liquibase Pro license key

 Required

Command parameters

Attribute Definition Requirement

liquibase.command.flowFile: <string>

liquibase.command.flow.flowFile: <string>

The path to the configuration YAML file which contains one or more "stages" of commands to be executed in a liquibase flow operation. Default: liquibase.flowfile.yaml.

 Optional

liquibase.command.flowFileStrictParsing: <true|false>

liquibase.command.flow.flowFileStrictParsing: <true|false>

If true, parse flow file YAML to allow only Liquibase flow file-specific properties, indentations, and structures. Default: true.

 Optional

liquibase.command.flowShellInterpreter: <string>

liquibase.command.flow.flowShellInterpreter: <string>

The default interpreter used to execute shell commands. Examples include bash, sh, and cmd.

 Optional

liquibase.command.flowShellKeepTempFiles: <true|false>

liquibase.command.flow.flowShellKeepTempFiles: <true|false>

If true, do not delete temporary files created by the shell command execution. Default: false.

 Optional

Global parameters

Attribute Definition Requirement

JAVA_OPTS=-Dliquibase.licenseKey=<string>

Your Liquibase Pro license key

 Required

Command parameters

Attribute Definition Requirement

JAVA_OPTS=-Dliquibase.command.flowFile=<string>

JAVA_OPTS=-Dliquibase.command.flow.flowFile=<string>

The path to the configuration YAML file which contains one or more "stages" of commands to be executed in a liquibase flow operation. Default: liquibase.flowfile.yaml.

 Optional

JAVA_OPTS=-Dliquibase.command.flowFileStrictParsing=<true|false>

JAVA_OPTS=-Dliquibase.command.flow.flowFileStrictParsing=<true|false>

If true, parse flow file YAML to allow only Liquibase flow file-specific properties, indentations, and structures. Default: true.

 Optional

JAVA_OPTS=-Dliquibase.command.flowShellInterpreter=<string>

JAVA_OPTS=-Dliquibase.command.flow.flowShellInterpreter=<string>

The default interpreter used to execute shell commands. Examples include bash, sh, and cmd.

 Optional

JAVA_OPTS=-Dliquibase.command.flowShellKeepTempFiles=<true|false>

JAVA_OPTS=-Dliquibase.command.flow.flowShellKeepTempFiles=<true|false>

If true, do not delete temporary files created by the shell command execution. Default: false.

 Optional

Global parameters

Attribute Definition Requirement

LIQUIBASE_LICENSE_KEY=<string>

Your Liquibase Pro license key

 Required

Command parameters

Attribute Definition Requirement

LIQUIBASE_COMMAND_FLOW_FILE=<string>

LIQUIBASE_COMMAND_FLOW_FLOW_FILE=<string>

The path to the configuration YAML file which contains one or more "stages" of commands to be executed in a liquibase flow operation. Default: liquibase.flowfile.yaml.

 Optional

LIQUIBASE_COMMAND_FLOW_FILE_STRICT_PARSING=<true|false>

LIQUIBASE_COMMAND_FLOW_FLOW_FILE_STRICT_PARSING=<true|false>

If true, parse flow file YAML to allow only Liquibase flow file-specific properties, indentations, and structures. Default: true.

 Optional

LIQUIBASE_COMMAND_FLOW_SHELL_INTERPRETER=<string>

LIQUIBASE_COMMAND_FLOW_FLOW_SHELL_INTERPRETER=<string>

The default interpreter used to execute shell commands. Examples include bash, sh, and cmd.

 Optional

LIQUIBASE_COMMAND_FLOW_SHELL_KEEP_TEMP_FILES=<true|false>

LIQUIBASE_COMMAND_FLOW_FLOW_SHELL_KEEP_TEMP_FILES=<true|false>

If true, do not delete temporary files created by the shell command execution. Default: false.

 Optional

Output

In this example, we are running the default flow file that comes pre-installed with Liquibase.

##########           LIQUIBASE FLOWFILE                ##########
##########  learn more http://docs.liquibase.com/flow  ##########

## Note: Any command which fails in any stage below result in the command stopping, and endStage being run.
## A flow file can have one or more stages, each with multiple "actions", 
## or your flow file can have multiple stages with fewer actions in each stage.
stages:


  ## The first stage of actions. 
  Default:
        
    actions:
      #
      # Policy Checks for changelog
      #
      - type: liquibase
        command: checks run
        cmdArgs: {checks-scope: changelog}
      #
      # Run the update
      #
      - type: liquibase
        command: update
          
      #
      # Policy Checks for database
      #
      - type: liquibase
        command: checks run
        cmdArgs: {checks-scope: database}


## The endStage ALWAYS RUNS. 
## So put actions here which you desire to perform whether previous stages' actions succeed or fail.
## If you do not want any actions to ALWAYS RUN, simply delete the endStage from your flow file.

endStage:
  actions:
    - type: liquibase
      command: history
Flow file liquibase.flowfile.yaml is valid.
******************************************************************************
*
* Executing Stage: Default
*
******************************************************************************

******************************************************************************
*
* Executing 'liquibase' checks run
*
******************************************************************************

Executing Policy Checks against example-changelog.xml

Executing all changelog checks because a valid license key was found!

WARNING: No database checks were run. Make sure the checks-scope property includes "database" to run database checks. In the CLI set --checks-scope="changelog,database" or set an environment variable LIQUIBASE_COMMAND_CHECKS_SCOPE=database. Learn more at https://docs.liquibase.com/policy-checks

INFO: Checks executed against SQL generated by H2 at jdbc:h2:tcp://localhost:9090/mem:dev.
Checks-settings File:      liquibase.checks-settings.conf
=====================================================================================
Changesets Validated: in example-changelog.xml
  ID: 1; Author: your.name
  ID: 2; Author: your.name
  ID: 3; Author: other.dev

Checks run against each changeset:
  Changesets Must Have a Comment Assigned (Short names: ChangesetCommentCheck)
  Changesets Must Have a Context Assigned (Short names: ChangesetContextCheck)
  Changesets Must Have a Label Assigned (Short names: ChangesetLabelCheck)
  Check Table Column Count (Short names: TableColumnLimit)
  One Change Per Changeset (Short names: OneChangePerChangeset)
  Require primary key when creating table (Short names: PrimaryKeyOnCreateTable)
  Rollback Required for Changeset (Short names: RollbackRequired)
  Warn on Detection of 'SELECT *' (Short names: SqlSelectStarWarn)
  Warn on Detection of 'USE DATABASE' statements (Short names: WarnOnUseDatabase)
  Warn on Use of User Defined ChangeTypes (Short names: DetectChangeType)
  Warn when 'DROP COLUMN' detected (Short names: ChangeDropColumnWarn)
  Warn when 'DROP TABLE' detected (Short names: ChangeDropTableWarn)
Warn when 'MODIFY <column>' detected (Short names: ModifyDataTypeWarn)

	Changelogs Checks Skipped Due to unsupported changeset type for this check:
	Warn on Detection of 'GRANT' Statements (Short names: SqlGrantWarn) skipped for:
	1:your.name,
	2:your.name,
	3:other.dev
	Warn on Detection of 'REVOKE' Statements (Short names: SqlRevokeWarn) skipped for:
	1:your.name,
	2:your.name,
	3:other.dev
	Warn on Detection of grant that contains 'WITH ADMIN OPTION' (Short names: SqlGrantAdminWarn) skipped for:
	1:your.name,
	2:your.name,
	3:other.dev
	Warn on Detection of grant that contains 'WITH GRANT OPTION' (Short names: SqlGrantOptionWarn) skipped for:
	1:your.name,
	2:your.name,
	3:other.dev
	Warn when 'TRUNCATE TABLE' detected (Short names: ChangeTruncateTableWarn) skipped for:
	1:your.name,
	2:your.name,
	3:other.dev

	INFO: Customize this output with the 'checks-output' property. See list of options with 'liquibase checks run --help' or https://docs.liquibase.com/policy-checks
	INFO: The return code of all SQL Parser failures can be customized by setting the --sql-parser-fail-severity/LIQUIBASE_COMMAND_CHECKS_RUN_SQL_PARSER_FAIL_SEVERITY property, including setting it to '0' to prevent job interruptions. Learn more at https://docs.liquibase.com/policy-checks
	Liquibase command 'checks run' was executed successfully.

	******************************************************************************
	*
	* Executing 'liquibase' update
	*
	******************************************************************************

	Running Changeset: example-changelog.xml::1::your.name
	Running Changeset: example-changelog.xml::2::your.name
	Running Changeset: example-changelog.xml::3::other.dev

	UPDATE SUMMARY
	Run:                          3
	Previously run:               0
	Filtered out:                 0
	Failed deployment:            0
	-------------------------------
	Total change sets:            3

	Liquibase: Update has been successful. Rows affected: 3
	Liquibase command 'update' was executed successfully.

	******************************************************************************
	*
	* Executing 'liquibase' checks run
	*
	******************************************************************************

	Executing Policy Checks against database jdbc:h2:tcp://localhost:9090/mem:dev

	Executing all database checks because a valid license key was found!

	INFO This command might not yet capture Liquibase Pro additional object types on h2
	Checks-settings File:      liquibase.checks-settings.conf
	=====================================================================================
	Database objects Validated:
	Catalog             : 1
	Column              : 11
	Index               : 2
	PrimaryKey          : 2
	Schema              : 1
	Table               : 2
	To increase details set the --verbose property

	Checks run against database jdbc:h2:tcp://localhost:9090/mem:dev:
	Check Table Column Count (Short names: TableColumnLimit)
	Table must have an index (Short names: CheckTablesForIndex)

	INFO: Customize this output with the 'checks-output' property. See list of options with 'liquibase checks run --help' or https://docs.liquibase.com/policy-checks
	INFO: The return code of all SQL Parser failures can be customized by setting the --sql-parser-fail-severity/LIQUIBASE_COMMAND_CHECKS_RUN_SQL_PARSER_FAIL_SEVERITY property, including setting it to '0' to prevent job interruptions. Learn more at https://docs.liquibase.com/policy-checks
	Liquibase command 'checks run' was executed successfully.

	******************************************************************************
	*
	* Executing Stage: endStage
	*
	******************************************************************************

	******************************************************************************
	*
	* Executing 'liquibase' history
	*
	******************************************************************************

	Liquibase History for jdbc:h2:tcp://localhost:9090/mem:dev

	+---------------+------------------+-----------------------+------------------+--------------+-----+
	| Deployment ID | Update Date      | Changelog Path        | Changeset Author | Changeset ID | Tag |
	+---------------+------------------+-----------------------+------------------+--------------+-----+
	| 9150144810    | 2/28/24, 2:55 PM | example-changelog.xml | your.name        | 1            |     |
	+---------------+------------------+-----------------------+------------------+--------------+-----+
	| 9150144810    | 2/28/24, 2:55 PM | example-changelog.xml | your.name        | 2            |     |
	+---------------+------------------+-----------------------+------------------+--------------+-----+
	| 9150144810    | 2/28/24, 2:55 PM | example-changelog.xml | other.dev        | 3            |     |
	+---------------+------------------+-----------------------+------------------+--------------+-----+

	Liquibase command 'history' was executed successfully.

	Liquibase command 'flow' was executed successfully.

Related videos

Learn more about Flow in Liquibase Pro

Learn how to use Flow files with S3

Related links