PrismaFlow - Visual Prisma Migration Safety

Overview

PrismaFlow is a local-first CLI and dashboard for understanding Prisma migration history, schema health, drift, risk, and deployment readiness in seconds.

Architecture

Layer	Technology	Role
CLI	Node.js 20, Commander	Project detection, commands, local server startup
Core engines	TypeScript, Prisma CLI	Migration timeline, drift detection, risk scoring, simulation
API	Hono	Authenticated local REST and SSE API
Dashboard	Next.js	Visual migration, drift, risk, simulation, and schema views

V1 Scope

Included

Local dashboard, CLI checks, reports, risk analysis, simulation, schema explorer, and token-protected local API.

Not included yet

Hosted cloud sync, accounts, team RBAC, paid limits, and a first-class multi-environment dashboard.

Installation

Run PrismaFlow from the root of a project that contains `prisma/schema.prisma`. Requirements: Node.js 20+, Prisma 5+, and `DATABASE_URL` for live database checks.

terminal

cd /path/to/prisma-project
npx prisma-flow
# Optional installs
npm install --save-dev prisma-flow
npm install -g prisma-flow

CLI Reference

The default command opens the dashboard. Use focused commands for CI, terminal workflows, generated artifacts, and advanced local maintenance.

Command Matrix

Command	Use	Options
prisma-flow	Open the local dashboard. Alias for `dashboard`.	none
dashboard	Start the Hono API and bundled Next.js dashboard.	-p, --port <port>; --no-open
status	Print project health, drift, risk, and readiness.	--json; --quiet
check	CI-friendly safety gate for pending, failed, drifted, or risky migrations.	--ci; --json; --fail-on-risk <level>; --quiet
plan	Generate a deploy decision with blockers, priority actions, and exact next commands.	--format <format>; --json; --ci; -o, --output <path>
report	Generate JSON or Markdown reports for reviews and CI artifacts.	--format <format>; --json; -o, --output <path>
doctor	Validate local Node, Prisma, schema, migrations, and database setup.	--json
inspect <migration>	Inspect one migration, SQL, risks, and rollback plan.	--json; --sql; --rollback
simulate <migration>	Preview SQL statements and destructive warnings.	--json; --fail-on-destructive
history	Show the migration timeline in the terminal.	--limit <n>; --json; --git
diff	Compare Prisma schema against a database URL.	--from <url>; --json; --breaking-only
compare	Compare named environments from config.	--envs <names>; --json
repair	Suggest drift repairs and optionally apply safe repair steps.	--apply; --json
rollback <migration>	Generate rollback SQL for a migration.	--json; --print-sql; --include-manual
init	Create `prismaflow.config.ts` with documented defaults.	-f, --force

Core Workflow

terminal

prisma-flow dashboard --port 5555
prisma-flow status --json
prisma-flow plan --format markdown --output prismaflow-plan.md
prisma-flow check --ci --fail-on-risk high
prisma-flow report --format markdown --output prismaflow-report.md
prisma-flow doctor --json

Analysis and Safety

terminal

prisma-flow inspect 20260228120000_add_billing --sql --rollback
prisma-flow simulate 20260228120000_add_billing --fail-on-destructive
prisma-flow history --limit 25 --git

Advanced Local Utilities

These commands are available for local automation and maintenance. Review output before applying repairs or using generated rollback SQL.

terminal

prisma-flow diff --from "$DATABASE_URL" --breaking-only
prisma-flow compare --envs dev,staging,prod --json
prisma-flow repair --json
prisma-flow repair --apply
prisma-flow rollback 20260228120000_add_billing --print-sql

Dashboard

The V1 dashboard focuses on the main migration safety workflow: Overview, Migrations, Drift, Risks, Simulate, and Schema.

Overview

Detected project, health score, deployment plan, readiness checks, and suggested next actions.

Migrations

Timeline with applied, pending, failed, created, applied, duration, and risk fields.

Drift

What changed, where, why it matters, SQL evidence, and suggested action.

Risks

Low, medium, high, and critical migration risk analysis.

Simulate

Generated SQL, destructive statements, affected objects, locks, and mode.

Schema

Models, fields, relations, enums, indexes, constraints, and ERD-style overview.

Reports and CI

V1 reports and CI checks are free, local, and suitable for GitHub Actions or any shell pipeline.

.github/workflows/prismaflow.yml

name: PrismaFlow
on: [pull_request]
jobs:
  prismaflow:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx prisma-flow plan --ci --json
      - run: npx prisma-flow check --ci --json
      - run: npx prisma-flow report --format markdown --output prismaflow-report.md

Exit code	Meaning
0	Ready
1	Pending migrations
2	Schema drift detected
3	Failed migrations
4	Runtime or configuration error
5	Risk threshold exceeded with --fail-on-risk

