# Checklist for Reviewing AI-Generated Prisma Migrations

> A human review checklist for Prisma schema changes and migrations written by AI coding agents — data loss, locking, and irreversible operations.

**Type:** Checklist  
**Tools:** Cursor, Claude Code, Codex, Windsurf  
**Stack:** PostgreSQL, TypeScript  
**Updated:** 2026-06-08

---

Prisma migrations run automatically on deploy and can drop columns, rewrite large tables, or take exclusive locks. AI generates migration SQL that looks correct but can cause downtime or silent data loss.

## Correctness

```txt
[ ] Migration SQL in prisma/migrations/ matches the schema.prisma diff exactly
[ ] No manually edited migration files — Prisma tracks checksums and will reject them
[ ] New required fields have a @default value or the migration includes a backfill step
[ ] Renamed fields generate two migrations: add new, migrate data, drop old — not a direct rename
[ ] Enums added to PostgreSQL are append-only — removing a value requires a separate process
[ ] Relation fields have the correct onDelete behavior (Cascade, Restrict, SetNull) defined
[ ] @unique constraints are intentional — they create indexes and reject duplicates
[ ] @@index and @@unique on composite fields have columns in the right order for query patterns
[ ] prisma migrate diff output is reviewed before applying in production
[ ] Shadow database connection string is configured for CI environments
[ ] Prisma Client is regenerated after every schema change before running tests
[ ] Model names are PascalCase; field names are camelCase — Prisma maps to snake_case in SQL
```

## Data Safety

```txt
[ ] No DROP COLUMN on a column that still has application code reading it (blue-green safe)
[ ] No DROP TABLE without confirming all application references are removed
[ ] Backfills for new non-nullable columns run before the NOT NULL constraint is added
[ ] Large backfills are batched — not a single UPDATE on millions of rows
[ ] Cascade deletes are intentional and tested — not the default chosen to silence a Prisma error
[ ] Migration does not truncate a table that should retain historical data
[ ] @default(now()) on a field that was previously nullable sets correct values on existing rows
[ ] Schema change is backward compatible with the previous deployed application version
```

## Performance

```txt
[ ] Adding an index on a large table uses CONCURRENTLY — Prisma does not do this by default
[ ] Adding NOT NULL to an existing column without a default causes a full table rewrite in older Postgres
[ ] New foreign key constraints use DEFERRABLE INITIALLY DEFERRED if adding to populated tables
[ ] Migration run time is estimated — tables over 1M rows need a maintenance window or zero-downtime strategy
[ ] No multiple expensive migrations chained in a single deploy
[ ] @db.Text on columns that should be VARCHAR — unbounded text disables some index strategies
[ ] @@index is added for every foreign key that will be used in a JOIN or WHERE filter
```

## Deployment

```txt
[ ] prisma migrate deploy (not dev) is used in the production deploy script
[ ] DATABASE_URL in production points to the primary/writer replica, not a read replica
[ ] Migration is tested against a staging database with production-scale data before production deploy
[ ] Rollback plan exists — document which migrations are reversible and how
[ ] prisma db push is not used in production — it bypasses the migration history
[ ] CI runs prisma migrate diff to detect schema drift before merging
[ ] Database user running migrations has ALTER TABLE privileges but application user does not
```

## AI-Specific Risks

```txt
[ ] AI has not used prisma.$queryRaw without the Prisma.sql tagged template (SQL injection risk)
[ ] AI has not fabricated Prisma schema attributes — verify each @attribute exists in the Prisma docs
[ ] AI has not added @@map or @map incorrectly — this changes the actual table or column name
[ ] AI-generated schema uses the correct provider (postgresql, mysql, sqlite) — not a mix
[ ] AI has not assumed that prisma migrate dev auto-applies in CI — it requires --skip-generate in some setups
[ ] AI has not used deprecated Prisma v2 syntax in a v5+ project
[ ] AI has not generated a migration that includes the full table recreate when only an index was requested
```

## Fix Prompt

```txt title="Fix Prompt"
Review this Prisma schema change and the generated migration SQL against the
checklist above. Identify any data loss risks, missing defaults, blocking
index additions, or fabricated schema attributes. Produce a corrected schema
and a safe zero-downtime migration strategy, including any intermediate steps
needed to add NOT NULL constraints or backfill data.
```