home / skills / medusajs / medusa-agent-skills / db-migrate

db-migrate skill

safe

This skill runs Medusa database migrations and reports applied migrations, errors, and success using the Bash tool to guide deployment.

npx playbooks add skill medusajs/medusa-agent-skills --skill db-migrate

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

411 B

---
name: db-migrate
description: Run database migrations in Medusa
allowed-tools: Bash(npx medusa db:migrate:*)
---

# Run Database Migrations

Execute the Medusa database migration command to apply pending migrations.

Use the Bash tool to execute: `npx medusa db:migrate`

Report the migration results to the user, including:

- Number of migrations applied
- Any errors that occurred
- Success confirmation

Overview

This skill runs Medusa database migrations and reports results back to the user. It executes the Medusa CLI migration command, captures output, and summarizes what changed. The goal is clear, actionable feedback about applied migrations and any errors.

How this skill works

The skill invokes the Medusa CLI migration command (npx medusa db:migrate) via a shell execution tool. It parses the command output to count applied migrations, detect errors or warnings, and extract success confirmations. Finally, it returns a concise summary with counts, error details, and suggested next steps.

When to use it

After adding or modifying Medusa migration files to apply schema changes.
Before deploying to staging or production to ensure migrations run cleanly.
When troubleshooting failed or partially applied migrations.
As part of a CI/CD pipeline step to validate database state changes.

Best practices

Back up the database before running migrations in production.
Run migrations in a controlled environment (staging) first.
Review migration diffs and ensure idempotency before execution.
Check for long-running migrations and plan maintenance windows.
Capture full command output and logs for post-mortem analysis.

Example use cases

Apply pending Medusa migrations after pulling new code that adds schema changes.
Validate that all migrations succeed during a deployment pipeline run.
Diagnose an error when a migration fails and report the failing migration file and error message.
Confirm the number of migrations applied after a maintenance window.

FAQ

What command does this skill run?

It runs npx medusa db:migrate using a shell execution tool.

What information will I get after running migrations?

You receive the number of migrations applied, any error messages or stack traces, and a success confirmation or next-step recommendations.