CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-liquibase--liquibase-core

Liquibase is a tool for managing and executing database changes.

—

Pending
Overview
Eval results
Files

command-framework.mddocs/

Command Framework

This document covers Liquibase's modern command framework through the CommandScope class, which provides a flexible and extensible way to execute Liquibase operations.

Imports

import liquibase.command.CommandScope;
import liquibase.command.CommandResults;
import liquibase.exception.CommandExecutionException;

import java.io.OutputStream;
import java.io.Writer;

CommandScope Class

The CommandScope class is the primary facade for executing commands using Liquibase's modern command framework.

Constructor

/**
 * Create a new command scope for execution
 * @param commandName Command name(s) to execute
 * @throws CommandExecutionException if command cannot be found
 */
public CommandScope(String... commandName) throws CommandExecutionException

Argument Configuration

/**
 * Add argument value for command execution
 * @param argumentName Name of the argument
 * @param value Argument value
 * @return CommandScope for method chaining
 */
public CommandScope addArgumentValue(String argumentName, Object value)

Output Configuration

/**
 * Set output stream for command results
 * @param outputStream Target output stream
 * @return CommandScope for method chaining
 */
public CommandScope setOutput(OutputStream outputStream)

Command Execution

/**
 * Execute the configured command
 * @return CommandResults containing execution results
 * @throws CommandExecutionException if command execution fails
 */
public CommandResults execute() throws CommandExecutionException

Core Commands

Update Commands

Execute database update operations:

// Standard update
CommandScope updateCommand = new CommandScope("update")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("contexts", "dev,test")
    .addArgumentValue("labelFilter", "feature-1");

CommandResults results = updateCommand.execute();

// Update with count limit
CommandScope updateCountCommand = new CommandScope("updateCount")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa") 
    .addArgumentValue("password", "")
    .addArgumentValue("count", 5);

// Update to specific tag
CommandScope updateToTagCommand = new CommandScope("updateToTag")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "") 
    .addArgumentValue("tag", "version-1.0");

Update SQL Commands

Generate SQL for update operations without executing them:

