Database Migration Commands

Learn how to manage database migrations with the Medusa CLI.

Database Migration Commands

The Medusa CLI provides several commands for managing database migrations, including creating databases, running migrations, generating migration files, and rolling back changes.

Overview

Medusa uses a migration system to manage database schema changes across modules. Each module can have its own migrations, and the CLI provides commands to coordinate these migrations across your entire application.

Commands

medusa db:setup

Create the database, run all pending migrations, and sync links in a single command.

medusa db:setup

Options

--db <name>

Specify the name of the database to create.

medusa db:setup --db my_medusa_store

--interactive / --no-interactive

Display or suppress interactive prompts.

medusa db:setup --no-interactive

• Type: boolean
• Default: true

--skip-links

Skip the link synchronization step.

medusa db:setup --skip-links

--execute-all-links

Skip prompts and execute all actions from sync links, including unsafe operations.

medusa db:setup --execute-all-links

--execute-safe-links

Skip prompts and execute only safe actions from sync links.

medusa db:setup --execute-safe-links

Example Output

info: Creating database...
info: Database created successfully
info: Running migrations...
---------------------------------------------------------------
info: Migrations completed
---------------------------------------------------------------
info: Syncing links...
info: Links synced successfully

---

medusa db:create

Create the database used by your Medusa application.

medusa db:create

Options

--db <name>

Specify the database name to create.

medusa db:create --db my_medusa_store

--interactive / --no-interactive

Control interactive prompts.

medusa db:create --no-interactive

• Type: boolean
• Default: true

---

medusa db:migrate

Execute all pending database migrations.

medusa db:migrate

Options

--skip-scripts

Skip running migration scripts.

medusa db:migrate --skip-scripts

--skip-links

Skip the link synchronization step.

medusa db:migrate --skip-links

--execute-all-links

Execute all link sync actions without prompting, including unsafe operations.

medusa db:migrate --execute-all-links

--execute-safe-links

Execute only safe link sync actions without prompting.

medusa db:migrate --execute-safe-links

--concurrency <number>

Number of concurrent migrations to run.

medusa db:migrate --concurrency 5

--all-or-nothing

If any migration fails, revert all migrations that were applied.

medusa db:migrate --all-or-nothing

• Type: boolean
• Default: false

Example Output

info: Running migrations...
info: [ProductModule] Running migration 001_create_products
info: [OrderModule] Running migration 001_create_orders
info: [CartModule] Running migration 001_create_carts
---------------------------------------------------------------
info: Migrations completed
---------------------------------------------------------------
info: Syncing links...
info: Links synced successfully
---------------------------------------------------------------
info: Running migration scripts...
info: Migration scripts completed

---

medusa db:migrate:scripts

Run all migration scripts without running migrations.

medusa db:migrate:scripts

Migration scripts are additional setup scripts that run after migrations to populate or transform data.

---

medusa db:rollback

Rollback the last batch of migrations for specified modules.

medusa db:rollback <modules...>

Arguments

modules (required)

One or more module names to rollback migrations for.

medusa db:rollback product order

Example Output

info: Reverting migrations...
info: [ProductModule] Reverting migration 002_add_product_variants
info: [OrderModule] Reverting migration 003_add_order_status
---------------------------------------------------------------
info: Migrations reverted

Error Handling

If you specify an invalid module name, you’ll see:

error: Unknown modules: invalid-module
error: Available modules:
          - product
          - order
          - cart
          - customer
          - ...

---

medusa db:generate

Generate migration files for specified modules based on entity changes.

medusa db:generate <modules...>

Arguments

modules (required)

One or more module names to generate migrations for.

medusa db:generate product

Example Output

info: Generating migrations...
info: [ProductModule] Generated migration: 003_add_product_description
info: Migration file created at: src/modules/product/migrations/003_add_product_description.ts
---------------------------------------------------------------
info: Migrations generated

How It Works

The command:

1. Compares your current entity definitions with the database schema
2. Detects differences (new tables, columns, indexes, etc.)
3. Generates TypeScript migration files with the necessary changes
4. Saves the migration files in your module’s migrations directory

---

medusa db:sync-links

Synchronize database schema with the links defined by your application and Medusa core.

medusa db:sync-links

Links define relationships between modules. This command ensures the database schema matches your link definitions.

Options

--execute-all

Execute all actions without prompts, including unsafe operations.

medusa db:sync-links --execute-all

--execute-safe

Execute only safe actions without prompts.

medusa db:sync-links --execute-safe

--concurrency <number>

Number of concurrent operations to run.

medusa db:sync-links --concurrency 5

Example Output

info: Syncing links...
info: Creating link table: product_order_link
info: Creating index: idx_product_order_link_product_id
info: Links synced successfully

---

Common Workflows

Initial Setup

When setting up a new Medusa project:

# Create database and run all migrations
medusa db:setup

After Pulling Changes

When you pull changes that include new migrations:

# Run any pending migrations
medusa db:migrate

After Modifying Entities

When you modify entity definitions in a module:

# Generate migration for the module
medusa db:generate my-module

# Review the generated migration file
# Then run the migration
medusa db:migrate

Rollback Last Changes

If you need to undo recent migrations:

# Rollback specific modules
medusa db:rollback product order

Production Deployment

For deploying to production:

# Build the application
medusa build

# Run migrations (skip interactive prompts)
medusa db:migrate --no-interactive

# Start the server
medusa start

Environment Variables

All database commands set:

• NODE_ENV=development - Default environment for database operations
• MEDUSA_WORKER_MODE=server - Set to server mode
• DB_MIGRATION_CONCURRENCY - Controlled by --concurrency option

Database Connection

Migration commands use the database connection configuration from your Medusa config file (typically medusa-config.js or medusa-config.ts).

Example configuration:

module.exports = {
  projectConfig: {
    database_url: process.env.DATABASE_URL,
    database_type: "postgres",
  },
}

Troubleshooting

”Unknown modules” Error

When running db:generate or db:rollback, if you see an error about unknown modules, use the exact module name as defined in your configuration.

The error message shows available modules:

error: Unknown modules: prod
error: Available modules:
          - product
          - order
          - cart

Migration Failures

If a migration fails:

1. Check the error message for details
2. Fix the underlying issue (e.g., database permissions, schema conflicts)
3. Re-run the migration

With --all-or-nothing, failed migrations are automatically reverted:

medusa db:migrate --all-or-nothing

Database Already Exists

If you run db:create and the database already exists, you’ll see a message indicating the database exists. This is safe to ignore if you’re setting up an existing project.

See Also

• medusa db:setup - Complete database setup
• Database Configuration - Learn about database configuration options
• Deployment Overview - Production deployment guide