Utility Commands

The purpose of the utility commands is to allow users to perform a variety of administrative tasks for Liquibase changelogs, changesets, checksums, table locks, and database schema documents.

Utility Category

These commands are available in all Liquibase editions and are listed by functional subcategories.

Schema Javadoc Utility Command

• db-doc: use this to generate database documentation that lists all actions performed against the existing database.

Changelog Utility Commands

• tag: use this to mark the current database state, version, or release for future rollback.
• tag-exists: use this to check if a tag already exists in the database.
• validate: use this to check and identify errors in a changelog that may cause the update command to fail.

Checksum Utility Commands

• calculate-checksum: use this to calculate and print a checksum for a changeset to see if a changeset has been changed.
• clear-checksums: use this to clear all checksums typically when there is a MD5Sum error message and the checksums need to be cleared from the DATABASECHANGELOG table.

Liquibase Lock Utility Commands

• list-locks: use this to return the hostname, IP address, and the timestamp when the Liquibase lock record was added to the DATABASECHANGELOG table.
• release-locks: use this to remove a lock record from the DATABASECHANGELOG table due to an interruption with the change deployment.

Changelog Sync Utility Commands

• changelog-sync: use this to mark all undeployed changes in the changelog as executed.
• changelog-sync-sql: run this before the changelog-sync command to inspect the raw SQL for potential issues.
• changelog-sync-to-tag: use this to mark all undeployed changes in the changelog up to a specified tag.
• changelog-sync-to-tag-sql: run this before the changelog-sync-to tag command to inspect the raw SQL for potential issues.
• mark-next-changeset-ran: use this to mark the next change as executed in the database.
• mark-next-changeset-ran-sql: run this before the mark-next-changeset-ran command to inspect the raw SQL for potential issues.

Since changelog sync utility commands change the schema of a database, Liquibase provides SQL output commands that you can run beforehand. The SQL output commands let you inspect the SQL that Liquibase will generate when you run the changelog sync utility commands.

Direct Database Commands

• drop-all: use this to drop all objects in your database
• execute-sql: use this to run a SQL query or file on your database

Additional Commands for Liquibase Pro

These commands require an active Liquibase Pro license:

• set-contexts: use this to set or replace contexts on a changeset using the CLI.
• set-labels: use this to set or replace labels on a changeset using the CLI.

Each individual utility command page specifies the criteria for using the command successfully, including a list of required and optional command-specific arguments.

Utility Command Requirements

With the exception of the set-contexts and set-labels Liquibase Pro commands, the utility commands require the following command argument:

• The JDBC database connection URL is specified as --url.

The db-doc, validate, calculate-checksum, set-contexts, set-labels, and the changelog sync utility commands also require the following command argument:

• The root changelog file is specified as --changelog-file.

Your database may also require the --username and --password arguments in Liquibase. However, the username and password are not required for connections and systems which use alternate means of authentication.

Troubleshooting

If Liquibase returns an error when you run a utility command, use the Liquibase --help parameter to check the correct syntax of the command and the command-specific parameters you can use with it.

For example, in the CLI:

liquibase <command> --help

Related Content

Visit the Using JDBC URL in Liquibase documentation page to learn more about Liquibase database connection requirements.

Liquibase Resources

Liquibase Help

Visit the Liquibase Forum channel to ask questions, find answers from other Liquibase users, and learn about new Liquibase version releases.

Tutorials

Visit the How to set up Liquibase with an Existing Project and Multiple Environments documentation page to see how the changelog-sync command is used to mark changesets as already run in an existing database.

Liquibase University

Liquibase Commands for Troubleshooting: this course includes, but not limited to, lessons on using the tag, db-doc, clear-checksums, and mark-next-changeset-ran commands.

Blogs and Articles

Preparing for Database Automation with Liquibase: read this CI/CD & DevOps blog on how using the validate and tag commands can help teams adopt good CI/CD patterns in their use of Liquibase.