Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท Migrations

Migrations in Sequelize

Use sequelize-cli to create, run and undo migrations, write queryInterface steps, track state in SequelizeMeta and add seed files for starter data.

Sequelize keeps migrations separate from your models. A migration is a plain JavaScript module that exports up and down functions. Each receives a queryInterface, an object with methods for creating tables, adding columns and running raw SQL, and the Sequelize class for data types. A command-line tool, sequelize-cli, creates the files and runs them.

The packages are not available in the lesson runner, so Sequelize code is read-only here. The runnable examples use node:sqlite with a stand-in that mimics queryInterface and the SequelizeMeta table.

Project setup

Terminal
npm install --save-dev sequelize-cli
npx sequelize-cli init

init creates four folders: config/ (connection settings per environment), models/, migrations/ and seeders/. A .sequelizerc file can move them if you prefer a different layout.

The CLI commands

Command Purpose
npx sequelize-cli migration:generate --name add-email Creates an empty timestamped file
npx sequelize-cli db:migrate Runs all pending migrations
npx sequelize-cli db:migrate:status Shows up or down per file
npx sequelize-cli db:migrate:undo Reverts the latest migration
npx sequelize-cli db:migrate:undo:all Reverts everything
npx sequelize-cli db:migrate --to 20250101-add-email.js Migrates up to a given file

Applied names are stored in a table called SequelizeMeta, one row per file name.

Writing a migration

JavaScript
// migrations/20250101120000-create-users.js
'use strict';

module.exports = {
  async up(queryInterface, Sequelize) {
    await queryInterface.createTable('Users', {
      id: { type: Sequelize.INTEGER, primaryKey: true, autoIncrement: true },
      name: { type: Sequelize.STRING(120), allowNull: false },
      createdAt: { type: Sequelize.DATE, allowNull: false },
      updatedAt: { type: Sequelize.DATE, allowNull: false },
    });
    await queryInterface.addIndex('Users', ['name']);
  },

  async down(queryInterface) {
    await queryInterface.dropTable('Users');
  },
};

Note that the migration lists every column by hand. It does not read your model. That is deliberate: the model can change next month, and this file must still describe the table as it was on this day.

Useful queryInterface methods: addColumn, removeColumn, changeColumn, renameColumn, renameTable, addIndex, removeIndex, addConstraint, bulkInsert, bulkDelete and sequelize.query for raw SQL.

Transactions inside a migration

On databases with transactional DDL, wrap multi-step migrations so they succeed or fail as a unit.

JavaScript
async up(queryInterface, Sequelize) {
  await queryInterface.sequelize.transaction(async (transaction) => {
    await queryInterface.addColumn('Users', 'email', { type: Sequelize.STRING }, { transaction });
    await queryInterface.addIndex('Users', ['email'], { unique: true, transaction });
  });
}

A runnable stand-in

This stand-in loads migration objects, records them in SequelizeMeta, and offers migrate and undo. The queryInterface is a thin wrapper over SQLite, so the SQL is real.

Node.js A mini sequelize-cli (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.

Seeders

Seed files fill tables with starter data, such as roles, countries or a demo admin. They look like migrations but use bulkInsert and bulkDelete.

JavaScript
// seeders/20250101-demo-users.js
module.exports = {
  async up(queryInterface) {
    await queryInterface.bulkInsert('Users', [
      { name: 'Ada', createdAt: new Date(), updatedAt: new Date() },
    ]);
  },
  async down(queryInterface) {
    await queryInterface.bulkDelete('Users', { name: 'Ada' });
  },
};

Run them with npx sequelize-cli db:seed:all. Seeders are tracked only if you configure seederStorage, so write them to be safe to run twice (or run them only on fresh databases).

Comparing with TypeORM

Sequelize has no built-in "diff my models" generator. You write each migration yourself, which is more typing but also means the SQL always reflects a decision you made. TypeORM's migration:generate gives a faster first draft and needs a more careful review. See Migrations in TypeORM for that side.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which table does sequelize-cli use to record applied migrations?

    SequelizeMeta holds one row per migration file name that has run.
  2. 2. Why does a migration list columns by hand instead of reading the model?

    A migration is frozen history; coupling it to a living model would change its meaning.
  3. 3. Which command reverts the latest migration?

    db:migrate:undo runs down for the most recent file and removes its row.
  4. 4. What is a seeder for?

    Seeders populate tables; they do not change the schema.

Summary

  • A Sequelize migration exports up(queryInterface, Sequelize) and down.
  • sequelize-cli creates, runs, reports and undoes migrations and tracks them in SequelizeMeta.
  • Write columns explicitly; never depend on the current model.
  • Use transactions for multi-step changes where the database supports transactional DDL.
  • Seeders add starter data and have their own up and down.

Next: Safe Schema Changes in Production