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

configuration.mddocs/

Configuration System

This document covers Liquibase's global configuration system through the GlobalConfiguration class, which manages settings that affect Liquibase behavior across all operations.

Imports

import liquibase.GlobalConfiguration;
import liquibase.configuration.ConfigurationDefinition;

// Enums for configuration values
import liquibase.GlobalConfiguration.DuplicateFileMode;

GlobalConfiguration Class

The GlobalConfiguration class provides access to global configuration properties that control Liquibase behavior.

Instance Access

/**
 * Get the singleton GlobalConfiguration instance
 * @return GlobalConfiguration instance
 */
public static GlobalConfiguration getInstance()

Database Table Configuration

Configuration for Liquibase tracking tables:

/**
 * Name of the database changelog table (default: "DATABASECHANGELOG")
 */
public static final ConfigurationDefinition<String> DATABASECHANGELOG_TABLE_NAME;

/**
 * Name of the database changelog lock table (default: "DATABASECHANGELOGLOCK") 
 */
public static final ConfigurationDefinition<String> DATABASECHANGELOGLOCK_TABLE_NAME;

Example Usage

// Get current table names
String changelogTable = GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue();
String lockTable = GlobalConfiguration.DATABASECHANGELOGLOCK_TABLE_NAME.getCurrentValue();

// Set custom table names
System.setProperty("liquibase.databaseChangeLogTableName", "MY_CHANGELOG");
System.setProperty("liquibase.databaseChangeLogLockTableName", "MY_CHANGELOG_LOCK");

Database Schema and Catalog Configuration

Configuration for database schema and catalog placement:

/**
 * Catalog name for Liquibase objects
 */
public static final ConfigurationProperty<String> LIQUIBASE_CATALOG_NAME;

/**
 * Schema name for Liquibase objects
 */
public static final ConfigurationProperty<String> LIQUIBASE_SCHEMA_NAME;

/**
 * Tablespace name for Liquibase objects
 */
public static final ConfigurationProperty<String> LIQUIBASE_TABLESPACE_NAME;

Example Usage

// Configure Liquibase to use specific schema
System.setProperty("liquibase.liquibaseSchemaName", "LIQUIBASE_SCHEMA");
System.setProperty("liquibase.liquibaseCatalogName", "LIQUIBASE_CATALOG");
System.setProperty("liquibase.liquibaseTablespaceName", "LIQUIBASE_TBS");

File Handling Configuration

Configuration for file encoding and path handling:

/**
 * File encoding for reading changelog files (default: UTF-8)
 */
public static final ConfigurationProperty<String> FILE_ENCODING;

/**
 * File encoding for output files
 */
public static final ConfigurationProperty<String> OUTPUT_FILE_ENCODING;

/**
 * Line separator for output files
 */
public static final ConfigurationProperty<String> OUTPUT_LINE_SEPARATOR;

/**
 * Search path for changelog files
 */
public static final ConfigurationProperty<String> SEARCH_PATH;

Example Usage

// Set file encoding
System.setProperty("liquibase.fileEncoding", "ISO-8859-1");
System.setProperty("liquibase.outputFileEncoding", "UTF-16");

// Configure search paths
System.setProperty("liquibase.searchPath", "db/changelog,db/scripts,classpath:");

// Set line separator
System.setProperty("liquibase.outputLineSeparator", "\r\n");

Database Locking Configuration

Configuration for database lock behavior:

/**
 * Lock wait time in minutes (default: 5)
 */
public static final ConfigurationProperty<Long> CHANGELOGLOCK_WAIT_TIME;

/**
 * Lock poll rate in seconds (default: 10)
 */
public static final ConfigurationProperty<Long> CHANGELOGLOCK_POLL_RATE;

Example Usage

// Configure lock timeouts
System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "10");
System.setProperty("liquibase.changelogLockPollRate", "5");

Behavior Control Configuration

Configuration for general Liquibase behavior:

/**
 * Convert data types to standard types (default: true)
 */
