Skip to content

fix #48: support locking for clickhouse - #120

Draft
jaccozilla wants to merge 1 commit into
flyway:mainfrom
jaccozilla:48-clickhouse-locking
Draft

jaccozilla wants to merge 1 commit into
flyway:mainfrom
jaccozilla:48-clickhouse-locking

Conversation

@jaccozilla

@jaccozilla jaccozilla commented Mar 5, 2026 •

Copy link
Copy Markdown

#48

Depends on flyway/flyway#4212. A little bit of dependency management/consolidation for junit and test containers

Doc explaining how locking is implemented:

    /**
     * This implementation leverages an insert-based locking strategy that is compatible with ClickHouse's
     * limitations (e.g., no standard transactional row-level locks limited DELETE support on MergeTree,
     * and no real Primary Key constraints). It is designed to support concurrent Flyway migrations across
     * distributed nodes or processes via insert timing and deterministic resolution of owners.
     *
     * <p>
     * Locking Strategy Overview:
     * <ul>
     *   <li>Each process attempting to acquire the lock inserts a row into the Flyway schema history table
     *       with a unique `version`, `description = 'flyway-lock'`, and a current timestamp.</li>
     *   <li>High-precision timestamps are captured using `now64(9)` which returns a DateTime64 with nanosecond precision.
     *       This timestamp is split across two columns:
     *       <ul>
     *         <li>`installed_on` (DateTime): stores the whole-second part via `toDateTime(now64(9))`, truncating subseconds</li>
     *         <li>`checksum` (Int32): stores the subsecond nanoseconds via `(now64(9) - toDateTime(now64(9))) * 1000000000`,
     *             extracting the fractional seconds and converting to nanoseconds as an integer</li>
     *       </ul>
     *       This split allows nanosecond-precision ordering while working within the table's existing schema.
     *   </li>
     *   <li>To determine the lock owner, the table is queried using `ORDER BY (installed_on, checksum, version)`
     *       and the first row is selected. This ensures consistent ordering across processes and helps resolve
     *       race conditions if two inserts occur within the same second.</li>
     *   <li>Unlocking is performed by deleting the specific lock row matching the unique `version`.</li>
     * </ul>
     * </p>
     */

@jaccozilla
jaccozilla marked this pull request as draft March 5, 2026 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant