Skip to main content

​
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
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

Build docs developers (and LLMs) love

Get started for freeTalk to us