DB Scalability Guardian

Analyze database migrations for scalability and evolvability risks before they hit production.

Features

• 🔍 16+ deterministic rules — Detects NOT NULL additions, type changes, drops, index locks, enum modifications
• 🤖 AI-powered analysis — Architectural insights and future feature blockers (paid plans)
• 🚦 CI/CD gate — Block deployments on HIGH/CRITICAL findings
• 📊 Multiple formats — JSON + Markdown reports
• 🔀 Git-aware — Only analyzes changed migrations between branches

Installation

npm install --save-dev db-scalability-guardian

Quick Start

1. Get Your API Key

Create a free account at db-guardian.com and generate your API key.

2. Set Environment Variable

export DB_GUARDIAN_API_KEY=DB-GUARDIAN-XXXXX

3. Run Analysis

npx db-scalability-guardian analyze

Configuration

Create guardian.config.json in your repository root (optional):

{
  "database": {
    "migrationsPath": "prisma/migrations"
  },
  "gate": {
    "failOn": ["HIGH", "CRITICAL"]
  },
  "guardian": {
    "enableAI": true
  }
}

| Option | Description | Default | |--------|-------------|---------| | database.migrationsPath | Path to migrations folder | prisma/migrations | | gate.failOn | Severities that cause exit code 1 | ["HIGH", "CRITICAL"] | | guardian.enableAI | Enable AI analysis (paid plans) | true |

GitHub Actions

name: DB Scalability Check

on:
  pull_request:
    branches: [main]

jobs:
  guardian:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run DB Scalability Guardian
        run: npx db-scalability-guardian analyze
        env:
          DB_GUARDIAN_API_KEY: ${{ secrets.DB_GUARDIAN_API_KEY }}

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: guardian-reports
          path: guardian-reports/

Output

Reports are generated in guardian-reports/:

| File | Description | |------|-------------| | guardian-report.json | Machine-readable findings | | guardian-report.md | Human-readable report | | guardian-llm-analysis.md | AI architectural analysis (if enabled) |

Detected Patterns

| Severity | Patterns | |----------|----------| | CRITICAL | DROP TABLE, DROP COLUMN, TRUNCATE | | HIGH | ADD COLUMN NOT NULL, TYPE CHANGE, RENAME TABLE, ALTER TYPE ADD/DROP VALUE, SET NOT NULL | | MEDIUM | CREATE INDEX, ADD FK, RENAME COLUMN, Multiple ALTER TABLE, UPDATE/DELETE | | LOW | DROP INDEX |

Exit Codes

• 0 — Success, no blocking findings
• 1 — Blocking findings detected

Pricing

| Plan | Deterministic | AI Analysis | Price | |------|--------------|-------------|-------| | Free | ✅ Unlimited | ❌ | $0 | | Starter | ✅ Unlimited | 50/month | $9/mo | | Professional | ✅ Unlimited | 200/month | $29/mo |

Overage: $0.015 per additional AI analysis.

License

ISC