Validate changelogs before deployment

The validate command checks your changelog for potential errors in Liquibase syntax that may cause the update command to fail.

Note: The validate command examines Liquibase syntax and behaviors related to Liquibase operations. It does not check SQL for correctness and does not anticipate database deployment errors resulting from malformed SQL.

Uses

Use the validate command to detect issues in your changelog before running the update command. Validation helps you avoid partial updates, where only some changesets are applied due to errors in your changelog file.

Standard Validation

The validate command ensures:

  • The XML, YAML, JSON, or formatted SQL is structured correctly

  • Referenced files can be found

  • Attributes you specify in your changelog match the XSD schema

  • There are no duplicated id, author, and file combinations

  • There are no checksum errors

  • The DATABASECHANGELOG and DATABASECHANGELOGLOCK tables exist (if not, Liquibase creates them)

Strict Validation - Liquibase Secure 5.1+

Use validate --strict to enforce additional best practices and catch configuration issues that standard validation allows:

  • Empty attribute values: Detects when changeset attributes like labels or context are defined but have no value

  • Invalid enumerated values: Catches typos or invalid values for attributes like dbms and runWith

  • Missing included files: Validates that all files referenced via include and includeAll exist

  • Full changelog tree validation: Validates all nested and included changelogs from the root changelog

Run validate --strict before deployment to ensure your changelogs follow strict configuration standards.

Warning: The validate command only looks for possible errors in the changelog structure and syntax. It does not check for errors that might result from applying the changes to a specific database, such as SQL syntax errors or database-specific compatibility issues.

Procedure

1

Specify the driver, classpath, and database URL in the liquibase.properties file.

2

Run the validate command:

liquibase validate --changelog-file=
<example-changelog>.xml

Be sure to replace <example-changelog> with the name of your changelog.

Liquibase will check nested changelogs for definitions of the changesets to validate. Note: You may not need the `username` and `password` attributes depending on your authentication setup. If your database uses IAM roles, integrated authentication, certificates, or other credential management systems, you can omit these attributes. Alternatively, some JDBC URLs allow you to embed credentials directly in the connection string; however, for better security and credential management, consider using separate parameters or environment variables instead.

3

(Optional) enable liquibase validate --strict mode

Liquibase Secure strict validation mode

Available in Liquibase Secure 5.1+

Use the --strict flag to enforce stricter validation rules before running updates. Strict mode catches additional configuration issues that standard validation allows.

Syntax:

liquibase validate --strict

When to use strict mode: Run validate --strict before liquibase update to ensure your changelogs follow best practices and avoid runtime errors.

Validation Check

Standard validate

validate --strict

Missing attribute values (empty labels, contexts)

❌ Not detected

✅ Detected

Invalid enumerated values (dbms, runwith, etc.)

❌ Not detected

✅ Detected

Missing included files

❌ Not detected

✅ Detected

Nested/included changelog validation

⚠️ Partial validation

✅ Full validation

Validation details

Strict mode detects when changeset attributes are defined but have no value:
#This will fail strict validation:
- changeSet:
    id: example
    author: user1
    labels:           # Empty value
    context: " "      # Space-only value
Strict mode catches typos or invalid values for attributes with predefined options:
#This will fail strict validation:
- changeSet:
    id: example
    author: user1
    dbms: somerandomname        # Invalid database type
    runWith: somerandotoolname  # Invalid executor
Strict mode validates that all referenced files exist.
#When files are missing, validation shows the exact path that was checked to help you troubleshoot.
#This will fail if the file doesn't exist:
- include:
    file: path/to/missing-changelog.xml

Error message guidance

When strict validation detects issues, Liquibase will:

  1. Stop the operation

  2. List all attributes with missing or invalid values

  3. Show file paths for missing includes

Liquibase reports what is wrong (missing value, invalid option, missing file) but doesn't attempt to diagnose why (typos, formatting errors, etc.). This keeps error messages focused and actionable.

Standard validate Results:

If you run liquibase validate --changelog-file=<example-changelog>.xml (without --strict): Successful validation would show:

  • Confirmation that the changelog file was found and parsed

  • Verification that changesets are properly formatted

  • Confirmation that the database connection is valid (if credentials are provided)

  • A success message indicating the changelog is valid

Potential issues that standard validate WOULD catch:

  • Malformed XML/YAML/JSON syntax

  • Duplicate changeset IDs

  • Invalid changelog structure

  • Database connection failures (if credentials are used)

Potential issues that standard validate WOULD NOT catch:

  • Empty attribute values such as labels: or context: " "

  • Typos in enumerated values such as dbms: somerandomname

  • Missing included changelog files

  • Incomplete nested changelog validation

validate --strict Results:

If you run liquibase validate --strict (Liquibase Secure 5.1+):In addition to everything standard validate checks, you'd get:✅ Detection of missing/empty attribute values

  • Flags changelogs with attributes defined but no value

  • Identifies space-only or empty string values

✅ Invalid enumerated value detection

  • Catches typos in dbms (database types)

  • Catches typos in runWith (executor names)

  • Validates other predefined option attributes

✅ Missing file detection

  • Verifies all include: referenced files exist

  • Shows the exact path checked when files are missing

✅ Full nested changelog validation

  • Recursively validates all included/nested changelogs with the same strict rules

Error output format: When strict mode finds issues, Liquibase will:

  1. Stop immediately before any database changes are applied

  2. List specific problems such as "attribute 'labels' has empty value"

  3. Show file paths for missing includes

  4. Focus on what's wrong, not why (you'll need to investigate typos/formatting yourself)