Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 36 ยท Migrations

db push, db pull and Baselining

Know when to use prisma db push for prototyping, db pull to introspect an existing database, and how to baseline production so Prisma Migrate can take over safely.

Prisma Migrate is not the only way to line a schema and a database up. Two other commands matter in daily work: db push for fast prototyping and db pull for reading an existing database into a schema. This lesson explains when each is right, and how to baseline a database that already exists so that Migrate can start managing it.

All Prisma commands here are read-only snippets. The runnable examples are labelled stand-ins on node:sqlite.

db push: schema straight to database

Terminal
npx prisma db push

db push computes the difference between schema.prisma and the database and applies it immediately. It creates no migration file and no history. It is ideal when you are experimenting: change a model, push, look at the result, change again, and never worry about a trail of tiny migrations.

If the change could lose data (dropping a column, narrowing a type) it stops and asks for --accept-data-loss. It also never uses a shadow database.

migrate dev db push
Creates migration files Yes No
Keeps history for production Yes No
Needs shadow database Yes No
Best for Real projects Prototypes, throwaway databases

The rule of thumb: once the schema must reach another machine or production, switch to migrations. A common pattern is to prototype with db push, then run migrate dev --name init once the model settles. Because the first migration will describe the whole schema, run it against a fresh database or reset the prototype one.

db pull: database to schema

Terminal
npx prisma db pull

This is introspection. Prisma reads tables, columns, keys, indexes and relations from a live database and writes matching model blocks into schema.prisma. Use it when you inherit a legacy database or when another team owns the database structure.

Introspection is good but not magic. Check the result for:

  • Table names that look awkward in code. Rename the model and map it back with @@map("legacy_table").
  • Columns named in snake_case: keep them with @map("created_at") and expose a createdAt field.
  • Relations Prisma could not infer because the database has no foreign key. Add @relation fields by hand.
  • Types Prisma does not support natively, shown as Unsupported("...").
PRISMA
model BlogPost {
  id        Int      @id @default(autoincrement())
  title     String
  createdAt DateTime @default(now()) @map("created_at")

  @@map("blog_posts")
}

Running db pull again later overwrites parts of the schema with what the database says, so commit first and review the diff.

Node.js Stand-in: introspect a database into model text

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.

Baselining an existing database

You inherit a production database with real data and no migration history. Running migrate dev would try to create tables that already exist. Baselining teaches Prisma "this starting state is already applied".

  1. Run db pull and fix up schema.prisma until it matches the database.
  2. Create the folder prisma/migrations/0_init.
  3. Generate the SQL that would build the current schema from nothing:
Terminal
mkdir -p prisma/migrations/0_init
npx prisma migrate diff \
  --from-empty \
  --to-schema prisma/schema.prisma \
  --script > prisma/migrations/0_init/migration.sql
  1. Tell Prisma the migration is already in place, without running it:
Terminal
npx prisma migrate resolve --applied 0_init

From this point migrate dev and migrate deploy treat the database as managed. The folder name starts with 0_ so it sorts before every later timestamped migration. Every other environment (a fresh developer database, CI) runs 0_init normally, because there it has not been applied.

flowchart TD
  A["Existing database, no history"] --> B["db pull -> schema.prisma"]
  B --> C["migrate diff --from-empty -> 0_init/migration.sql"]
  C --> D["migrate resolve --applied 0_init (production)"]
  D --> E["From now on: migrate dev / migrate deploy"]

Baselining records history; it does not change the production tables.

Node.js Stand-in: baseline marks a migration applied without running it

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.

Without the baseline step, 0_init would have failed with "table already exists".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does prisma db push NOT do?

    db push applies changes directly and leaves no migration history, which is why it suits prototypes only.
  2. 2. When is db pull most useful?

    Introspection reads tables, columns and keys from a live database and writes the matching models.
  3. 3. How do you keep a snake_case column but use a camelCase field in code?

    @map links a field to the database column name; @@map does the same for a model and its table.
  4. 4. What does prisma migrate resolve --applied 0_init do during baselining?

    The tables already exist in production, so Prisma only needs a history row stating that the baseline migration is in place.

Summary

  • db push syncs the schema to a database instantly with no history: use it for prototypes.
  • db pull introspects a database into models; review names, relations and Unsupported types.
  • Use @map and @@map to keep code names tidy while matching existing columns and tables.
  • Baseline an existing database with migrate diff --from-empty, then migrate resolve --applied.
  • After baselining, production uses migrate deploy like any other managed database.

Next: Seeding and Data Migrations