public static final ConfigurationProperty<Boolean> CONVERT_DATA_TYPES;

/**
 * Enable strict mode for best practices (default: false)
 */
public static final ConfigurationProperty<Boolean> STRICT;

/**
 * Force headless mode (default: false)
 */
public static final ConfigurationProperty<Boolean> HEADLESS;

/**
 * Show startup banner (default: true)
 */
public static final ConfigurationProperty<Boolean> SHOW_BANNER;

/**
 * Validate XML changelog files against XSD (default: true)
 */
public static final ConfigurationProperty<Boolean> VALIDATE_XML_CHANGELOG_FILES;

Example Usage

// Enable strict mode
System.setProperty("liquibase.strict", "true");

// Disable banner
System.setProperty("liquibase.showBanner", "false");

// Force headless mode
System.setProperty("liquibase.headless", "true");

// Disable XML validation
System.setProperty("liquibase.validateXmlChangelogFiles", "false");

// Disable data type conversion
System.setProperty("liquibase.convertDataTypes", "false");

Diff and Generation Configuration

Configuration for diff operations and changelog generation:

/**
 * Compare column order in diff operations (default: true)
 */
public static final ConfigurationProperty<Boolean> DIFF_COLUMN_ORDER;

/**
 * Include created timestamps in generated changesets (default: false)
 */
public static final ConfigurationProperty<Boolean> GENERATE_CHANGESET_CREATED_VALUES;

/**
 * Snapshot data by default in diff operations (default: false)
 */
public static final ConfigurationProperty<Boolean> SHOULD_SNAPSHOT_DATA;

Example Usage

// Configure diff options
System.setProperty("liquibase.diffColumnOrder", "false");
System.setProperty("liquibase.generateChangesetCreatedValues", "true");
System.setProperty("liquibase.shouldSnapshotData", "true");

Configuration Property Access

Direct Property Access

// Get current value of a configuration property
String currentValue = GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue();

// Check if property has been explicitly set
boolean wasSet = GlobalConfiguration.STRICT.getWasOverridden();

// Get default value
Boolean defaultValue = GlobalConfiguration.STRICT.getDefaultValue();

System Property Configuration

Most configuration can be set via system properties using the pattern liquibase.{propertyName}:

// Set via system properties
System.setProperty("liquibase.databaseChangeLogTableName", "CUSTOM_CHANGELOG");
System.setProperty("liquibase.strict", "true");
System.setProperty("liquibase.fileEncoding", "UTF-8");

// Set via environment variables (convert to uppercase and replace dots with underscores)
// LIQUIBASE_DATABASE_CHANGE_LOG_TABLE_NAME=CUSTOM_CHANGELOG
// LIQUIBASE_STRICT=true

Configuration Enums

DuplicateFileMode

Controls behavior when duplicate files are detected:

public enum DuplicateFileMode {
    WARN,    // Log warning (default)
    ERROR,   // Throw error  
    INFO,    // Log info message
    DEBUG,   // Log debug message
    SILENT   // No logging
}

UpdateSummaryEnum

Controls update summary display:

// Values depend on implementation
// Used for controlling summary output format

UpdateSummaryOutputEnum

Controls update summary output format:

// Values depend on implementation  
// Used for controlling where summary is written

Complete Configuration Example

Production Configuration

import liquibase.GlobalConfiguration;

public class ProductionLiquibaseConfig {
    
    public static void configureForProduction() {
        // Use custom schema for Liquibase tables
        System.setProperty("liquibase.liquibaseSchemaName", "LIQUIBASE");
        System.setProperty("liquibase.liquibaseCatalogName", "PROD_DB");
        
        // Configure table names
        System.setProperty("liquibase.databaseChangeLogTableName", "DB_CHANGELOG");
        System.setProperty("liquibase.databaseChangeLogLockTableName", "DB_CHANGELOG_LOCK");
        
        // Production behavior settings
        System.setProperty("liquibase.strict", "true");
        System.setProperty("liquibase.showBanner", "false");
        System.setProperty("liquibase.headless", "true");
        
        // Lock configuration for production
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "15");
        System.setProperty("liquibase.changelogLockPollRate", "30");
        
