3.5.7. Migrations

In this chapter, you'll learn what a migration is and how to generate a migration or write it manually.

What is a Migration?#

A migration is a TypeScript or JavaScript file that defines database changes made by a module. Migrations are useful when you re-use a module or you're working in a team, so that when one member of a team makes a database change, everyone else can reflect it on their side by running the migrations.

The migration's file has a class with two methods:

• The up method reflects changes on the database.
• The down method reverts the changes made in the up method.

Generate Migration#

Instead of you writing the migration manually, the Medusa CLI tool provides a db:generate command to generate a migration for a modules' data models.

For example, assuming you have a blog Module, you can generate a migration for it by running the following command:

Terminal
❯npx medusa db:generate blog

This generates a migration file under the migrations directory of the Blog Module. You can then run it to reflect the changes in the database as mentioned in this section.

Write a Migration Manually#

You can also write migrations manually. To do that, create a file in the migrations directory of the module and in it, a class that has an up and down method. The class's name should be of the format Migration{YEAR}{MONTH}{DAY}{HOUR}{MINUTE}.ts to ensure migrations are ran in the correct order.

For example:

src/modules/blog/migrations/Migration202507021059.ts
1import { Migration } from "@mikro-orm/migrations"2
3export class Migration202507021059 extends Migration {4
5  async up(): Promise<void> {6    this.addSql("create table if not exists \"author\" (\"id\" text not null, \"name\" text not null, \"created_at\" timestamptz not null default now(), \"updated_at\" timestamptz not null default now(), \"deleted_at\" timestamptz null, constraint \"author_pkey\" primary key (\"id\"));")7  }8
9  async down(): Promise<void> {10    this.addSql("drop table if exists \"author\" cascade;")11  }12
13}

The migration class in the file extends the Migration class imported from @mikro-orm/migrations. In the up and down method of the migration class, you use the addSql method provided by MikroORM's Migration class to run PostgreSQL syntax.

In the example above, the up method creates the table author, and the down method drops the table if the migration is reverted.

Run the Migration#

To run your migration, run the following command:

Terminal
❯npx medusa db:migrate

This reflects the changes in the database as implemented in the migration's up method.

Rollback the Migration#

To rollback or revert the last migration you ran for a module, run the following command:

Terminal
❯npx medusa db:rollback blog

This rolls back the last ran migration on the Blog Module.

Caution: Rollback Migration before Deleting#

If you need to delete a migration file, make sure to rollback the migration first. Otherwise, you might encounter issues when generating and running new migrations.

For example, if you delete the migration of the Blog Module, then try to create a new one, Medusa will create a brand new migration that re-creates the tables or indices. If those are still in the database, you might encounter errors.

So, always rollback the migration before deleting it.

More Database Commands#

To learn more about the Medusa CLI's database commands, refer to this CLI reference.