MigrationSafe

🛡️ ESLint for your Postgres migrations — catch dangerous operations before production

MigrationSafe analyzes your PostgreSQL migration files and flags potentially dangerous operations that could cause data loss, downtime, or other production issues.

Features

• ✅ Detects dangerous SQL operations (DROP TABLE, ALTER TABLE, etc.)
• ✅ Validates migration safety before deployment
• ✅ Multiple output formats: terminal, JSON, Markdown, GitHub
• ✅ Severity levels: critical, warning, info
• ✅ Automatic rewriting suggestions with AI (optional)
• ✅ Detailed scoring and recommendations
• ✅ Works with any PostgreSQL migration tool (Flyway, Liquibase, custom scripts, etc.)

Installation

npm install -g migrationsafe
# or
npx migrationsafe@latest check <pattern>

Quick Start

# Check a single migration file
migrationsafe check migrations/001_add_users.sql

# Check all migrations in a directory
migrationsafe check "migrations/**/*.sql"

# Get detailed output with scores
migrationsafe check migrations/*.sql --verbose

# Output as JSON for CI/CD
migrationsafe check migrations/*.sql --format json

# Generate GitHub comment with results
migrationsafe check migrations/*.sql --format github

# Fail if any critical issues found
migrationsafe check migrations/*.sql --fail-on critical

# Save report to file
migrationsafe check migrations/*.sql -o report.md --format markdown

Usage

Usage: migrationsafe check [options] <pattern>

Analyse migration files for safety issues

Options:
  -f, --format <format>  terminal | json | markdown | github (default: "terminal")
  --fix                  Generate AI rewrite (requires ANTHROPIC_API_KEY)
  --fail-on <severity>   critical | warning | info | never (default: "critical")
  -o, --output <file>    Write report to file
  --verbose              Show score breakdown
  -h, --help             display help for command

Output Formats

Terminal (Default)

Colorized output with violations, warnings, and safe operations.

migrationsafe check migrations/*.sql

JSON

Machine-readable format perfect for CI/CD pipelines.

migrationsafe check migrations/*.sql --format json

Markdown

Formatted report ready for documentation or pull requests.

migrationsafe check migrations/*.sql --format markdown

GitHub

Formatted as a GitHub comment for pull request reviews.

migrationsafe check migrations/*.sql --format github

Severity Levels

• Critical: Operations that could cause data loss or extended downtime
• Warning: Operations that could impact performance or require careful planning
• Info: Informational notes and best practice suggestions

Exit Codes

• 0: Analysis complete (use --fail-on to control exit behavior)
• 1: Analysis failed or violations found (when --fail-on threshold met)

CI/CD Integration

GitHub Actions

Add to your workflow:

- name: Check migrations with MigrationSafe
  run: npx migrationsafe@latest check "migrations/**/*.sql" --fail-on critical

GitLab CI

check_migrations:
  image: node:latest
  script:
    - npx migrationsafe@latest check "migrations/**/*.sql" --fail-on critical

AI-Powered Rewrites

Enable automatic rewriting suggestions using Claude AI:

ANTHROPIC_API_KEY=your-key migrationsafe check migrations/*.sql --fix

Examples

Example 1: Single File Check

$ migrationsafe check migrations/001_add_users.sql

Example 2: Directory with Markdown Output

$ migrationsafe check "migrations/**/*.sql" --format markdown -o report.md

Example 3: CI/CD with Fail on Warning

$ migrationsafe check "db/migrations/*.sql" --fail-on warning --format json

What Gets Checked

MigrationSafe analyzes for:

• Dropping tables or columns without safe patterns
• Altering column types unsafely
• Removing constraints that protect data
• Large operations without migration patterns
• Unsafe index operations
• And many more database safety patterns

License

UNLICENSED

Support

For issues, questions, or contributions, visit the repository at: https://github.com/rahul-nakum14/migrationsafe

Keep your database safe. Use MigrationSafe. 🛡️