Liquibase Flow Files

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. Flow Files are available in Liquibase 4.15.0 and later.

You can use a Flow File to group together multiple commands 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.

You can also use the flow file to run Policy Checks on your changelog or database. In Liquibase 4.24.0+, flow files running policy checks exit with a return code matching the highest return code triggered by any check.

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

Default Flow File method

This method is for creating an entirely new project.

  1. Run the liquibase flow command.
  2. Select option 3: Generate a flow file and exit.
  3. Open the newly created file and review the sections and comments.

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.

Outside the CLI, you can use the LIQUIBASE_COMMAND_FLOW_FILE environment variable or the liquibase.command.flowFile property.

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 Commands 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 global arguments shown in: Incompatible commands and global arguments.

Syntax

The Liquibase Flow File is written in YAML. To run Liquibase commands in actions, set the type argument for that action to liquibase. To run shell commands in actions, set the type argument for that action to shell.

Command arguments use the following format:

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

This example Flow File is the simplest scenario in which only cmdArgs are specified in the actions:

## 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

Note: For this example to run, a changelog file and 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.

Incompatible commands and global arguments

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

Incompatible commands

  • init start-h2 – This command locks the console

Incompatible 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

Related videos

Learn more about Flow in Liquibase Pro

Learn how to use Flow files with S3

Related links