Medusa Database Migrations: Generating, Reviewing and Deploying Safely

Medusa generates migrations from your models, which removes an entire category of tedium and introduces a specific risk: generated SQL that you have not read is SQL you have not agreed to. A rename you did not intend reads to the generator as a drop and an add, and columns do not come back.

The commands

# Generate migrations for one module after changing its models
npx medusa db:generate my_module

# Apply all pending migrations
npx medusa db:migrate

# Create the database if it does not exist
npx medusa db:create

# Drop everything — development only
npx medusa db:rollback

db:generate takes the module name as registered, not the directory path. Core modules manage their own migrations; you never generate for them.

Read what it produced

Change a model:

export const LoyaltyAccount = model.define("loyalty_account", {
  id: model.id().primaryKey(),
  customer_id: model.text().index(),
  points: model.number().default(0),
  tier: model.enum(["bronze", "silver", "gold"]).default("bronze"),
})

Generate, then open the file. What you are checking for:

• +Drops. A DROP COLUMN you did not intend is data loss. If you renamed something, edit the migration to RENAME COLUMN instead.
• +Non-nullable additions without a default. These fail on any table with existing rows.
• +New indexes on large tables. In Postgres, prefer CREATE INDEX CONCURRENTLY, which the generator will not produce for you.
• +Enum changes. Removing a value fails if any row still uses it.

Treat a generated migration as a first draft. Editing it before commit is normal and expected.

Deploying them

As a discrete release step, before new code serves traffic:

{
  "deploy": {
    "preDeployCommand": "npx medusa db:migrate",
    "startCommand": "cd .medusa/server && medusa start"
  }
}

Never at boot. Three instances starting together will run the same migration simultaneously, and the outcomes range from a harmless lock wait to a half-applied schema.

Zero-downtime changes

During a rolling deploy, old and new application code both run against the already-migrated schema. Any migration that breaks the old code causes errors until the rollout finishes.

The pattern is expand and contract, across two releases.

Say you are renaming points to points_balance.

Release 1 — expand.

1. Add points_balance as a nullable column.
2. Deploy code that writes to both and reads from points if points_balance is null.
3. Backfill in a script or job.

Release 2 — contract.

1. Deploy code that reads and writes only points_balance.
2. Drop points in a later migration, once you are confident.

Slower, and it is the difference between a rename and an incident. The rule of thumb: a migration should never break the currently deployed code.

What is safe and what is not

Rollbacks

There is no per-migration down you can lean on in production. Plan forward instead:

• +Backups with point-in-time recovery, tested by an actual restore.
• +Forward-only fixes. A bad migration is corrected by a new migration.
• +A staging database restored from production so migrations run once against real data volume before they run against real data.

That last one catches the migration that works on 200 rows and locks a table for eleven minutes on two million.

Migrations in modules and plugins

Each module owns its migrations under src/modules/<name>/migrations/, and db:migrate runs pending ones across all modules and plugins. Plugins ship their own, which is why installing one is always followed by a migrate.

Commit generated migrations. They are source: reviewed, versioned, and identical across environments.

Practical guidance

Generate after every model change, immediately. Batching three changes into one migration makes the diff unreadable.

Name the branch after the migration. Schema changes deserve their own PR and their own review.

Test on a production-sized copy. Lock duration is a function of table size, and staging never has enough rows.

Never edit an applied migration. Environments will diverge. Write a new one.

Backfilling data

Schema changes and data changes are different operations and should be different steps. A migration that adds a column and then updates two million rows will hold a lock for minutes.

Add the column in the migration, then backfill in a script in batches:

import { ExecArgs } from "@medusajs/framework/types"

export default async function backfill({ container }: ExecArgs) {
  const loyalty = container.resolve("loyalty")
  const logger = container.resolve("logger")

  const BATCH = 500
  let offset = 0

  for (;;) {
    const accounts = await loyalty.listLoyaltyAccounts(
      { points_balance: null },
      { take: BATCH, skip: offset },
    )
    if (!accounts.length) break

    await loyalty.updateLoyaltyAccounts(
      accounts.map((a) => ({ id: a.id, points_balance: a.points })),
    )

    offset += accounts.length
    logger.info(`[backfill] ${offset} accounts`)
  }
}

Batched, resumable, and it can run while the application serves traffic.

A pre-merge checklist for schema changes

[ ] Read the generated SQL line by line
[ ] No unintended DROP statements
[ ] New non-nullable columns have a default, or are added nullable
[ ] New indexes on large tables use CONCURRENTLY
[ ] The migration does not break the currently deployed code
[ ] Tested against a production-sized database copy
[ ] Lock duration measured, not assumed
[ ] Backfill separated into a script
[ ] Rollback plan written down

The one that catches the most real problems is testing against a production-sized copy. A migration that takes 40ms on 200 seeded rows can take eleven minutes and an exclusive lock on two million.

Multiple environments

Migrations must run in the same order everywhere, which means the same commits in the same sequence.

The practice that prevents divergence: never run a migration manually in production. If it is not in the pipeline, it did not happen — and an environment with a hand-applied migration will silently diverge until a later migration fails against a schema nobody can reconstruct.

For a hotfix that genuinely needs a schema change, still ship it through the pipeline on a hotfix branch. The five minutes saved by applying it by hand is not worth the environment drift, and the audit trail is worth having when someone asks what changed.

Keep staging's schema identical to production by restoring a production backup periodically, so migrations are always tested against a schema that actually exists.

Schema changes are where deploys go wrong quietly. We are happy to review a risky one.