// Generate update SQL
CommandScope updateSqlCommand = new CommandScope("updateSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Generate update count SQL  
CommandScope updateCountSqlCommand = new CommandScope("updateCountSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("count", 3);

// Generate update to tag SQL
CommandScope updateToTagSqlCommand = new CommandScope("updateToTagSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "version-1.0");

Rollback Commands

Execute rollback operations:

// Rollback to tag
CommandScope rollbackCommand = new CommandScope("rollback")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "version-1.0");

// Rollback count
CommandScope rollbackCountCommand = new CommandScope("rollbackCount")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("count", 2);

// Rollback to date
CommandScope rollbackToDateCommand = new CommandScope("rollbackToDate")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("date", "2023-01-01T00:00:00");

Rollback SQL Commands

Generate SQL for rollback operations:

// Generate rollback SQL to tag
CommandScope rollbackSqlCommand = new CommandScope("rollbackSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "version-1.0");

// Generate rollback count SQL
CommandScope rollbackCountSqlCommand = new CommandScope("rollbackCountSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("count", 2);

// Generate rollback to date SQL
CommandScope rollbackToDateSqlCommand = new CommandScope("rollbackToDateSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("date", "2023-01-01T00:00:00");

Changelog Commands

Manage changelog synchronization:

// Sync changelog
CommandScope changelogSyncCommand = new CommandScope("changelogSync")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Sync to tag
CommandScope changelogSyncToTagCommand = new CommandScope("changelogSyncToTag")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "version-1.0");

// Generate sync SQL
CommandScope changelogSyncSqlCommand = new CommandScope("changelogSyncSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

Utility Commands

Various utility and maintenance operations:

// Show status
CommandScope statusCommand = new CommandScope("status")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("verbose", true);

// Validate changelog
CommandScope validateCommand = new CommandScope("validate")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Clear checksums
CommandScope clearChecksumsCommand = new CommandScope("clearChecksums")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Calculate checksum
CommandScope calculateChecksumCommand = new CommandScope("calculateChecksum")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("changesetPath", "db/changelog/changes/001-create-table.xml")
    .addArgumentValue("changesetAuthor", "admin")
    .addArgumentValue("changesetId", "1");

// Tag database
CommandScope tagCommand = new CommandScope("tag")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "release-1.0");

// Check tag existence
CommandScope tagExistsCommand = new CommandScope("tagExists")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("tag", "release-1.0");

Lock Management Commands

Manage database locks:

// List locks
CommandScope listLocksCommand = new CommandScope("listLocks")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Release locks
CommandScope releaseLocksCommand = new CommandScope("releaseLocks")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

Documentation Commands

Generate database documentation:

// Generate database documentation
CommandScope dbDocCommand = new CommandScope("dbDoc")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("outputDirectory", "./dbdoc");

// Generate changelog from database
CommandScope generateChangelogCommand = new CommandScope("generateChangelog")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("changelogFile", "generated-changelog.xml");

Diff Commands

Compare databases and generate change scripts:

// Compare databases
CommandScope diffCommand = new CommandScope("diff")
    .addArgumentValue("referenceUrl", "jdbc:h2:mem:reference")
    .addArgumentValue("referenceUsername", "sa")
    .addArgumentValue("referencePassword", "")
    .addArgumentValue("url", "jdbc:h2:mem:target")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "");

// Generate diff changelog
CommandScope diffChangelogCommand = new CommandScope("diffChangelog")
    .addArgumentValue("referenceUrl", "jdbc:h2:mem:reference")
    .addArgumentValue("referenceUsername", "sa")
    .addArgumentValue("referencePassword", "")
    .addArgumentValue("url", "jdbc:h2:mem:target")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("changelogFile", "diff-changelog.xml");

// Snapshot database
CommandScope snapshotCommand = new CommandScope("snapshot")
    .addArgumentValue("url", "jdbc:h2:mem:test")
    .addArgumentValue("username", "sa")
    .addArgumentValue("password", "")
    .addArgumentValue("snapshotFormat", "json");

Command Results

The CommandResults object contains the results of command execution:

// Execute command and get results
CommandResults results = updateCommand.execute();

// Access result data (varies by command)
// Results structure depends on specific command executed

Common Arguments

Database Connection Arguments

Standard database connection parameters used across commands:

.addArgumentValue("url", "jdbc:h2:mem:test")           // Database URL
.addArgumentValue("username", "sa")                    // Database username  
.addArgumentValue("password", "")                      // Database password
.addArgumentValue("driver", "org.h2.Driver")           // JDBC driver class

Changelog Arguments

Changelog and filtering parameters:

.addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")  // Changelog file path
.addArgumentValue("contexts", "dev,test")              // Execution contexts
.addArgumentValue("labelFilter", "feature-1")         // Label expression
.addArgumentValue("defaultsFile", "liquibase.properties")  // Properties file

Schema Arguments

Schema and catalog targeting:

.addArgumentValue("defaultSchemaName", "public")       // Default schema
.addArgumentValue("defaultCatalogName", "mydb")        // Default catalog  
.addArgumentValue("liquibaseSchemaName", "liquibase")  // Liquibase schema
.addArgumentValue("liquibaseCatalogName", "liquibase") // Liquibase catalog

Example Usage

Complete Update Workflow

import liquibase.command.CommandScope;
import liquibase.command.CommandResults;

try {
    // Validate changelog first
    CommandScope validateCommand = new CommandScope("validate")
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
        .addArgumentValue("username", "dbuser")
        .addArgumentValue("password", "dbpass");
    
    validateCommand.execute();
    
    // Check status
    CommandScope statusCommand = new CommandScope("status")
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
        .addArgumentValue("username", "dbuser")
        .addArgumentValue("password", "dbpass")
        .addArgumentValue("verbose", true);
    
    CommandResults statusResults = statusCommand.execute();
    
    // Execute update
    CommandScope updateCommand = new CommandScope("update")
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
        .addArgumentValue("username", "dbuser")
        .addArgumentValue("password", "dbpass")
        .addArgumentValue("contexts", "production")
        .addArgumentValue("labelFilter", "release-2.0");
    
    CommandResults updateResults = updateCommand.execute();
    
    // Tag the release
    CommandScope tagCommand = new CommandScope("tag")
        .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
        .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
        .addArgumentValue("username", "dbuser")
        .addArgumentValue("password", "dbpass")
        .addArgumentValue("tag", "release-2.0-deployed");
    
    tagCommand.execute();
    
} catch (CommandExecutionException e) {
    System.err.println("Command execution failed: " + e.getMessage());
    throw e;
}

Rollback Workflow with SQL Preview

// First generate rollback SQL for review
CommandScope rollbackSqlCommand = new CommandScope("rollbackSql")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
    .addArgumentValue("username", "dbuser")
    .addArgumentValue("password", "dbpass")
    .addArgumentValue("tag", "release-1.0");

CommandResults sqlResults = rollbackSqlCommand.execute();

// After review, execute actual rollback
CommandScope rollbackCommand = new CommandScope("rollback")
    .addArgumentValue("changelogFile", "db/changelog/db.changelog-master.xml")
    .addArgumentValue("url", "jdbc:postgresql://localhost:5432/mydb")
    .addArgumentValue("username", "dbuser")
    .addArgumentValue("password", "dbpass")
    .addArgumentValue("tag", "release-1.0");

CommandResults rollbackResults = rollbackCommand.execute();

Database Comparison

// Compare two databases
CommandScope diffCommand = new CommandScope("diff")
    .addArgumentValue("referenceUrl", "jdbc:postgresql://prod:5432/mydb")
    .addArgumentValue("referenceUsername", "readonly")
    .addArgumentValue("referencePassword", "password")
    .addArgumentValue("url", "jdbc:postgresql://staging:5432/mydb")
    .addArgumentValue("username", "readonly")
    .addArgumentValue("password", "password");

CommandResults diffResults = diffCommand.execute();

// Generate changelog for differences
CommandScope diffChangelogCommand = new CommandScope("diffChangelog")
    .addArgumentValue("referenceUrl", "jdbc:postgresql://prod:5432/mydb")
    .addArgumentValue("referenceUsername", "readonly")
    .addArgumentValue("referencePassword", "password")
    .addArgumentValue("url", "jdbc:postgresql://staging:5432/mydb")
    .addArgumentValue("username", "readonly")
    .addArgumentValue("password", "password")
    .addArgumentValue("changelogFile", "sync-staging-to-prod.xml");

CommandResults changelogResults = diffChangelogCommand.execute();

Install with Tessl CLI

npx tessl i tessl/maven-org-liquibase--liquibase-core

docs

changelog.md

command-framework.md

configuration.md

database-operations.md

database-support.md

diff-comparison.md

exceptions.md

index.md

tile.json