pg-migration-risk

The problem

Migration tools execute SQL. They do not warn you that CREATE INDEX without CONCURRENTLY will block writes, or that ALTER COLUMN TYPE may rewrite a hot table. Teams find out in production, or during a tense deploy window. I wanted a small check you can run locally or in CI, before the migration lands.

What I built

So I built pg-migration-risk. It walks a .sql migration file with static heuristics and reports fail or warn findings with a short mitigation tip. DROP TABLE, blocking indexes, type changes, foreign keys, and a few other patterns show up early. Output is human by default, or JSON when you need CI plumbing. Exit codes match the same shape as mcp-health: 0 ok, 1 warnings, 2 failures.

It is intentionally not a full SQL planner. Treat the report as a review aid, not a guarantee that production will be quiet.

Signals

v0.1

Static heuristics shipped

CI ready

Human report or JSON exit codes

How to use it

1. Clone the repo and install dependencies.
2. Point the check at a migration file, or use the fixtures to see what risky SQL looks like.
3. Use --json when you want machine-readable output in CI.
4. Treat high-risk findings as a reason to rewrite the migration before you ship it.

1git clone https://github.com/leon-pixel/pg-migration-risk.git2cd pg-migration-risk3npm install4npm run check -- fixtures/risky.sql

1npm run build2node dist/cli.js check --json fixtures/safe.sql

1[FAIL] CREATE_INDEX_BLOCKING  (statement #2)2  CREATE INDEX without CONCURRENTLY blocks writes for the duration3  tip: Use CREATE INDEX CONCURRENTLY (cannot run inside a transaction block)

What it doesn't do

• It does not run a full SQL planner or talk to Postgres yet.
• Heuristics can false-positive. Use the report as a review aid.
• Dialect coverage is focused on common Postgres migration patterns, not every ORM quirks list.

Links

View on GitHub