Plainform

Learn how to run database migrations safely in production.

Goal

By the end of this recipe, you'll know how to create and apply database migrations in production.

Prerequisites

A working Plainform installation
Prisma configured
Production database access

Steps

Create Migration Locally

Create a migration for your schema changes:

npx prisma migrate dev --name add_new_field

This creates a migration file in prisma/migrations/.

Always test migrations locally before applying to production.

Commit Migration Files

Commit the migration files to Git:

git add prisma/migrations/
git commit -m "feat: add new database field"
git push origin main

Apply Migration in Production

After deployment, run the migration:

Option 1: Automatic (Recommended)

Add to your package.json:

package.json

{
  "scripts": {
    "postinstall": "prisma generate && prisma migrate deploy"
  }
}

Vercel will run migrations automatically on each deployment.

Option 2: Manual

Run manually via Vercel CLI:

vercel env pull .env.production
npx prisma migrate deploy

Verify Migration

Check that the migration applied successfully:

npx prisma studio

Or query your database directly to verify schema changes.

Migration Best Practices

Before Running Migrations

Backup your database before major schema changes
Test locally with production-like data
Review SQL in migration files for correctness

Safe Migration Patterns

Adding columns:

model User {
  id    String @id
  email String
  name  String? // Make new fields optional initially
}

Renaming columns:

Add new column
Copy data from old to new
Remove old column (in separate migration)

Dropping columns:

Remove from application code first
Deploy application
Drop column in separate migration

Avoid breaking changes in migrations. Add new fields as optional, then make required in a later migration.

Common Issues

Migration Fails in Production

Check database connection string
Verify database user has migration permissions
Review migration SQL for syntax errors

Schema Out of Sync

Reset and reapply migrations:

npx prisma migrate reset
npx prisma migrate deploy

migrate reset drops all data. Only use in development.

Migration Conflicts

If multiple developers create migrations:

npx prisma migrate resolve --applied <migration_name>

Rollback Strategy

To rollback a migration:

Revert the migration commit in Git
Create a new migration that undoes changes
Deploy the rollback migration

Prisma doesn't support automatic rollbacks. Always create a new migration to undo changes.

Next Steps

Deploy Vercel - Deploy your application

Prisma Migrations - Complete migration guide
Prisma Deploy - Production migration docs

Database Migrations