pg-migration-guard

An MCP server and CLI that stops AI coding agents (and humans) from shipping Postgres migrations that lock production tables.

AI coding tools are great at migration syntax. They don't know your table has 40 million rows, that CREATE INDEX blocks every write until it finishes, or that a "harmless" ALTER TABLE waiting on a lock queues every query behind it. The migration finishes in 10 ms on a laptop and takes the checkout API down in production.

pg-migration-guard gives the agent that missing knowledge. Connect it to Claude Code, Claude Desktop, Cursor or any MCP client, and the agent can check a migration before it runs it. Each finding comes with the safer rewrite.

[HIGH] line 6  create-index-not-concurrently
  CREATE INDEX idx_orders_customer ON orders (customer_id)
  Why: CREATE INDEX takes a SHARE lock: reads keep working, but every INSERT, UPDATE and
       DELETE on the table waits until the index is built. On a large table that can be minutes.
  Fix: Use `CREATE INDEX CONCURRENTLY` (outside a transaction).

• Zero runtime dependencies. The MCP protocol layer (JSON-RPC 2.0 over stdio) is implemented directly. Nothing to audit in your supply chain.

• Deterministic. Rules, not a model. Same SQL in, same answer out. That makes it safe to use as a gate.

• Works in CI too. The CLI exits non-zero on high-severity findings.

What it checks

Tables created earlier in the same migration are exempt, because they are empty.

Related MCP server: MigrationPilot

Use it from an AI agent (MCP)

git clone https://github.com/saimulhasnain-dev/pg-migration-guard && cd pg-migration-guard
npm install && npm run build

Claude Code

claude mcp add pg-migration-guard -- node /absolute/path/to/pg-migration-guard/dist/src/server.js

Claude Desktop / Cursor (claude_desktop_config.json or .cursor/mcp.json)

{
  "mcpServers": {
    "pg-migration-guard": {
      "command": "node",
      "args": ["/absolute/path/to/pg-migration-guard/dist/src/server.js"]
    }
  }
}

Then add one line to your project's CLAUDE.md / agent rules:

Before running or committing any Postgres migration, call analyze_migration and apply its fixes.

Tools

Use it in CI

node dist/src/cli.js migrations/*.sql                 # fail on high
node dist/src/cli.js --fail-on medium --tx --pg 15 db/migrate/*.sql
node dist/src/cli.js --json migrations/2026_add_index.sql

--tx tells it your tool wraps each file in a transaction (Rails, Django, Prisma and Knex do by default), so CONCURRENTLY inside one gets flagged.

Try it

npm run build
node dist/src/cli.js examples/risky.sql   # 5 high, 2 medium
node dist/src/cli.js examples/safe.sql    # the same changes, done safely: clean
npm test                                  # 19 tests, including a real MCP stdio session

Limitations

It's pattern-based, not a full SQL parser. It doesn't look inside DO blocks or function bodies, and it can't know your table sizes. A finding on a 200-row lookup table may be fine to ignore. Treat it as a reviewer that never forgets the lock rules, not as a replacement for knowing your data.

License

MIT