API Reference

The dashboard uses a local authenticated API. The token is generated per server process and passed as `?token=...` or `Authorization: Bearer ...`.

GET /api/status

{
  "success": true,
  "data": {
    "connected": true,
    "migrationsApplied": 10,
    "migrationsPending": 0,
    "migrationsFailed": 0,
    "driftDetected": false,
    "driftCount": 0,
    "riskLevel": "low",
    "healthScore": 100,
    "deploymentReadiness": {
      "status": "ready",
      "score": 100,
      "summary": "Ready for deployment",
      "checks": []
    },
    "provider": "postgresql",
    "schemaPath": "prisma/schema.prisma",
    "packageManager": "npm",
    "hasDatabaseUrl": true
  }
}

Endpoint	Purpose
GET /health	Unauthenticated process health for local monitors.
GET /api/status	Project health, drift, risk, readiness, and detected metadata.
GET /api/plan	Deployment decision, blockers, priority actions, and commands.
GET /api/migrations?page=1&limit=20	Paginated migration timeline.
GET /api/migrations/:name	Single migration SQL, risk score, and details.
GET /api/drift	Cached drift result, refreshed every 10 seconds.
POST /api/drift/check	Force a fresh drift check.
GET /api/risks	Risk score for every migration.
GET /api/risks/:migration	Risk score for one migration.
GET /api/simulate/:migration	Static or shadow simulation result.
GET /api/schema	Parsed models, fields, relations, enums, indexes, and constraints.
GET /api/diff?breaking=true	Schema/database diff used by advanced tooling.
GET /api/rollback/:migration?format=sql	Rollback plan or SQL download.
GET /api/repair	Drift repair suggestions.
POST /api/repair/apply	Apply automated repair steps. Review before use.
GET /api/compare	Environment comparison when at least two environments are configured.
GET /api/git	Migration git metadata, conflicts, and uncommitted migration files.
GET /api/audit?limit=100	Local audit log entries from `.prismaflow/audit.jsonl`.
GET /api/config	Resolved non-sensitive configuration.
GET /api/events	Local server-sent events stream.

Configuration

PrismaFlow works with zero configuration. Use `prisma-flow init` only when you want local defaults checked into your project.

prismaflow.config.ts

import type { PrismaFlowConfig } from 'prisma-flow'
export default {
  port: 5555,
  logLevel: 'info',
  openBrowser: true,
  features: {
    riskAnalysis: true,
    simulation: true,
    ciAnnotations: true,
  },
  environments: [],
  riskThreshold: 'medium',
} satisfies PrismaFlowConfig

Setting	Default	Notes
port	`5555`	Dashboard/API port. Override with `PRISMAFLOW_PORT`.
logLevel	`info`	`trace`, `debug`, `info`, `warn`, or `error`. Override with `PRISMAFLOW_LOG_LEVEL`.
openBrowser	`true`	Set `PRISMAFLOW_NO_OPEN=1` to disable auto-open.
features.riskAnalysis	`true`	Enable migration risk scoring.
features.simulation	`true`	Enable migration simulation.
features.ciAnnotations	`true`	Keep CI output structured for annotations.
environments	`[]`	Named database URLs for `compare`; not shown in the V1 dashboard.
riskThreshold	`medium`	Default warning threshold. Override with `PRISMAFLOW_RISK_THRESHOLD`.

Security

PrismaFlow runs locally and does not require an account or cloud service.
The dashboard API requires a per-session token with 192 bits of entropy.
CORS accepts localhost and same-origin browser requests only.
Child processes use argument arrays instead of shell-built commands.
Database URLs, schema files, SQL, and project paths stay local by default.
Usage telemetry is disabled unless `PRISMAFLOW_TELEMETRY=on` is set.

Troubleshooting

No Prisma project found

Run PrismaFlow from the directory containing prisma/schema.prisma or a package that owns that schema.

Prisma CLI unavailable

Install Prisma in the project or run npm install before drift, status, check, simulate, or report commands.

Database unreachable

Check DATABASE_URL, local database availability, credentials, and network access before running drift or readiness checks.

Dashboard token rejected

Open the URL printed by the current prisma-flow process. Tokens are regenerated every time the server starts.

Dashboard port in use

Start the dashboard with a different port: prisma-flow dashboard --port 7777.

Slow drift checks

Drift detection calls Prisma migrate diff. Large schemas and remote databases can take longer.

Documentation

Overview

Architecture

V1 Scope

Included

Not included yet

Installation

CLI Reference

Command Matrix

Core Workflow

Analysis and Safety

Advanced Local Utilities

Dashboard

Reports and CI

API Reference

Configuration

Security

Troubleshooting

No Prisma project found

Prisma CLI unavailable

Database unreachable

Dashboard token rejected

Dashboard port in use

Slow drift checks