How to evolve a database schema with Prisma Migrate

What and why

Prisma Migrate generates SQL migration files from your declarative schema.prisma and keeps a migration history the database can track. It gives Node.js and TypeScript teams a typed ORM plus reproducible schema evolution in one toolchain.

Prerequisites

• A Node.js project with npm, pnpm, or yarn.
• A relational database URL (PostgreSQL, MySQL, SQLite, etc.).
• Basic familiarity with the Prisma schema language.

Steps

1. Install Prisma

npm install prisma --save-dev
npx prisma init

This creates prisma/schema.prisma and a .env with DATABASE_URL.

2. Define the data model

Edit schema.prisma:

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

3. Create a dev migration

npx prisma migrate dev --name init

This generates a timestamped folder under prisma/migrations/, applies it to the dev database, and regenerates the typed client.

4. Inspect the SQL

Open prisma/migrations/<timestamp>_init/migration.sql and confirm the generated DDL. Prisma writes plain SQL, so you can review exactly what will run and edit it for cases Prisma cannot infer.

5. Deploy to production

In CI or on the server, never use migrate dev. Apply committed migrations with:

npx prisma migrate deploy

This applies pending migrations only and does not reset data.

6. Resolve drift

If the database schema no longer matches the migration history, Prisma reports drift. Inspect with npx prisma migrate status. For a controlled fix, mark a migration as applied with npx prisma migrate resolve --applied <name> or, in dev only, reset with npx prisma migrate reset.

Verification

Run npx prisma migrate status; it should show the database is up to date. Use npx prisma studio or a SQL client to confirm tables and columns. The generated client should expose the new model with full types.

Next Steps

Add prisma migrate deploy to your deployment step, keep migration files in version control, and use shadow-database checks in CI to catch invalid migrations early.