migrolint

A framework-agnostic linter for your database migrations folder. It catches the boring, expensive mistakes that pass locally and only blow up when CI actually runs the migrations — duplicate version numbers, sequence gaps, and up migrations with no matching down. No database connection, no framework lock-in, zero dependencies (pure standard library).

pip install migrolint

migrolint                      # auto-detects ./migrations, db/migrations, ...
migrolint db/migrations --strict

The problem

Two developers branch off main, each adds 0007_add_index.sql, both merge. Now your migrations folder has two migrations claiming version 0007. Your runner picks one and silently skips the other — or aborts the whole deploy. This is a known, recurring failure in every sequence-numbered migration tool.

The existing linters (django-migration-linter, Flyway's own checks) are tied to one framework or need a live database. If you use raw SQL with goose, dbmate, golang-migrate, or a hand-rolled folder, there's nothing that just looks at the filenames and tells you they're sane. That's migrolint.

What it checks

Naming conventions it understands

migrolint reads version numbers out of the filename, across the conventions people actually use:

Timestamp-style versions are recognized but exempt from SEQ_GAP (they're not meant to be contiguous). Well-known non-migration files (schema.rb, structure.sql, seeds.rb, …) and any non-migration extension are skipped.

Usage

migrolint                      # scan the first migrations dir it finds
migrolint db/migrations        # scan a specific dir
migrolint app/migrations svc/migrations   # scan several
migrolint --json               # machine-readable, for tooling
migrolint --strict             # warnings become errors (exit 1) — good for CI
migrolint --ext .sql,.py       # override which extensions count
migrolint --ignore baseline.sql,seed.sql

You can also run it as a module: python -m migrolint db/migrations.

As a pre-commit / CI gate

# .pre-commit-config.yaml
- repo: local
  hooks:
    - id: migrolint
      name: migrolint
      entry: migrolint --strict
      language: system
      pass_filenames: false

# GitHub Actions
- run: pipx run migrolint --strict

Example output

migrolint db/migrations (14 files, 12 migrations)

  ✗ DUPE_NUM     version 0007 used by 2 migrations:
       0007_add_index.up.sql
       0007_add_orders_fk.up.sql
  ⚠ MISSING_DOWN 0009_drop_legacy.up.sql — no matching .down file
  ⚠ SEQ_GAP      missing version(s): 5

1 error, 2 warnings.

Exit codes

Also available for Node

Same checks, same flags: npx migrolint (source: migrolint). Both ports read filenames identically, so a mixed-language team gets the same verdict.

License

MIT