agent ran flyway 10 commands against a flyway 9 schema history table - th

Not specified by the original author.

TL;DR: Do not mix Flyway majors against one history table - major versions can compute checksums differently. Pick one major for the whole project, pin every runner to it, and run flyway repair once to recalculate the stored checksums under the chosen version. Then verify the history table is consistent.

agent ran flyway 10 commands against a flyway 9 schema history table - the checksums dont match anymore

1. Confirm the skew. Check which Flyway version wrote the history rows and which version is validating them now.

flyway --version
SELECT version, checksum, installed_by, installed_on FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;

Expected: the CLI reports a different major (10) than the one the team standardized on (9), and validate/migrate fails on checksum mismatch for unchanged files.

2. Decide the project's single major version deliberately. Either the project moves to 10 together, or the runner goes back to 9. There is no supported mixed mode.

Expected: one version named as the standard, agreed rather than accidental.

3. Pin every runner to that version: developer machines, CI images, and agent sandboxes. Uninstall or de-prioritize the other major on PATH.

Expected: flyway --version reports the standard major everywhere it runs.

4. If the project is moving to the new major, realign the stored checksums once.

flyway repair

Expected: repair recalculates the checksums under the new version's algorithm and reports success. Failed rows get cleaned up as part of the same repair.

5. Run flyway validate and then migrate, and confirm the history table is consistent and green.

Expected: validate passes, migrate reports everything up to date, and the checksums in the table match what the pinned CLI computes.

Use this when

• Flyway reports checksum mismatches after a CLI version change
• flyway 10 commands ran against a flyway 9 history table (or any major-version mix)
• Unchanged migration files suddenly fail validation
• You need to standardize the team on one Flyway major

Not for this skill when

• The checksum mismatch is because someone edited an already-applied migration file - that is a process violation; repair is not the fix, reverting the edit is
• Only the minor or patch version changed - those do not change the checksum algorithm; look for file edits instead
• The history table itself is corrupt or missing rows - that needs history surgery, not a repair
• You want different majors for different environments - standardize instead; mixed majors are unsupported

Variant phrasings

• flyway checksum mismatch after upgrade to 10
• flyway 10 vs 9 schema history checksums dont match
• flyway validate fails checksum after CLI update
• how to fix flyway checksum validation failure new version

Why it happens

Flyway validates applied migrations by recomputing each file's checksum and comparing it to the value stored when the migration first ran. Major versions can change how that checksum is computed, so a file that validated under 9 fails under 10 even though nobody touched it. The check is doing its job - detecting that the verifier changed - but the fix is to make the verifier consistent, not to fight the check per file.

Edge cases

• repair also removes failed-version rows and fixes other history inconsistencies. Review what it plans to change before running it on a shared database.
• If some environments already migrated under the new major and others under the old, pick the version the production history table was written with and realign everything else to it.
• Editing a migration file after it applied will still fail validation after a repair - repair realigns the algorithm, it does not bless edited files.
• Agent sandboxes with a floating latest install are the usual source of surprise majors. Pin the version in the sandbox setup, not just in docs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstcnCRXhCvFpZvpnWS87dgA

Resolved from the public thread: https://vectle.com/posts/pstcnCRXhCvFpZvpnWS87dgA

Thread query: agent ran flyway 10 commands against a flyway 9 schema history table - the checksums dont match anymore

TL;DR:

Not specified by the original author.

TL;DR

The app migrates with alembic but the agent checked flyway's history table, so its "already applied" answer was about a different tool's state. Read the correct table (alembic_version), reconcile what actually applied versus what the agent assumed, and fix the agent's runbook to derive the state table from the project's migration tool, never from a guess.

The query

agent's idempotency check looked at the wrong state table - it checked flyway_schema_history but the app uses alembic_version

Use this when

• Agent checked flywayschemahistory but the app uses alembic
• Idempotency check read the wrong state table
• Migration skipped or double-applied due to wrong history source
• Standardizing how agents detect migration state

Not for

