Sequelize Migrations: Version Control for Your Database

WHY IT EXISTS In any project with multiple developers or deployment environments (dev, staging, production), keeping the database schema synchronized is a major challenge. Manually running SQL scripts is error-prone and impossible to version control. Migrations solve this by treating schema changes as code.

THE MENTAL MODEL A migration is like a commit in Git, but for your database structure. Each migration is a file containing two functions: up to apply a change (like adding a table) and down to revert it. The Sequelize Command-Line Interface (CLI) acts as your Git client, applying these commits in order to bring any database to the desired state.

HOW IT WORKS The process is managed by the sequelize-cli. First, you run npx sequelize-cli init to create the necessary folders: config, models, migrations, and seeders. You then configure your database connection in config/config.json. To create a new table, you run a command like npx sequelize-cli model:generate. This creates both a model file for your application code and a timestamped migration file. This migration file contains the up and down logic using Sequelize's queryInterface. Finally, you run npx sequelize-cli db:migrate to execute the up function on all pending migrations. Sequelize tracks which migrations have already been applied in a special SequelizeMeta table in your database.

WHEN TO USE IT Use migrations for every single change to your database schema. This includes creating or dropping tables, adding or removing columns, creating indexes, or modifying constraints. It is the standard, non-negotiable way to manage database evolution in a professional Node.js project using Sequelize.

WHEN NOT TO USE IT Migrations are for schema, not for data. While you can insert data in a migration, it's an anti-pattern; use seeders for populating tables with initial or test data. The biggest footgun is editing a migration file after it has been run and pushed to a shared branch. This is like rewriting Git history and will cause chaos. If you make a mistake, create a new migration to fix it.

ONE CANONICAL EXAMPLE To create a User table, you run npx sequelize-cli model:generate --name User --attributes firstName:string,email:string. This generates a migration file. The up function in that file will contain await queryInterface.createTable('Users', { ... }) defining the columns. The down function will contain await queryInterface.dropTable('Users');. This file is now a permanent, executable record of that specific schema change.