Skip to content

CONCEPT Cited by 1 source

Idempotent migration

Definition

An idempotent migration is a database schema change script that produces the same end state regardless of how many times it is executed against the same database. Re-applying it after it has already succeeded is a no-op — it does not error, does not duplicate data, and does not create conflicting objects.

Why it matters for branching workflows

In a branching development model, the same migration script runs against many branches over its lifecycle: the developer branch, the CI branch, staging branches, A/B prototype branches, and eventually production. If the migration is not idempotent, any branch that has already partially applied it (or re-applies after a reset) will fail or produce inconsistent state. Non-idempotent migrations are treated as bugs.

Canonical statement

"The authorship discipline of idempotency. The same migration runs against many branches over the life of a transition, so it has to behave the same way every time. A migration that fails on re-apply is a bug."

(Source: sources/2026-06-05-databricks-enabling-evolutionary-database-development-database-branchin)

Implementation patterns

  • IF NOT EXISTS / IF EXISTS guards. CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ADD COLUMN IF NOT EXISTS, DROP INDEX IF EXISTS.
  • Migration framework metadata. Frameworks like Flyway, Liquibase, Alembic, and Knex maintain a metadata table tracking which migrations have been applied. The migrate command skips already-applied scripts.
  • Upsert-based seed data. INSERT ... ON CONFLICT DO NOTHING or MERGE for reference data population.

Anti-patterns

  • Migrations that assume a specific intermediate state. A migration depending on local changes in the branch (not yet committed upstream) will fail against any other branch that doesn't have those changes.
  • Non-guarded DDL. CREATE TABLE foo (...) without IF NOT EXISTS fails on second application.
  • Order-dependent data manipulation. UPDATE that assumes a column exists only after a prior migration in the same batch — safe if the framework guarantees ordering, but fragile across branch topologies.
Last updated · 542 distilled / 1,571 read