Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Migrations

Why You Need Migrations

Learn why schema migrations exist, what a migration table records, and how up and down steps keep every environment on the same database structure.

Your entities and models describe the shape of your data, but a real database does not magically take that shape. Someone has to create the tables, add the columns and build the indexes, and they have to do it the same way on your laptop, on the test server and in production. A migration is a small, versioned script that moves a database from one schema version to the next.

Both TypeORM and Sequelize have a "synchronize" shortcut that makes the database match your code automatically. It is wonderful while you prototype and dangerous afterwards. In this lesson you will see why migrations replace that shortcut, and you will build a tiny migration runner so the idea is concrete before we meet the real tools.

Honest note. TypeORM and Sequelize are npm packages, and the lesson runner has no npm. The ts and js blocks that import them are read-only. The runnable examples use Node's built-in node:sqlite and a hand-written stand-in that behaves like the real migration tools. Every stand-in is labelled.

The problem with auto-sync

Imagine you rename the name column of User to fullName. Auto-sync compares the new entity to the table and sees one column that disappeared and one that is new. The safe-looking result is: drop name, add fullName. Every stored name is gone.

TypeScript
// TypeORM: convenient in a throwaway demo, risky anywhere else
new DataSource({
  type: 'postgres',
  synchronize: true, // never leave this on in production
  entities: [User],
});

Sequelize has the same trap with sequelize.sync({ alter: true }). A migration lets you say what you actually mean: "rename this column and keep the data".

What a migration is

A migration has two halves:

  • up: apply the change (create a table, add a column).
  • down: undo it, so you can roll back a bad release.

Migrations run in a fixed order, usually by a timestamp or number in the file name. The runner keeps a small table in the database (TypeORM calls it migrations, Sequelize calls it SequelizeMeta) that lists which migrations already ran. When you deploy, the runner compares the list of files with the table and runs only what is missing.

flowchart LR
  A["Files on disk<br/>001, 002, 003"] --> C{"Runner compares"}
  B["Migrations table<br/>001, 002"] --> C
  C --> D["Runs 003 only"]
  D --> E["Records 003"]

The runner applies only the migrations that are not recorded yet.

A runnable migration runner

The stand-in below is about twenty lines. It is not TypeORM or Sequelize, but it follows the same contract: ordered files, up/down, and a bookkeeping table.

Node.js A tiny migration runner (stand-in)

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 second call prints nothing: both names are already in the table, so the runner skips them. That is idempotence at the migration level, and it is what makes deploys safe to repeat.

Rolling back

A rollback runs the down of the most recent migration and removes its row. Add that to the runner and watch the schema shrink.

Node.js Reverting the last migration (stand-in)

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.

Rules that keep migrations trustworthy

  1. Never edit a migration that has already run somewhere. Add a new one. Other databases recorded the old version as done and will never see your edit.
  2. Commit migrations with the code that needs them. A feature branch carries its schema change.
  3. Write a real down when you can. Some changes (dropping a column) cannot restore data, so say so in a comment.
  4. Run the same migrations everywhere, including your test database.
  5. Review the SQL. A generated migration is a draft, not a verdict.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the migrations table record?

    The runner compares migration files with this table and runs only the ones that are missing.
  2. 2. Why is synchronize: true risky in production?

    Auto-sync diffs the schema and cannot know that two different column names mean the same data.
  3. 3. You find a typo in a migration that already ran in production. What is the right fix?

    Applied migrations are history. Fixes go forward as new migrations.
  4. 4. What is the job of the down function?

    down reverses up, although some changes such as dropping a column cannot bring data back.

Summary

  • Migrations are ordered, versioned scripts with up and down.
  • A bookkeeping table records what has run, so deploys apply only the new ones.
  • Auto-sync is for prototypes; use migrations for anything with real data.
  • Never edit an applied migration: add a new one.

Next: Migrations in TypeORM