Plainform | Migrations

Prisma Migrate manages your database schema changes through migration files stored in prisma/migrations. Each migration represents a set of changes to your database structure.

Development Workflow

Modify Your Schema

Update prisma/schema.prisma with your changes:

prisma/schema.prisma

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String
  authorId  String
  createdAt DateTime @default(now())
  
  @@index([authorId])
}

Create Migration

Generate and apply the migration:

Terminal

npx prisma migrate dev --name add_post_model

This creates a migration file, applies it to your database, and regenerates Prisma Client.

Commit Migration

Add the migration to version control:

Terminal

git add prisma/migrations
git commit -m "feat: add post model"

Migration Commands

Development

Terminal

# Create and apply migration
npx prisma migrate dev --name migration_name

# Create migration without applying
npx prisma migrate dev --create-only

# Apply pending migrations
npx prisma migrate dev

Production

Terminal

# Apply all pending migrations
npx prisma migrate deploy

# Check migration status
npx prisma migrate status

Use migrate dev in development and migrate deploy in production. Never use migrate dev in production.

Included Supabase RLS Migration

Plainform ships with a migration that configures Supabase grants and Row Level Security policies for the default tables. When users run:

Development

npx prisma migrate dev

or in production:

Production

npx prisma migrate deploy

Prisma applies those policies alongside the table schema.

The default policy behavior is:

Event is readable with the Supabase publishable key
Event writes require the Supabase secret key or Prisma-backed server code
User has RLS enabled and no public read/write policies
User remains readable/writable by Prisma-backed backend routes and webhooks

RLS policies apply to Supabase API access, not normal Prisma queries. Existing Clerk webhooks, Stripe webhooks, and API routes that use Prisma continue to work through DATABASE_URL.

Reset Database

Terminal

# Drop database, recreate, and apply all migrations
npx prisma migrate reset

migrate reset deletes all data. Only use in development or with backups.

Common Scenarios

Adding a Field

prisma/schema.prisma

model Event {
  id        String   @id @default(cuid())
  type      String
  slug      String
  text      String
  timestamp BigInt
  views     Int      @default(0)  // New field
}

Terminal

npx prisma migrate dev --name add_views_field

Adding a Relationship

prisma/schema.prisma

model Post {
  id       String    @id @default(cuid())
  title    String
  authorId String
  author   User      @relation(fields: [authorId], references: [id])
  
  @@index([authorId])
}

model User {
  id    String @id @default(cuid())
  name  String
  posts Post[]
}

Terminal

npx prisma migrate dev --name add_post_author_relation

Renaming a Field

prisma/schema.prisma

model Event {
  id          String @id @default(cuid())
  description String  // Renamed from 'text'
  timestamp   BigInt
}

Terminal

npx prisma migrate dev --name rename_text_to_description

Prisma detects renames as drop + create. To preserve data, manually edit the migration SQL to use ALTER TABLE ... RENAME COLUMN.

Production Deployment

Vercel

Add to your build command:

package.json

{
  "scripts": {
    "build": "prisma migrate deploy && next build"
  }
}

Or set in Vercel dashboard:

Build Command: prisma migrate deploy && npm run build

Environment Variables

Ensure production has both connection strings:

Production .env

DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."

Best Practices

Descriptive Names

Terminal

# ✅ Good
npx prisma migrate dev --name add_user_email_verification

# ❌ Bad
npx prisma migrate dev --name update

Small Migrations

Terminal

# ✅ Good - one change per migration
npx prisma migrate dev --name add_post_title_field
npx prisma migrate dev --name add_post_content_field

# ❌ Bad - too many changes
npx prisma migrate dev --name add_entire_blog_system

Review Generated SQL

Terminal

# Create without applying
npx prisma migrate dev --create-only --name your_migration

# Review SQL in prisma/migrations/[timestamp]_your_migration/migration.sql

# Apply if looks good
npx prisma migrate dev

Next Steps

Usage & Integration - Use Prisma Client in your code
Troubleshooting - Resolve migration issues
Prisma Migrate Docs - Complete reference

Migrations

On this page