FormattedSqlHeaderRequired

All .sql Liquibase changelogs must begin with a --liquibase formatted SQL header. This header enables Liquibase's change tracking, auditing, and rollback features.

The FormattedSqlHeaderRequired policy check is triggered when a .sql changelog does not start with the required header. When triggered, the policy check lists all offending .sql changelog files missing the required header and notifies the user to add the missing header. This helps maintain the integrity and reliability of database change management.

Prerequisites

1. Ensure that you have correctly specified your Liquibase Pro license key.
2. Ensure that the --checks-scope parameter includes the scope of this check.
3. Create a Check Settings file: Use the Checks Settings Configuration File

For example:

--license-key=<string>

--checks-scope=<string>

globalArgs: { license-key: "<string>" }
cmdArgs: { checks-scope: "<string>" }

liquibase.licenseKey: <string>
liquibase.command.checksScope: <string>

liquibase.licenseKey: <string>
liquibase.command.checks.run.checksScope: <string>

JAVA_OPTS=-Dliquibase.licenseKey=<string> -Dliquibase.command.checksScope=<string>

JAVA_OPTS=-Dliquibase.licenseKey=<string> -Dliquibase.command.checks.run.checksScope=<string>

LIQUIBASE_LICENSE_KEY=<string>
LIQUIBASE_COMMAND_CHECKS_SCOPE=<string>

LIQUIBASE_LICENSE_KEY=<string>
LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCOPE=<string>

Enable

These steps describe how to create the Policy Check.

1. Initiate the customization process. In the CLI, run this command:
   liquibase checks customize --check-name=FormattedSqlHeaderRequired
   
   This message will display:
   WARNING: Additional checks have been added to 'liquibase.checks-settings.conf' and are disabled. To auto-enable new checks on upgrades, set '--auto-enable-new-checks=true'. Learn more at https://docs.liquibase.com/policy-checks
Set the Severity to return a code of 0-4 when triggered. (options: 'INFO'|0, 'MINOR'|1, 'MAJOR'|2, 'CRITICAL'|3, 'BLOCKER'|4)? [INFO]:

2. Set the Severity to return a code of 0-4 when triggered. These severity codes allow you to determine if the job moves forward or stops when this check triggers.
   
   Learn more here: Use Policy Checks in Automation: Severity and Exit Code
   options: 'INFO'=0, 'MINOR'=1, 'MAJOR'=2, 'CRITICAL'=3, 'BLOCKER'=4

3. Set the files you don't want this check to run against by setting the 'SQL_FILE_EXCEPTIONS_LIST' as a comma-separated list of 'path/to/sqlfiles'. This list will not trigger this check.
   
   In this example, we will specify:
   schema.sql, create_functions.sql, add_indexes.sql
   This message will display in the CLI:
   

   Copy

   Customization complete. Review the table below to confirm your changes.
                               +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
                               | Short Name                 | Scope     | Type   | Status  | Severity | Customization                  | Description                    |
                               +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
                               | FormattedSqlHeaderRequired | changelog | sql,   | enabled | 0        | SQL_FILE_EXCEPTIONS_LIST =     | This check triggers when a     |
                               |                            |           | xml,   |         |          | schema.sql,                    | changelog does not start with  |
                               |                            |           | yaml,  |         |          | create_functions.sql,          | the required '--liquibase      |
                               |                            |           | json   |         |          | add_indexes.sql                | formatted sql' header.         |
                               +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
                           Liquibase command 'checks customize' was executed successfully.

4. When finished, verify that your configuration is correct by running the show command:

   liquibase checks show --check-name=FormattedSqlHeaderRequired
   

   This message will display:

   Copy

   C:\Users\AmberWilliams\Projects\liquibase-4.32>liquibase checks show --check-name=FormattedSqlHeaderRequired
   ####################################################
   ##   _     _             _ _                      ##
   ##  | |   (_)           (_) |                     ##
   ##  | |    _  __ _ _   _ _| |__   __ _ ___  ___   ##
   ##  | |   | |/ _` | | | | | '_ \ / _` / __|/ _ \  ##
   ##  | |___| | (_| | |_| | | |_) | (_| \__ \  __/  ##
   ##  \_____/_|\__, |\__,_|_|_.__/ \__,_|___/\___|  ##
   ##              | |                               ##
   ##              |_|                               ##
   ##                                                ##
   ##  Get documentation at docs.liquibase.com       ##
   ##  Get certified courses at learn.liquibase.com  ##
   ##                                                ##
   ####################################################
   Starting Liquibase at 15:16:49 using Java 21.0.1 (version merge-test #12 built at 2025-04-28 21:24+0000)
   Liquibase Version:
   Liquibase Pro merge-test by Liquibase licensed to Liquibase until Mon Dec 11 17:00:00 MST 20
   
   Generating report on current configuration of checks using settings in: liquibase.checks-settings.conf
   
   WARNING: Additional checks have been added to 'liquibase.checks-settings.conf' and are disabled. To auto-enable new checks on upgrades, set '--auto-enable-new-checks=true'. Learn more at https://docs.liquibase.com/policy-checks
   +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
   | Short Name                 | Scope     | Type   | Status  | Severity | Customization                  | Description                    |
   +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
   | FormattedSqlHeaderRequired | changelog | sql,   | enabled | 0        | SQL_FILE_EXCEPTIONS_LIST =     | This check triggers when a     |
   |                            |           | xml,   |         |          | schema.sql,                    | changelog does not start with  |
   |                            |           | yaml,  |         |          | create_functions.sql,          | the required '--liquibase      |
   |                            |           | json   |         |          | add_indexes.sql                | formatted sql' header.         |
   +----------------------------+-----------+--------+---------+----------+--------------------------------+--------------------------------+
   INFO: Customize 'checks show' table with --show-cols flag. Learn more with 'liquibase checks show --help'
   
   Liquibase command 'checks show' was executed successfully.

5. Optional: You may want to customize this check if you need to specify different SQL files to exclude than you initially did in step three. If you need to make any other changes, run the customize command:

   liquibase checks customize --check-name=FormattedSqlHeaderRequired

Note: If you want to create another variant of this check with different settings, use the copy command to create a copy of the original check and then use the customize command to customize it.

Run

To run the check, use the run command:

liquibase checks run --check-name=formattedSqlHeaderRequired

stages:
  Default:
    actions:
      - type: liquibase
        command: checks run
        cmdArgs: {check-name: formattedSqlHeaderRequired}

liquibase flow

The Checks Run report will appear for you to review if this check triggered.

Related links

• endDelimiter SQL attribute