Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 36 ยท Migrations

The Prisma Migrate Workflow

Learn how Prisma Migrate turns schema changes into SQL migration files, how migrate dev and migrate deploy differ, and what the _prisma_migrations table records.

Your Prisma schema describes what the database should look like. The database, however, already exists and holds real data. Prisma Migrate closes that gap: it compares your schema with the database, writes the SQL needed to move from one to the other, saves that SQL as a file in your project, and applies it. Because every change becomes a file, your database history lives in Git next to your code, and every teammate and every server can replay it in the same order.

Note: Prisma code needs the npm package prisma and a real database, and the in-browser runner here has neither. So the Prisma commands and schema in this track are read-only snippets, and the runnable examples are small stand-ins that use Node's built-in node:sqlite to demonstrate the same ideas (ordered SQL files, checksums, history tables). Each stand-in is labelled. The behavior described for Prisma matches Prisma 7.

The mental model

A migration is a folder with a timestamped name and one migration.sql file inside. Prisma applies folders in name order and remembers which ones it ran.

TEXT
prisma/
  schema.prisma
  migrations/
    migration_lock.toml
    20260105101500_init/
      migration.sql
    20260112093000_add_post_published/
      migration.sql

migration_lock.toml records the database provider (for example postgresql). It stops a teammate from accidentally applying PostgreSQL SQL to a SQLite database. Commit it.

flowchart LR
  A["Edit schema.prisma"] --> B["prisma migrate dev --name change"]
  B --> C["SQL file created in migrations/"]
  C --> D["SQL applied to dev database"]
  D --> E["Commit schema + migration folder"]
  E --> F["prisma migrate deploy in CI / production"]

The schema file is the source of truth for the next change; the migration folders are the source of truth for the history.

migrate dev: the development command

Terminal
npx prisma migrate dev --name add_post_published

In development this one command does several things:

  1. Replays existing migrations against a temporary shadow database to learn what your history currently produces.
  2. Compares that result with your schema.prisma and works out the difference.
  3. Writes the difference as a new migration.sql in a new folder named <timestamp>_<name>.
  4. Applies any pending migrations to your development database and records them.

In Prisma 7, migrate dev no longer runs prisma generate or your seed script by itself; run npx prisma generate (and npx prisma db seed if you want data) as separate steps. If your database was created by other means and no longer matches your history, migrate dev stops and offers to reset it, which deletes all data. That is fine on a laptop and unacceptable in production, which is why production uses a different command.

migrate deploy: the production command

Terminal
npx prisma migrate deploy

deploy never creates migrations, never resets, and never uses a shadow database. It looks at the history table, finds folders that have not been applied, applies them in order, and exits. It is safe to run in a CI/CD pipeline on every release, and running it twice does nothing the second time. Later lessons cover deployment in detail.

The history table

Prisma creates a table named _prisma_migrations in your database. One row per migration holds the folder name, a checksum (a SHA-256 hash of the SQL file), start and finish timestamps, and how many steps were applied. The checksum is why you must not edit a migration that has already been applied elsewhere: the next run notices the file no longer matches what was recorded and reports it as modified.

Inspect the state any time:

Terminal
npx prisma migrate status

It tells you whether the database is up to date, which migrations are pending, and whether any applied migration is missing locally or was changed.

A runnable stand-in

This first TryIt is not Prisma. It is a 30-line imitation of the core algorithm: take SQL files in name order, skip those already recorded, run the rest, store a checksum.

Node.js Stand-in: apply ordered migrations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Run it and notice the third call is a no-op. That is exactly why migrate deploy is safe to run on every release.

What happens when someone edits an applied migration

Edit one character of an applied file and Prisma's checksum comparison fails. Here is the same idea in the stand-in, with the error you would see reported as a modified migration.

Node.js Stand-in: detect an edited migration

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The fix is never "edit the old file". Add a new migration that makes the change you want. Rewriting history is only acceptable for a migration that nobody has applied yet.

Common mistakes

  • Running migrate dev against production. It can reset data. Use migrate deploy there.
  • Forgetting to commit the migration folder. Teammates then get an empty history and a drifting schema.
  • Editing applied migrations. Add a new one instead.
  • Mixing db push and migrations on the same database without understanding the difference.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command applies pending migrations in production without creating new ones?

    migrate deploy only applies unapplied migration folders in order. It never creates migrations, never resets and needs no shadow database.
  2. 2. What is the purpose of the checksum stored in the _prisma_migrations table?

    Prisma hashes each migration.sql. If the file's hash no longer matches the recorded one, the migration was modified after being applied.
  3. 3. Why does migrate dev use a shadow database?

    The shadow database is a temporary copy built from your migration history, used to work out what SQL is needed to reach the current schema.
  4. 4. A migration already applied on your teammates' machines has a typo in a column default. What should you do?

    History is append-only. A new migration fixes the problem on every machine without breaking checksums.

Summary

  • Prisma Migrate stores every schema change as a timestamped folder with a migration.sql file.
  • migrate dev is for development: it uses a shadow database, creates migrations and may offer to reset.
  • migrate deploy is for CI and production: it only applies pending migrations.
  • _prisma_migrations records each applied migration with a checksum, so edits to applied files are caught.
  • The runnable examples here are stand-ins built on node:sqlite; real Prisma commands are read-only.

Next: Migration Files, Customizing SQL and Drift