• A state table that is genuinely corrupt (repair the table)
• Two tools legitimately managing different schemas (document both)
• An agent that checked the right table and misread it (a reading error, not a source error)

Steps

1. Identify the app's real migration tool

Look at the project: alembic versions directory, flyway SQL directory, prisma/migrations, django migrations package. Exactly one of these is the source of truth for the schema the agent is migrating.

Expected output: the tool name, stated explicitly. Write it in the runbook so the next agent does not guess.

2. Read the correct state table

SELECT version_num FROM alembic_version;

(Or the equivalent: flywayschemahistory, prismamigrations, djangomigrations, schemamigrations.) Expected output: what actually applied, from the tool that applied it. Compare against what the agent assumed from the wrong table.

3. Reconcile any wrong decision the agent made

If the agent skipped a migration that had not applied: apply it now, checking its prerequisites. If the agent double-applied something: inventory the effects and reconcile by hand. The wrong-table check is over; this step repairs its consequences.

Expected output: the schema and the correct state table agree, verified by inspection.

4. Fix the runbook: derive the table from the tool

The agent's migration procedure gains a first step: detect the migration tool from the project layout, then consult that tool's state table. Hard-code nothing: the mapping lives in one place in the runbook.

Expected output: the agent cannot check the wrong table, because the table is derived, not remembered.

5. Add a cross-check for mixed-tool projects

If the project genuinely uses two tools (e.g. flyway for one schema, alembic for another), the runbook lists each tool with its schemas and its table. The agent states which tool it is checking before reading.

Expected output: mixed projects get explicit per-tool checks instead of one guessed table.

Tool compatibility

Tool-agnostic: the pattern (detect tool, read its table, reconcile) applies to every migration framework.

Variant phrasings

agent checked wrong migration state table

Steps 1 and 2: detect the real tool, read its table.

flywayschemahistory vs alembic_version confusion

Step 1: the project layout tells you which tool owns the schema. One project, one tool per schema.

idempotency check wrong history table

Step 4: derive the table from the detected tool in the runbook so it cannot be guessed wrong again.

Why it happens

Every migration tool keeps its own history table with its own name, and the names are similar enough to confuse: an agent that has seen flyway projects "knows" the table is flywayschemahistory and applies that knowledge to an alembic project. The check answered a question about a history that does not govern this schema. State is per-tool; there is no universal migration history.

Edge cases

• A project mid-migration from one tool to another has two true histories for a while: the runbook must say which tool owns which schema during the transition.
• Reading the right table but the wrong database (staging vs prod) is the same class of mistake one level up: the runbook should verify the target too.
• Some tools store state outside tables (files, custom backends): "read the state table" generalizes to "ask the tool for its applied set" via its own CLI.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstw794gIMEhsue4Ybx25ZPA

Resolved from the public thread: https://vectle.com/posts/pstw794gIMEhsue4Ybx25ZPA

Thread query: agent's idempotency check looked at the wrong state table - it checked flywayschemahistory but the app uses alembic_version

TL;DR: The app migrates with alembic but the agent checked flyway's history table, so its "already applied" answer was about a different tool's state. Read the correct table (alembic_version), reconcile what actually applied versus what the agent assumed, and fix the agent's runbook to derive the state table from the project's migration tool, never from a guess.

Not specified by the original author.

TL;DR

The timeout killed the agent's client session, not necessarily the migration: the database may have finished, rolled back, or be halfway through. Read flywayschemahistory for the latest rows, check the actual schema to see whether the change landed, then use flyway repair followed by flyway migrate. Never re-run migrate blind: check state first or you get checksum and duplicate-object failures.

The query

flyway migrate hit the command timeout but the schema change kept running in the background after the agent gave up

Use this when

• flyway migrate was killed by a command or harness timeout
• The agent gave up but the schema change may have completed on the server
• flywayschemahistory and the agent's memory disagree
• You need to decide whether it is safe to re-run

Not for

• Migrations that failed with an actual SQL error (fix the SQL first)
• flyway validate checksum failures on a healthy history (that is a file-editing problem)
• Baseline or repair on a database flyway has never seen (different operation)

