migratoor

Database migration safety checker MCP server. Catch dangerous migrations before they hit production.

Problem

Developers write migrations, deploy, and accidentally lock production tables for minutes. Or drop a column that running code still references. Or create an index that blocks all writes. These cause real outages.

migratoor checks your SQL migrations against 14 proven safety rules from Squawk and strong_migrations, explains why each pattern is dangerous, and suggests the safe alternative — all as MCP tools in your AI editor.

Quick Start

As MCP Server

Works with any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot), Continue.dev, Zed, Cline, and more.

{
  "mcpServers": {
    "migratoor": {
      "command": "npx",
      "args": ["-y", "@mrzadexinho/migratoor"]
    }
  }
}

As Library

import { analyzeMigration, formatReport } from '@mrzadexinho/migratoor';

const result = analyzeMigration(`
  ALTER TABLE users ADD COLUMN email TEXT NOT NULL;
  CREATE INDEX idx_email ON users (email);
`);

console.log(formatReport(result));
// [CRITICAL] Adding NOT NULL column without default blocks reads/writes
// [CRITICAL] Creating index without CONCURRENTLY blocks all writes
// Safe alternatives provided for each finding

MCP Tools

| Tool | Description | |------|-------------| | check_migration | Analyze SQL (file path or inline) for safety issues with risk levels and safe alternatives | | list_rules | List all 14 migration safety rules with severity and description | | explain_rule | Deep dive on a specific rule — why it's dangerous, what lock it takes, safe pattern |

Rules

Critical (blocks reads/writes, causes outages)

| Rule | What it catches | |------|----------------| | add-column-not-null-without-default | Adding NOT NULL column without default rewrites entire table under ACCESS EXCLUSIVE lock | | create-index-not-concurrently | CREATE INDEX blocks all writes during index build | | change-column-type | Changing column type rewrites entire table under ACCESS EXCLUSIVE lock | | add-foreign-key-without-validation | Adding FK validates all rows, blocking writes | | set-not-null-on-existing-column | SET NOT NULL scans all rows under exclusive lock |

Warning (breaks running code, data risk)

| Rule | What it catches | |------|----------------| | drop-column | Dropping column breaks cached ORM attributes and running code | | drop-table | Data loss risk, breaks dependent views/functions | | rename-column | Running code referencing old name fails immediately | | rename-table | Same as rename column with wider blast radius | | add-unique-constraint | ACCESS EXCLUSIVE lock during index build |

Info (best practices)

| Rule | What it catches | |------|----------------| | prefer-text-over-varchar | VARCHAR(N) has no performance benefit over TEXT in PostgreSQL | | prefer-jsonb-over-json | JSON lacks equality operators and indexing, use JSONB | | multiple-ddl-statements | Multiple DDL in one migration makes rollback harder | | data-in-ddl-migration | Mixing DML with DDL risks inconsistent state on failure |

Every critical and warning finding includes the safe alternative SQL — not just "this is wrong" but "here's exactly how to fix it."

Example Output

# Migration Safety Check

**3 statement(s) analyzed, 2 issue(s) found:**
- 2 critical

**This migration is NOT safe to run in production.**

## Critical

[CRITICAL] **Adding NOT NULL column without default blocks reads/writes**
Rule: `add-column-not-null-without-default` | Line: 1
```sql
ALTER TABLE users ADD COLUMN email TEXT NOT NULL

Safe alternative: Add column as nullable, backfill, then add NOT NULL constraint

ALTER TABLE users ADD COLUMN email TEXT;
ALTER TABLE users ALTER COLUMN email SET DEFAULT <value>;
UPDATE users SET email = <value> WHERE email IS NULL;
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

## Architecture

migratoor/ src/ sql/ # SQL parsing layer types # Statement, ParsedMigration parser # Split SQL, classify DDL operations rules/ # Safety rules types # Rule, Finding, Severity postgres # 14 PostgreSQL safety rules registry # Rule lookup, list, filter engine/ # Analysis engine analyzer # Apply rules, collect findings, summarize reporter # Format results (structured + markdown) mcp/ # MCP server layer tools/ # 3 MCP tools tests/ # 93 tests mirroring src/ structure

## Prerequisites

- **Node.js** >= 20.0.0
- No other dependencies required — migratoor analyzes SQL statically

## Development

```bash
git clone https://github.com/mrzadexinho/migratoor.git
cd migratoor
npm install
npm run build
npm test

License

MIT