liquibase flow file and command

The liquibase flow command and the Flow File on which it operates is intended to create portable, platform-independent Liquibase workflows that can run wherever you need them without modification. This can include but is not limited to Jenkins, GitHub actions, a developers desktop, or any CI/CD support tool. Flow allows you to put multiple commands in a single 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. An example file is

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.

Run flow validate --flow-file update-status-diff.flow in the CLI.

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 individualLiquibaseor 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 properties file should be in the same directory as the flow file. Additionally, the user will need a changelog file.

Flow File example

Copy
stages:
  cleanuptheDB:
    actions:
      - type: liquibase
        command: dropAll
    afterActions:
      - type: liquibase
        command: status
        cmdArgs: {verbose: TRUE}