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

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

Quick Start

$3

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

$3

`bash
export DB_GUARDIAN_API_KEY=DB-GUARDIAN-XXXXX
`

$3

`bash
npx db-scalability-guardian analyze
`

Configuration

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

`json
{
"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

`yaml
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