Database Operations

The Medusa CLI provides comprehensive database management capabilities including migration management and database seeding. These commands are only available within Medusa project directories and integrate with the local Medusa installation's database management system.

Capabilities

Database Migrations

Manage database schema migrations for the Medusa project, including running, reverting, and viewing migration status.

medusa migrations [action]

Parameters:

• action (required): Migration action to perform
  • run: Execute pending migrations
  • revert: Revert the most recent migration
  • show: Display migration status and history

Usage Examples:

# Run all pending migrations
medusa migrations run

# Revert the last migration
medusa migrations revert

# Show migration status
medusa migrations show

Behavior:

• Sets NODE_ENV to 'development' if not already configured
• Loads migration configuration from local Medusa project
• Connects to database using project's configuration
• Provides detailed feedback on migration execution

Database Seeding

Populate the database with initial or sample data using custom seed files.

medusa seed --seed-file <path>

Options:

• -f, --seed-file <string> (required): Path to the seed file containing data and instructions
• -m, --migrate <boolean>: Run migrations before seeding (default: true)

Usage Examples:

# Seed database with specific file
medusa seed --seed-file ./data/sample-products.js

# Seed without running migrations first
medusa seed --seed-file ./data/users.js --migrate false

# Seed with migrations (default behavior)
medusa seed -f ./data/store-setup.js

Behavior:

• Optionally runs migrations before seeding based on --migrate flag
• Sets NODE_ENV to 'development' for seed execution
• Executes seed file in the context of the Medusa project
• Provides progress feedback during seeding process

Migration Management

Migration Execution Flow

The migration system follows a structured execution pattern:

Run Migrations:

1. Connects to database using project configuration
2. Checks for pending migrations in the migrations directory
3. Executes migrations in chronological order
4. Updates migration tracking table
5. Reports success or failure for each migration

Revert Migrations:

1. Identifies the most recently applied migration
2. Executes the migration's down/revert function
3. Updates migration tracking to reflect the reversion
4. Provides confirmation of successful reversion

Show Migration Status:

1. Queries migration tracking table
2. Compares with available migration files
3. Displays status of each migration (pending/applied)
4. Shows migration timestamps and descriptions

Migration File Requirements

Migration files must follow Medusa's expected format:

File Location:

• Located in project's migrations directory
• Typically in src/migrations/ or similar project structure
• Named with timestamp prefix for ordering

File Structure:

• Export functions for both up (apply) and down (revert) operations
• Include proper database connection handling
• Follow Medusa's migration API conventions

Database Seeding

Seed File Format

Seed files should be JavaScript modules that export seeding logic:

Basic Structure:

// Example seed file structure
module.exports = async (container) => {
  const productService = container.resolve("productService");
  
  // Seeding logic here
  await productService.create({
    title: "Sample Product",
    // ... other product data
  });
};

Container Access:

• Seed functions receive Medusa's dependency injection container
• Access to all Medusa services and repositories
• Can perform complex data operations using Medusa's business logic

Seeding Workflow

The seeding process follows these steps:

1. Pre-Migration (if enabled): Run pending migrations to ensure schema is current
2. Container Setup: Initialize Medusa's dependency injection container
3. Seed Execution: Load and execute the specified seed file
4. Transaction Management: Handle database transactions for data consistency
5. Error Handling: Provide detailed error reporting for failed seeding operations
6. Cleanup: Properly close database connections and clean up resources

Database Configuration

Connection Management

Database operations use the project's existing configuration:

Configuration Sources:

• Environment variables (DATABASE_URL, etc.)
• Project's medusa-config.js file
• Default connection parameters

Connection Handling:

• Automatic connection establishment using project settings
• Proper connection pooling and management
• Graceful handling of connection failures

Environment Considerations

Database commands respect environment settings:

NODE_ENV Handling:

• Automatically sets to 'development' if not specified
• Affects database connection configuration
• Influences logging and error reporting levels

Database Selection:

• Uses project's configured database connection
• Supports multiple database environments through configuration
• Maintains separation between development, staging, and production

Error Handling and Validation

Migration Error Management

The migration system includes comprehensive error handling:

Pre-execution Validation:

• Verifies database connectivity before starting
• Checks for required migration files and structure
• Validates migration sequence and dependencies

Runtime Error Handling:

• Captures and reports migration execution errors
• Maintains database consistency during failures
• Provides detailed error messages for debugging

Recovery Mechanisms:

• Safe rollback procedures for failed migrations
• Database state preservation during errors
• Clear guidance for manual intervention when needed

Seeding Error Management

Database seeding includes robust error handling:

File Validation:

• Verifies seed file existence and format
• Checks for required dependencies and services
• Validates seed file structure before execution

Execution Monitoring:

• Progress tracking during seed operations
• Detailed error reporting for failed seed operations
• Transaction rollback on critical failures

Command Proxying and Integration

Local Command Resolution

Database commands are proxied to the local Medusa installation:

Dynamic Loading:

• Commands resolved from @medusajs/medusa/dist/commands/
• Uses local project's Medusa version for compatibility
• Falls back to help display if commands unavailable

Argument Forwarding:

• All CLI options passed through to underlying commands
• Project context information automatically included
• Maintains full compatibility with Medusa's native database tools