I tested a PostgreSQL migration checker on 760 real migration files

Description and use

The author tested the static tool pg-migration-guard on 760 migration files, finding 1,340 potential issues, and integrated it into GitHub Actions to check only new changes.

Problem

Valid SQL migrations can still cause production issues such as blocking writes or rewriting large tables, yet these problems are hard to detect during code review.

Outcome

The tool identified 1,340 rule matches across 760 migration files, demonstrating its ability to surface potential safety issues before deployment.

Workflow

• 1. Run pg‑migration‑guard on the migration files with the --changed-since flag to limit analysis to the current PR.
• 2. In GitHub Actions, configure the job to trigger on migrations/**/*.sql and run the tool with the appropriate flags.
• 3. The tool outputs GitHub‑style annotations for each finding and exits with a code indicating safety threshold failures.
• 4. Optionally, provide a database URL to enable catalog inspection for severity adjustment.

Evidence

I used the migration histories from Cal.com and Documenso: 760 SQL migration files, 2,638 SQL statements, 1,340 findings from the initial full-history scan

Source

The CLI now accepts a Git reference: npx pg-migration-guard "migrations/**/*.sql" --changed-since origin/main

Source

The current rules cover a deliberately limited set of PostgreSQL operations: indexes created without CONCURRENTLY, CREATE INDEX CONCURRENTLY inside a transaction, SET NOT NULL on existing tables, column type changes that may rewrite a table, volatile defaults, foreign keys that validate existing rows immediately, table and column removal, ALTER TABLE without a migration-level lock_timeout

Source