Skip to main content
Use check before migration SQL reaches a database. check reads SQL files or stdin. It does not connect to a database.

​
Use this when

  • A generated migration needs replay-safety proof.
  • Hand-written SQL should be gated before review.
  • CI should annotate pull requests or upload SARIF.
  • A pre-commit hook should reject unsafe staged migrations.

​
Run it

With no migration arguments, check scans every .sql file in config.migrationsDir. It exits 1 when no migrations exist unless --allow-empty is passed. Use --changed for local working-tree checks, --staged for pre-commit checks, and --base or --since for CI diff checks. Git-selected checks only include .sql files under config.migrationsDir and ignore deleted files.

​
Input

​
file | -
Migration files to check. Use - to read SQL from stdin.
Explicit directory arguments are not expanded. Use a shell glob such as database/migrations/*.sql.

​
Flags

​
text | github | sarif | json
Choose human text, GitHub workflow annotations, SARIF, or JSON.
​
boolean
Treat an empty config.migrationsDir as success for setup probes.
​
boolean
Check migration SQL changed in the working tree or index. This includes untracked migration files.
​
boolean
Check staged migration SQL only.
​
git ref
Check migration SQL returned by git diff <ref> --name-only --diff-filter=ACMR.
​
git ref
Alias the same git diff selection as --base, for CI and hook vocabulary that names a since-ref.
Use only one of --changed, --staged, --base, or --since. These flags cannot be combined with explicit migration file arguments.

​
What it checks

  • unguarded CREATE, DROP, and constraint operations;
  • unsafe DROP ... CASCADE;
  • lock hazards such as table rewrites and non-concurrent indexes;
  • transaction-incompatible statements;
  • search_path hazards;
  • SECURITY DEFINER functions without function-local search_path;
  • public-schema functions that do not explicitly revoke default PUBLIC EXECUTE;
  • same-file forward references to objects or columns created later in the migration;
  • DML that cannot be proven idempotent.

​
Exit codes

Verify

Prove apply-twice behavior with a database.

Diagnostics

Look up safety and extraction codes.

CI recipe

Add reporters to GitHub Actions.

Idempotent migrations

Learn the replay-safety model.
Last modified on July 7, 2026