Automatic Database Migration Checksum Repair

Overview

The KnownChecksumVariantHealer is an automated utility that runs during application startup to prevent a specific class of database migration failures. It is a Flyway callback that detects and corrects known, benign checksum mismatches in the database migration history table.

This component solves a problem where an application fails to start because Flyway's validation step detects a "Migration checksum mismatch". This can happen if a previously applied migration script file is altered in a way that changes its checksum, even if the change is non-functional (e.g., editing a SQL comment).

The healer targets a very specific scenario: a migration script was shipped in two different byte variants that are functionally identical but have different checksums. Databases that applied the initial variant will fail validation against any application build that includes the final variant. Instead of requiring manual database repair, the KnownChecksumVariantHealer automatically updates the recorded checksum in the database to match the canonical version shipped with the application, allowing startup to proceed.

The process is automatic, safe, and narrowly scoped. It only acts on a predefined list of known benign variants. Any other checksum mismatch will still cause Flyway to fail validation as expected, preserving the integrity of the migration process.

How it works

The KnownChecksumVariantHealer integrates with the Flyway migration process as a Callback bean, automatically discovered and registered by the platform's Spring Boot configuration. It is designed to be idempotent and safe, ensuring that it either fixes a known issue or has no effect.

The healing process is triggered before Flyway's main validation and migration phases.

sequenceDiagram
    participant App as Application Startup
    participant Flyway
    participant Healer as KnownChecksumVariantHealer
    participant DB as Database

    App->>Flyway: Initiate migrations
    Flyway->>Healer: handle(BEFORE_VALIDATE)
    Healer->>DB: Check for history table
    alt History table exists
        DB-->>Healer: Table name
        Healer->>Healer: For each known variant...
        Healer->>DB: UPDATE history table SET checksum=toChecksum WHERE version=v AND checksum=fromChecksum
        DB-->>Healer: N rows updated
        opt N > 0
            Healer->>Healer: Log S2R-FLYWAY-CHECKSUM-HEAL
        end
    else History table does not exist
        DB-->>Healer: Not found
        Healer-->>Flyway: Return (no-op)
    end
    Healer-->>Flyway: Return
    Flyway->>Flyway: Proceed with standard validation

Execution Flow

1. Event Trigger: The healer is registered to execute on Flyway's BEFORE_VALIDATE and BEFORE_MIGRATE events.
2. Connection Handling: It operates on its own database connection with auto-commit enabled. This ensures that its updates are committed immediately and independently of any larger Flyway transaction. A failure within the healer will not cause a surrounding transaction to be rolled back.
3. History Table Discovery: The healer first determines the fully qualified name of the Flyway history table. It uses the same logic as Flyway, respecting the configured defaultSchema and schemas properties. If the history table does not exist (e.g., on a fresh database installation), the healer does nothing.
4. Checksum Update: If the history table exists, the healer iterates through a hardcoded list of known migration variants (KNOWN_VARIANTS). For each variant, it executes a SQL UPDATE statement to change the old checksum (fromChecksum) to the new, correct checksum (toChecksum) for the specified migration version.
5. Logging: If an update successfully modifies one or more rows, the healer logs a detailed INFO message with the code S2R-FLYWAY-CHECKSUM-HEAL. This log entry includes the table name, migration version, the old and new checksums, the number of rows affected, and the reason for the change.
6. Idempotency: On subsequent application startups, the UPDATE statement's WHERE clause will no longer match any rows for an already-healed variant, so the operation has no effect.

Safety and Error Handling

The entire healing process is wrapped in a try-catch block. If any SQLException or RuntimeException occurs (e.g., due to insufficient database permissions), the healer will:

1. Log a WARN message with the code S2R-FLYWAY-CHECKSUM-HEAL could not run.
2. Cease its own execution.
3. Allow the Flyway process to continue.

Flyway will then proceed with its standard validation. If the checksum mismatch was not fixed, Flyway will report its normal "Migration checksum mismatch" error and the application will fail to start. This design ensures the healer never introduces a new failure mode.

Example Log Output

When the KnownChecksumVariantHealer finds and corrects a known checksum mismatch, it produces a log entry similar to the following. This indicates that a manual database intervention was successfully avoided.

S2R-FLYWAY-CHECKSUM-HEAL table=public.flyway_schema_history version=256 from=49376275 to=-1205763391 rows=1 reason="V256 intermediate variant (2026-08-11..08-26) differs from the shipped file in one SQL comment line only; no DDL difference"

Configuration

The KnownChecksumVariantHealer is enabled automatically and has no direct configuration properties. However, its behavior is influenced by the standard Flyway configuration used by the application, as it uses these settings to locate the migration history table.

Known Variants Reference

The healer will only act on the specific version and checksum pairs defined in its internal KNOWN_VARIANTS list. Any other mismatch will be ignored and reported by Flyway as a validation failure.

Troubleshooting

All SOAP-to-REST docs