        // File handling
        System.setProperty("liquibase.fileEncoding", "UTF-8");
        System.setProperty("liquibase.outputFileEncoding", "UTF-8");
        
        // Validation settings
        System.setProperty("liquibase.validateXmlChangelogFiles", "true");
        
        // Diff settings for production comparisons
        System.setProperty("liquibase.diffColumnOrder", "true");
        System.setProperty("liquibase.generateChangesetCreatedValues", "false");
    }
    
    public static void verifyConfiguration() {
        GlobalConfiguration config = GlobalConfiguration.getInstance();
        
        System.out.println("Changelog Table: " + 
            GlobalConfiguration.DATABASECHANGELOG_TABLE_NAME.getCurrentValue());
        System.out.println("Schema: " + 
            GlobalConfiguration.LIQUIBASE_SCHEMA_NAME.getCurrentValue());
        System.out.println("Strict Mode: " + 
            GlobalConfiguration.STRICT.getCurrentValue());
    }
}

Development Configuration

public class DevelopmentLiquibaseConfig {
    
    public static void configureForDevelopment() {
        // Development-friendly settings
        System.setProperty("liquibase.strict", "false");
        System.setProperty("liquibase.showBanner", "true");
        
        // Shorter timeouts for development
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "2");
        System.setProperty("liquibase.changelogLockPollRate", "5");
        
        // Include creation timestamps in generated changesets
        System.setProperty("liquibase.generateChangesetCreatedValues", "true");
        
        // Snapshot data for easier development comparisons
        System.setProperty("liquibase.shouldSnapshotData", "true");
        
        // Flexible search path for development
        System.setProperty("liquibase.searchPath", 
            "src/main/resources/db,src/test/resources/db,classpath:");
    }
}

Configuration from Properties File

import java.io.FileInputStream;
import java.io.IOException;
import java.util.Properties;

public class PropertiesBasedConfig {
    
    public static void loadFromFile(String propertiesFile) throws IOException {
        Properties props = new Properties();
        props.load(new FileInputStream(propertiesFile));
        
        // Apply all properties that start with "liquibase."
        for (String key : props.stringPropertyNames()) {
            if (key.startsWith("liquibase.")) {
                System.setProperty(key, props.getProperty(key));
            }
        }
    }
}

// Example liquibase.properties file:
// liquibase.databaseChangeLogTableName=MY_CHANGELOG
// liquibase.liquibaseSchemaName=LIQUIBASE_SCHEMA
// liquibase.strict=true
// liquibase.fileEncoding=UTF-8
// liquibase.changelogLockWaitTimeInMinutes=10

Environment-Specific Configuration

public class EnvironmentConfig {
    
    public static void configureForEnvironment(String environment) {
        switch (environment.toLowerCase()) {
            case "production":
                configureProduction();
                break;
            case "staging": 
                configureStaging();
                break;
            case "development":
                configureDevelopment();
                break;
            default:
                throw new IllegalArgumentException("Unknown environment: " + environment);
        }
    }
    
    private static void configureProduction() {
        System.setProperty("liquibase.strict", "true");
        System.setProperty("liquibase.showBanner", "false");
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "30");
    }
    
    private static void configureStaging() {
        System.setProperty("liquibase.strict", "true");
        System.setProperty("liquibase.showBanner", "false");
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "10");
        System.setProperty("liquibase.generateChangesetCreatedValues", "true");
    }
    
    private static void configureDevelopment() {
        System.setProperty("liquibase.strict", "false");
        System.setProperty("liquibase.showBanner", "true");
        System.setProperty("liquibase.changelogLockWaitTimeInMinutes", "2");
        System.setProperty("liquibase.shouldSnapshotData", "true");
    }
}

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