flow

The liquibase flow command is intended to create portable, platform-independent Liquibase workflows that can run wherever you need them without modification. This includes Jenkins, GitHub actions, a developers desktop, or any other CI/CD support tool.

Flow allows you to put multiple commands in a single file, called a Flow File, so they can all run sequentially by typing a single command into the CLI. The flow command provides the convenience of performing all of the steps in one place. This leads to better repeatability and standardization of the steps in a DevOps pipeline.

You can modify the Flow File to update the Liquibase steps specified in each Stage. You only have to update them in the Flow File to bring all jobs up to date. It is necessary to store Flow Files in remote locations or share across teams to enable this flexible behavior.

Create a Flow File

There are two ways to create a Flow File:

  1. The Default Flow File method, which runs on H2 by default
  2. The Existing Project method – advanced

The Flow File is not installed by default, so you must create one. If you create a Flow File without a properties file or a changelog configured, it will fail to run.

Validation

Once the Flow File is written, you can verify that it works by using the flow validate command. This ensures that the Liquibase commands have all of the parameters necessary to run successfully and the YAML formatting is correct. See the Syntax section for more information. In the CLI, run this command:

flow validate --flow-file update-status-diff.flow

If the file fails the validation check, Liquibase will state what command argument(s) were not resolved. You can then review and correct your Flow File and then run the flow validate command again to ensure it is working as expected.

Flow File organization

The Flow File contains one or more Stages and Actions. Below are definitions of these and a visual aid.

Stages are bundles of related actions in the Flow File. You can add a single action or multiple actions per Stage.

Actions are individual Liquibase or shell commands that execute within stages or endStage as part of the Flow File. Any Liquibase command arguments (abbreviated as cmdArgs in the Flow File) can be placed in any action section, with the exception of the list of global arguments below.

Incompatible commands and global arguments

You must use the following commands and global arguments in the CLI instead of the Flow File:

Commands

  • init start-h2 – This command locks the console

Global arguments

  • ARGUMENT_CONVERTER
  • CLASSPATH
  • DEFAULTS_FILE
  • INCLUDE_SYSTEM_CLASSPATH
  • LOG_CHANNELS
  • LOG_FILE
  • LOG_LEVEL
  • MONITOR_PERFORMANCE
  • PROMPT_FOR_NON_LOCAL_DATABASE
  • SEARCHPATH
  • SHOULD_RUN
  • SHOW_BANNER

Syntax

The Liquibase Flow File is written in YAML and must be formatted properly. As you can see in the below Flow File example, the cmdArgs section has all command arguments between curly braces and separated by commas.

All command arguments are formatted in the following way:

cmdArgs: {command-name: argument value, snapshot-format: JSON}

This example Flow File is the simplest scenario in which only cmdArgs are specified in the Actions. For this example to run, a liquibase.properties file with url, username, and password must be available. The liquibase.properties file should be in the same directory as the flow file. Additionally, the user will need a changelog file.

Flow File example

Copy
## 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:
      #
      # Quality Checks for changelog
      #
      - type: liquibase
        command: checks run
        cmdArgs: {checks-scope: changelog}
      #
      # Run the update
      #
      - type: liquibase
        command: update
          
      #
      # Quality 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

Related links