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