Stop 08 · ORMs & Query BuildersTopics · 8/10

Migrations with ORMs

In short

Change the schema, run one command, and the ORM writes the migration SQL for you. Very handy, but you still need to read what it generated.

Using your ORM's built-in migration tooling to version-control schema changes, instead of managing raw SQL migration scripts by hand.

The blob marks a new entry in a thick scorebook beside a cricket pitch.

Think of it like this

The cricket scorer's book

The scorer writes down every ball, in order, as it happens. Miss one and the final score is wrong. Anyone can replay the book to see how the innings went. ORM migrations do this for your schema: every change, in order, replayable on any database.

Watch it happen

Adding a phone column safely

Edit schema

Generate

Review SQL

Commit

Deploy

1/5Add phone String? to the User model in schema.prisma.

The big ideas

What you need to know

Generated from diffs

The ORM compares your schema with the last known state and writes the SQL difference.

Always read the SQL

A rename can look like a drop plus an add, which loses data. Fix the SQL before committing.

Dev vs deploy commands

migrate dev is for your laptop and may reset data. migrate deploy is the safe one for production.

Same idea everywhere

TypeORM, sequelize-cli and Knex each have their own migration commands built on the same idea.

See it in code

Walk through the code

bash

1# Prisma2npx prisma migrate dev --name add_phone   # local: create + apply3npx prisma migrate deploy                 # CI/production: apply pending4 5# TypeORM (TypeScript data source)6npx typeorm-ts-node-commonjs migration:generate src/migrations/AddPhone -d src/data-source.ts7npx typeorm-ts-node-commonjs migration:run -d src/data-source.ts8 9# Knex10npx knex migrate:make add_phone11npx knex migrate:latest12npx knex migrate:rollback

1/3Prisma: migrate dev on your laptop, migrate deploy in production.

The pattern is the same everywhere: generate or write, review, commit, then apply in order on every environment.

Save yourself the pain

Common mistakes

Oops

Running prisma migrate dev against the production database.

Do this instead

migrate dev can reset the database when it detects drift. Production only ever gets migrate deploy.

Oops

Renaming a field and trusting the generated migration.

Do this instead

Generators often drop the old column and add a new one. Edit the SQL into a RENAME so the data survives.

Your mission

Rename without losing data

~25 min

Quick check

Which Prisma command should your production deploy pipeline run?

Go deeper

1Add a field to a model and generate the corresponding migration with your ORM's CLI.
2Learn how to review a generated migration before running it in production.
3Practice rolling back a migration and understand what could go wrong doing so on live data.