variables and include feature

Liquibase flow files incorporate variables and include other Flow files or YAML files. These can be placed in the Flow file Header above stages.

Note: The flow feature requires Liquibase 4.17+.

In Liquibase 4.24.0+, variables you define in a flow file are shared across "nested" flow files and can be passed through multiple flow files.

Structure

globalVariables

globalVariables must be defined at the top of the Flow File with the syntax shown in the example Flow File. Each Action specified in the Flow File can reference a globalVariable as a command argument. This saves you time and keeps your Flow File tidy.

Define a global variable:

offlineRefUrl: "offline:postgres?snapshot=refSnapshot.json"

Use a global variable you have defined:

cmdArgs: { url: "${offlineRefUrl}"}

Reference System Environment Variables through globalVariables

globalVariables can reference System Environment Variables to provide values within a Flow file. Within the Flow file example below, notice that the command echoes "Running Liquibase from ${LIQUIBASE_HOME}". This allows you to change environment variables as desired without changing the Flow file.

Note:  Place the environment variable you want to reference between the parenthesis: "Running Liquibase from ${INSERT_ENVIRONMENT_VARIABLE_HERE}"

Copy 
stages:
    systemEnvironmentVariableSample:
        actions:
        - type: shell
            command: echo "Running Liquibase from ${LIQUIBASE_HOME}"

stageVariables

stageVariables work exactly like globalVariables except they are declared inside of each stage group. If you have the same variable declared as a globalVariable, the stageVariables are applied, not the globalVariable. For example, if you have a changelog globalVariable but need to specify a different changelog, you can apply that via a stageVariable. stageVariables always override globalVariables.

All variables, especially labels and context, must be specified in the Flow File with quotations to operate properly. If you want to run all changesets with or without labels, you must leave the label names quotes empty so you do not have to list all labels individually.

Copy
Label Example 1
Default:
    stageVariables:
      LABELNAMES: ""
Copy
Label Example 2
#
# Run the update
#
- type: liquibase
  command: update
  cmdArgs: {labels: "${LABELNAMES}"}

Include configured YAML files within a Flow File

Flow Files can include references to other YAML files with configuration by using the include section of the file. You need only create a variable name for the referenced YAML file and then reference the file title so that the Flow File can locate it.

The include variable should be in the following format:

username: actual-Username

The key is username and the value is actual-Username. To use the values defined in the included file in the Flow File, you need to reference the namespace and the key. For example:

cmdArgs: {username: "${username}"}

When the flow command executes, it will read the included file, locate the username key and substitute the value for that key into the Liquibase action. In the case of the key:value example here, the substitution results in ${postgresNamespace.user} becoming actual-Username. The Liquibase action executes using actual-Username as the user property.

Example of Flow File include functionality:

include:
- postgresNamespace: postgres-vars.yaml

To enable the functionality, you will then add the created variable name to the cmdArgs section or your changelog.

cmdArgs: { url: "${postgresNamespace.url}", username: "${postgresNamespace.user}", password: "${postgresNamespace.password}", changelog-file: "${postgresNamespace.changelogFile}"}

Includes cmdArgs, globalArgs, and a referenced include file (YAML)

Copy
flow-with-include-global 
##########           LIQUIBASE FLOW FILE               ##########
##########  learn more http://docs.liquibase.com/flow  ##########

## NOTE: This is an advanced example flowfile, compared to the other sample at examples/liquibase.flowfile.yaml
## Advanced options show in this file include:
## non-default name of 'liquibase.advanced.flow' (use by setting flowfile property to this name)
#### example for CLI: liquibase flow --flow-file=liquibase.advanced.flow
#### example for ENV Var: LIQUIBASE_FLOW_FLOW_FILE=liquibase.advanced.flow
## use of 'include' to inject namespaced yaml files of key:val variables
## use of globalVariables and stageVariables
## use of globalArgs and cmdArgs
## use of property substitution
## use of a nested flowfile (in this case in the endStage, but could be elsewhere)

## Bring in and namespace an external file with yaml 'key: val' pairs for use in this file
## The variables will be used as ${namespace.variablename}, seen in this example as $(DATES.THISDATE)
include:
  DATES: liquibase.flowvariables.yaml

## Set up some global variables for property substitution in ANY stage
globalVariables:
  PROJNAME: "MyFlowProject"

## Start the stages. There can be more than one, if desired.
stages:  
  
  ## The first stage. There can be more than one if desired.
  stage1:

    ## set up vars for property substitution in THIS stage only
    stageVariables:
      VERBOSESTATE: TRUE

    actions:
    
    # Do a validate command 
    - type: liquibase
      command: validate

    # tell me what is pending a deployment
    - type: liquibase
      command: status
      cmdArgs: {verbose: "${VERBOSESTATE}"}

    # And then save a version in detail
    - type: liquibase
      command: updatesql
      globalArgs: {outputfile: "${PROJNAME}-${DATES.THISDATE}-updatesql.log"}

    # Quality Checks for changelog 
    - type: liquibase
      command: checks run
      cmdArgs: {checks-scope: changelog}

    # Run update
    - type: liquibase
      command: update
      
    # Quality Checks for database
    - type: liquibase
      command: checks run
      cmdArgs: {checks-scope: database}

## Put your clean up and other actions for after success in all stage(s) above in the endStage
endStage:
  actions:
    - type: liquibase
      command: flow
      cmdArgs: {flowfile: liquibase.endstage.flow}

Related links