liquibase.command.CommandScope class is the primary high-level facade for running Liquibase operations.
The API provides both a way to call individual commands and metadata about each command including human-readable descriptions and argument information.
The operations available through the command API are end-user facing, complete calls such as "update", "rollback", or "generateChangelog".
The available commands are a pluggable extension point, and the command API provides a consistent and stable way to work with the commands regardless of what extensions are installed.
sequenceDiagram Integration->>CommandScope: Create and configure Integration->>CommandScope: execute() CommandScope->>Liquibase Logic: Runs Business Logic CommandScope-->>Integration: returns data from command
Commands are executed through the liquibase.command.CommandScope class.
CommandScope object defines a self-contained call to a specific command, where any configuration applied to it applies only to that command call.
Each call to a command will require a separate
Creating the Command
When constructing the
CommandScope object, the name of the command is passed in. For example,
If the command has a "nested" name, include the entire command "path" such as
new CommandScope("init", "project").
Arguments are added via the
The basic version uses a string argument name, such as
This allows you to easily set any arbitrary argument, but you do have to be careful about spelling as there is no type safety.
Alternatively, you can use the version that takes a
CommandArgumentDefinition you reference from the code that defines the command itself.
This ensures your argument name exists and provides compile-time type safety on the value passed, but requires you to find the CommandDefinition field to use.
By default, any command output will go to
The "command output" is reserved for the command's actual output and is separate from the errors, logged messages, and status updates which are handled via the
If you would like the command output to go to a different stream, call
After setting the command arguments, you can execute the command with
CommandResults result = commandScope.execute().
This will run the command's logic and return a
CommandResults object which can contain objects created during the command execution.
Commands can attach any objects they would like to the response, which can be accessed via the
For example, the
snapshot command may attach the
liquibase.snapshot.DatabaseSnapshot object it built up as a result.
Like the argument settings, results can be accessed either by the string name of the result like
or by a pre-defined
CommandResultDefinition object like
result.getResult(SnapshotCommandStep.SNAPSHOT_RESULT) to provide type safety.
Reading Command Metadata
The command metadata is available through the liquibase.command.CommandFactory singleton.
Like all singletons, you access the instance via
For integrations that are looking to expose all Liquibase functionality to end-users, such as the CLI or Maven integrations, the
CommandFactory allows you to programmatically and dynamically
expose everything Liquibase (including installed extensions) supports to your users.
CommandFactory, you can call
getCommands() to list all the available commands. For each command, it returns the liquibase.command.CommandDefinition for it.
- Argument information such as name, aliases, description, and default value
Both commands and arguments can be listed as "hidden" which are commands or arguments that can be used but are usually not user-facing.
If you know the specific command you want the
CommandDefinition for, you can look it up directly via
The complete javadocs for
liquibase.command.CommandScope is available at https://javadocs.liquibase.com
The following guides provide relevant examples:
Created: February 18, 2023