asmhatreandClaude Sonnet 5
67e1b2d8a9
Several documentation.red-gate.com and liquibase.com URLs added in the previous commit had since moved (Redgate restructured its docs under /flyway/reference/, Liquibase Pro pricing moved to /pricing); this repoints them at the current, verified-200 pages. Also captures docs/output/16-liquibase-lock-defaults-javap.txt, the trimmed javap output backing chapter 11's claim about Liquibase's default lock-poll and lock-wait settings, which chapter 11 previously asserted without a committed artifact to back it. Co-Authored-By: Claude Sonnet 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Q6XdRjtsp4862EM44T7i9a
47 lines
3.0 KiB
Markdown
47 lines
3.0 KiB
Markdown
# 3. Checksum validation: why editing an applied migration fails
|
|
|
|
[← 2. Anatomy of a migration run](02-anatomy-of-a-migration-run.md) · [Index](../README.md) · Next: [4. Out-of-order migrations →](04-out-of-order-migrations.md)
|
|
|
|
The most common way a migration tool earns its keep is by refusing to do something that would
|
|
otherwise fail silently, weeks later, on a machine nobody's watching. This is the simplest version
|
|
of that: someone "just tweaks" a migration file that has already run somewhere, instead of writing
|
|
a new one.
|
|
|
|
[`FlywayChecksumMismatchTest`](../src/test/java/com/ankurm/dbmigrations/flyway/FlywayChecksumMismatchTest.java)
|
|
starts a context against `V1__init.sql`, lets it apply cleanly, then edits that same file on disk
|
|
— widening a `varchar(50)` to `varchar(80)` — and starts a second context against the same
|
|
database. Flyway's default (`spring.flyway.validate-on-migrate=true`) compares every applied
|
|
migration's recorded checksum against the file's current checksum *before* attempting to migrate
|
|
anything else, and the second startup fails outright:
|
|
|
|
```
|
|
FlywayValidateException: Validate failed: Migrations have failed validation
|
|
Migration checksum mismatch for migration version 1
|
|
-> Applied to database : -712784830
|
|
-> Resolved locally : 756220147
|
|
Either revert the changes to the migration, or run repair to update the schema history.
|
|
```
|
|
|
|
(quoted verbatim from
|
|
[`docs/output/02-flyway-checksum-mismatch.txt`](output/02-flyway-checksum-mismatch.txt))
|
|
|
|
That message is doing real work: it's telling you the checksum stored in `flyway_schema_history`
|
|
for version 1 no longer matches the file Flyway just read off disk. Nothing about the *schema* is
|
|
inconsistent yet — the failure happens before any SQL runs, which is the entire point. A team that
|
|
lets this slide by running `flyway repair` out of habit is telling Flyway "the file changed on
|
|
purpose, update your record" — which is right for a comment or formatting fix, and very wrong for
|
|
"I need this table to actually have the new column now", which needs a new `V3__...` file, not a
|
|
rewrite of `V1`.
|
|
|
|
## What checksum validation is not
|
|
|
|
It is not a guarantee that the *applied* schema matches the *current* file. Flyway checks the file
|
|
against what it already recorded, not against the live schema — if someone hand-edits the table
|
|
after the fact, nothing here notices. It's a version-control safety net for the migration files
|
|
themselves, not a schema-drift detector.
|
|
|
|
## Going deeper
|
|
|
|
- [`spring.flyway.validate-on-migrate`](https://docs.spring.io/spring-boot/appendix/application-properties/index.html#application-properties.data-migration.spring.flyway.validate-on-migrate) in the Spring Boot configuration reference (`rel="nofollow"`) — `true` by default.
|
|
- [Flyway's `repair` command](https://documentation.red-gate.com/flyway/reference/commands/repair) (`rel="nofollow"`) — what actually happens to `flyway_schema_history` when you run it, and why it's a deliberate, logged action rather than something to script into a startup hook.
|