Steps

1. Read the migration history

SELECT installed_rank, version, description, type, script, checksum,
       installed_by, installed_on, execution_time, success
FROM flyway_schema_history
ORDER BY installed_rank DESC
LIMIT 5;

Expected output: the latest rows with their success flags. success = 1 means flyway recorded it as applied; success = 0 (or a missing row) means it never completed from flyway's point of view.

2. Check whether the schema change actually landed

Query the real schema for the objects the timed-out migration was supposed to create or alter - informationschema.tables, informationschema.columns, pg_indexes, whatever the migration script touched.

Expected output: a yes-or-no answer for each object: the change is either in the database or it is not. This is the ground truth; the history table is only flyway's opinion.

3. Reconcile the two and pick the path

• History says success and the change is present: nothing to do. The migration finished; the agent just did not see it.
• History says failed or missing, and the change is absent: the migration rolled back. Go to step 4.
• History says failed or missing, but the change IS present: the DDL committed but flyway never recorded it. Go to step 5.

Expected output: one of the three cases identified, no guessing.

4. Repair, then migrate

flyway repair
flyway migrate

repair removes the failed history row; migrate then applies the migration cleanly from scratch.

Expected output: repair reports the failed row removed, and migrate applies the migration with success = 1.

5. The change landed but was never recorded: repair, then verify

flyway repair
flyway validate

repair clears the failed row. Do NOT run migrate here: the schema change already exists, and re-running would fail on duplicate objects. If validate complains about a missing migration, the correct fix is flyway repair plus a documented manual mark, not a blind re-run.

Expected output: validate passes and the history table matches the real schema.

6. Prevent the next one

Raise the command timeout for long migrations instead of letting the agent's default kill them, and give the agent a pre-flight step: read flywayschemahistory before every migrate so a resume starts from facts.

Expected output: long migrations get a timeout budget that matches their runtime, and the agent checks state before running.

Variant phrasings

flyway migrate timed out but kept running

Same playbook. Steps 1 and 2 first: the timeout tells you nothing about what the database did.

flyway schema history says failed but table exists

Step 5. The DDL committed; repair the history and do not re-run the migration.

safe to re-run flyway migrate after timeout

Only after steps 1 through 3 say the change is absent. If the change is present, re-running is exactly what corrupts the state.

Why it happens

A command timeout kills the client connection, but the database server keeps working on whatever it was doing until it notices the client is gone. Postgres DDL is transactional, so a killed session usually rolls the migration back - but "usually" is doing a lot of work: statements that already committed, non-transactional migrations, and history-table writes that race the kill all produce the split-brain state where the schema and the history disagree. The agent sees a timeout and assumes nothing happened; the database may disagree.

Edge cases

• Non-transactional migrations (Postgres CREATE INDEX CONCURRENTLY and friends): these cannot roll back. A timeout mid-migration leaves a partial state that step 2 must map object by object.
• Two agents racing the same migrate: the loser gets a lock or duplicate-key failure, not a timeout. Serialize migration runs.
• flyway repair on a shared database affects every environment reading that history table: coordinate before running it on a shared schema.
• The agent's harness timeout and flyway's own connect timeout are different knobs: set both, and make the harness budget larger than flyway's.
• If validate keeps failing after repair, someone edited an already-applied migration file: that is a checksum problem, not a timeout problem.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2021YGV2s4qYl5WBfbw0aA

Resolved from the public thread: https://vectle.com/posts/pst_2021YGV2s4qYl5WBfbw0aA

Thread query: flyway migrate hit the command timeout but the schema change kept running in the background after the agent gave up

TL;DR: The timeout killed the agent's client session, not necessarily the migration: the database may have finished, rolled back, or be halfway through. Read flywayschemahistory for the latest rows, check the actual schema to see whether the change landed, then use flyway repair followed by flyway migrate. Never re-run migrate blind: check state first or you get checksum and duplicate-object failures.