Database Migrations with Prisma Migrate

Prisma Migrate is a database migration tool built into the Prisma CLI. It maps changes in your schema.prisma file directly to SQL scripts, keeping your database schema synchronized with your application models.

1. What is a Migration?

A migration is a version-controlled step that updates your database schema structure (for example, creating a new table, adding columns, or setting index rules).

Using a migration tool ensures that:

• Database schemas remain consistent across different developer environments.
• Schema changes can be tested and rolled back if needed.
• Changes are tracked historically as SQL files in version control.

2. Generating Migrations in Development

When you modify your schema.prisma file during local development, use the migrate dev command to sync your database:

# Run migration in development mode
npx prisma migrate dev --name init_users_table

This command triggers a set of actions:

1. Compares your schema file against the active database state.
2. Generates a SQL migration file inside prisma/migrations/.
3. Executes the SQL script on your local development database.
4. Triggers client generation (prisma generate) so your TypeScript types match the updated structure.

3. Deploying Migrations to Production

In staging or production environments, you should never run prisma migrate dev because it scans for changes and can reset database tables if they do not match.

Instead, run the migrate deploy command during your build or deployment phase:

# Deploy pending migrations safely to production
npx prisma migrate deploy

This command reads the migrations history and executes any pending SQL scripts on the target production database without modifying or resetting existing data.