Troubleshooting and Logging
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting and logging within the Liquibase ClickHouse extension provide visibility into database migration processes, cluster configuration loading, and lock management. The system utilizes standard Liquibase logging abstractions alongside Logback for test environments to capture execution details, configuration errors, and database connectivity issues.
Key areas of focus include identifying whether the system is operating in single-instance or cluster mode, verifying the integrity of the DATABASECHANGELOGLOCK table, and diagnosing failures during Liquibase actions such as update, rollback, or tag.
Logging Infrastructure
The project employs two primary logging mechanisms: the Liquibase Logger API for application logic and Logback for unit and integration testing.
Application Logging
Classes such as ParamsLoader use liquibase.Scope to retrieve a logger instance. This ensures that logs are routed through the Liquibase environment's configured appenders.
- Info Level: Used to report the discovery of cluster settings and the mode of operation (single-instance vs. cluster replicated).
- Severe Level: Used to log critical configuration failures, such as invalid property formats, typically accompanied by a full stack trace.
Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:37-39, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:95-108
Test Logging Configuration
For testing environments, the project uses Logback to direct output to the console. The default configuration sets the root logging level to WARN, suppressing verbose output unless errors occur.
Sources: src/test/resources/logback-test.xml:1-11
| Appender | Target | Pattern | Default Level |
|---|---|---|---|
STDOUT | ConsoleAppender | %d{HH:mm:ss.SSS} %-5level %logger - %msg%n | WARN |
Sources: src/test/resources/logback-test.xml:2-9
Troubleshooting Configuration Issues
The ParamsLoader is responsible for loading cluster-specific settings from a .conf file. Troubleshooting usually involves identifying missing or unknown properties within the cluster configuration block.
Configuration Validation Flow
The system validates the presence of three mandatory properties for cluster mode: clusterName, tableZooKeeperPathPrefix, and tableReplicaName. If these are missing or if unknown properties are found, the extension defaults to "single-instance" mode.
Common Configuration Errors
Errors are logged when the configuration does not match the expected schema.
| Error Type | Description | Resulting Action |
|---|---|---|
ConfigException.Missing | The cluster block or specific keys are missing from the .conf file. | Defaults to single-instance mode. |
InvalidPropertiesFormatException | Unknown properties are present or mandatory ones are missing. | Logs stack trace and defaults to single-instance. |
Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:95-112
Lock Service Troubleshooting
The ClickHouseLockService manages database execution locks to prevent concurrent migrations. Failures here often manifest as UnexpectedLiquibaseException or "No table available" info messages.
Lock Table Initialization Check
The service verifies if the lock table exists and contains the required initial record. If a LiquibaseException occurs during the check, the service determines its state based on whether the executor is allowed to update the database.
Diagnosing Connectivity and Schema Issues
In ClickHouseTest.java, troubleshooting is performed via JUnit tests that simulate various Liquibase actions. If a connection cannot be established with the ClickHouse container, a RuntimeException is thrown, wrapping the original cause.
Key methods for testing stability:
canInitializeLiquibaseSchema(): Verifies table creation.canForceReleaseLocks(): Tests ability to clear stuck locks.canReportStatus(): Checks if the current state can be retrieved from the database.
Sources: src/test/java/liquibase/ClickHouseTest.java:44-96
Summary
Troubleshooting the Liquibase ClickHouse extension relies on analyzing logs from ParamsLoader to confirm cluster configuration and monitoring ClickHouseLockService for table initialization status. By setting the logging level to INFO or DEBUG, developers can see which execution mode (single-instance vs. cluster) is active, which is critical for ensuring that migrations are correctly replicated across a ClickHouse cluster as defined in the liquibaseClickhouse.conf settings.