> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/medusajs/medusa/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
medusa db:setup
```

#### Options

**`--db <name>`**

Specify the name of the database to create.

```bash theme={null}
medusa db:setup --db my_medusa_store
```

**`--interactive` / `--no-interactive`**

Display or suppress interactive prompts.

```bash theme={null}
medusa db:setup --no-interactive
```

* Type: `boolean`
* Default: `true`

**`--skip-links`**

Skip the link synchronization step.

```bash theme={null}
medusa db:setup --skip-links
```

**`--execute-all-links`**

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

```bash theme={null}
medusa db:setup --execute-all-links
```

**`--execute-safe-links`**

Skip prompts and execute only safe actions from sync links.

```bash theme={null}
medusa db:setup --execute-safe-links
```

#### Example Output

```bash theme={null}
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.

```bash theme={null}
medusa db:create
```

#### Options

**`--db <name>`**

Specify the database name to create.

```bash theme={null}
medusa db:create --db my_medusa_store
```

**`--interactive` / `--no-interactive`**

Control interactive prompts.

```bash theme={null}
medusa db:create --no-interactive
```

* Type: `boolean`
* Default: `true`

***

### medusa db:migrate

Execute all pending database migrations.

```bash theme={null}
medusa db:migrate
```

#### Options

**`--skip-scripts`**

Skip running migration scripts.

```bash theme={null}
medusa db:migrate --skip-scripts
```

**`--skip-links`**

Skip the link synchronization step.

```bash theme={null}
medusa db:migrate --skip-links
```

**`--execute-all-links`**

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

```bash theme={null}
medusa db:migrate --execute-all-links
```

**`--execute-safe-links`**

Execute only safe link sync actions without prompting.

```bash theme={null}
medusa db:migrate --execute-safe-links
```

**`--concurrency <number>`**

Number of concurrent migrations to run.

```bash theme={null}
medusa db:migrate --concurrency 5
```

**`--all-or-nothing`**

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

```bash theme={null}
medusa db:migrate --all-or-nothing
```

* Type: `boolean`
* Default: `false`

#### Example Output

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
medusa db:rollback <modules...>
```

#### Arguments

**`modules`** (required)

One or more module names to rollback migrations for.

```bash theme={null}
medusa db:rollback product order
```

#### Example Output

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
medusa db:generate <modules...>
```

#### Arguments

**`modules`** (required)

One or more module names to generate migrations for.

```bash theme={null}
medusa db:generate product
```

#### Example Output

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
medusa db:sync-links --execute-all
```

**`--execute-safe`**

Execute only safe actions without prompts.

```bash theme={null}
medusa db:sync-links --execute-safe
```

**`--concurrency <number>`**

Number of concurrent operations to run.

```bash theme={null}
medusa db:sync-links --concurrency 5
```

#### Example Output

```bash theme={null}
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:

```bash theme={null}
# Create database and run all migrations
medusa db:setup
```

### After Pulling Changes

When you pull changes that include new migrations:

```bash theme={null}
# Run any pending migrations
medusa db:migrate
```

### After Modifying Entities

When you modify entity definitions in a module:

```bash theme={null}
# 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:

```bash theme={null}
# Rollback specific modules
medusa db:rollback product order
```

### Production Deployment

For deploying to production:

```bash theme={null}
# 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:

```javascript theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](#medusa-dbsetup) - Complete database setup
* [Database Configuration](/deployment/database) - Learn about database configuration options
* [Deployment Overview](/deployment/overview) - Production deployment guide