Migration Guardian

mgcheck — catch unsafe database migrations before they lock production

Compatible with PostgreSQL, Supabase, Neon, AWS RDS/Aurora, Cloud SQL, TimescaleDB & CockroachDB. Whether the migration was written by you, a teammate, or an AI coding agent.

npx mgcheck

Quickstart · How it works · Safety rules · Showcase · AI agents · CI · Configuration · API · Security · Roadmap · Contributing

Free and open source (MIT). Migration Guardian is an early-stage, community-driven project. If you've ever been paged because a migration locked a table, you already have the domain knowledge to help — new rules, framework detectors and fixes are very welcome.

You can roll back application code in seconds. A bad schema migration can take your database down in milliseconds — and it usually looks completely harmless in review.

-- Looks fine. Passes local tests on 10 rows. Gets approved in review.
CREATE INDEX idx_users_email ON users(email);

-- In production:
--   • Takes a SHARE lock on "users" → every INSERT/UPDATE/DELETE blocks
--   • Requests queue behind the lock, the connection pool saturates
--   • Your API starts timing out while the index builds

This class of bug is getting more common, not less. AI coding agents (Claude Code, Cursor, Copilot, Windsurf, …) are great at writing the DDL that produces the schema you asked for, but they have no idea how big your tables are or how PostgreSQL locks behave under load.

Migration Guardian sits between whoever writes the migration and the database that runs it. It parses every statement with the real PostgreSQL grammar, flags dangerous lock and rewrite patterns, dry-runs the migration on a throwaway shadow database, and makes a human sign off on anything risky before it reaches a real database.

Requirements: Node.js 18+. Docker is optional — use --provider pglite to run everything in-process.

1. Connect your AI agents and start the watcher

npx mgcheck

The setup wizard detects installed AI clients, registers the MCP server, and opens the live approval watcher.

2. Lint migrations statically (no database needed)

npx mgcheck analyze ./migrations

3. Lint + dry-run on a shadow database

npx mgcheck run ./migrations --provider pglite --seed ./schema.sql

4. Auto-fix an unsafe migration

npx mgcheck fix ./migrations/20260101_add_email_index.sql

5. Guard every commit

npx mgcheck hook install

                 Developer  /  AI coding agent
                              │
                              ▼
 ┌──────────────────────────────────────────────────────────────┐
 │ ① Detect      Prisma · Drizzle · Supabase · Flyway · Goose · │
 │               dbmate · golang-migrate · raw .sql             │
 └──────────────────────────────┬───────────────────────────────┘
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │ ② Analyze     PostgreSQL AST (WASM) checked against 14 rules │
 │               → locks, table rewrites, data loss, rollbacks  │
 └──────────────────────────────┬───────────────────────────────┘
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │ ③ Shadow run  Execute on throwaway PGlite or Docker Postgres │
 │               (optionally seeded with your existing schema)  │
 └──────────────────────────────┬───────────────────────────────┘
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │ ④ Gate        🟢 LOW     → approved                           │
 │               🟡 MEDIUM  → y/N prompt  (or agent retry, auto) │
 │               🔴 HIGH    → blocked unless human types         │
 │                            "override"                        │
 └──────────────────────────────┬───────────────────────────────┘
                                ▼
 ┌──────────────────────────────────────────────────────────────┐
 │ ⑤ Apply       Optional: run verified SQL on the target DB    │
 │               Every decision → .mgcheck/audit.jsonl          │
 └──────────────────────────────────────────────────────────────┘

error rules block the migration (🔴 HIGH risk). warning rules are reported and require approval (🟡 MEDIUM risk).

Any rule can be re-leveled or disabled per project — see Configuration.

CREATE INDEX idx_users_email ON users(email);
ALTER TABLE users ADD COLUMN is_active boolean NOT NULL;

SET lock_timeout = '5s';

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email ON users(email);
ALTER TABLE users ADD COLUMN is_active boolean DEFAULT false NOT NULL;

Migration Guardian ships an MCP server so AI agents check their own migrations before running them — and so you stay in control of what reaches the database.

Target a single client, or also write workspace instruction files (CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules, .cursor/rules/, .github/copilot-instructions.md):

npx mgcheck setup --client cursor
npx mgcheck setup --client all --with-rules --yes

For any other MCP-compatible client:

{
  "mcpServers": {
    "migration-guardian": {
      "command": "npx",
      "args": ["-y", "mgcheck", "mcp"]
    }
  }
}

npx mgcheck (or mgcheck setup) leaves a watcher running in your terminal. Requests from every project and editor stream into it:

  👁️  Guardian Active — Watching for AI migration activity...
  ─────────────────────────────────────────────────────────
  ● manual mode (shift+tab to cycle) · type /auto or /manual

  🔔 Approval Request [HIGH RISK]
  Client: Cursor (my-web-app)
  Query:  DROP TABLE "legacy_users";
  Violations:
    • [MG006] DROP TABLE is destructive and causes permanent data loss

  Type "override" to approve this query or press Enter to reject: _

Switch approval mode on the fly with Shift+Tab / Shift+Enter, or type /auto or /manual.

npx mgcheck mode                       # show active mode and where it came from
npx mgcheck mode auto                  # set globally   (~/.mgcheck/settings.json)
npx mgcheck mode manual --project      # set per project (.mgcheckrc.json)
npx mgcheck mode auto --levels low     # auto mode, but only auto-approve LOW

Resolution order: MGCHECK_MODE env var → project config → global settings → manual.

💡 Tip: Every command below can be run without install via npx mgcheck <command>. If installed globally (npm install -g mgcheck), you can use mgcheck <command> directly.