All commands are api/ executed in the directory.
Workflow
Step 1: Check current status (always run first)
Before starting any task, check the current migration status.
cd api && bun run db:status-dev
Show the user the list of applied migrations and unapplied migrations.
Step 2: Branch according to intent
If only a status check was requested
→ Show the Step 1 result and exit.
Run migration (up)
cd api && bun run db:up-dev
- After running the dbmate migration,
extract-schemais automatically executed. - The schema file (
db/schema/) is automatically updated. - Show the result and inform the list of changed schema files.
Rollback migration (down)
cd api && bun run db:down-dev
- Before execution, be sure to: Show the filename of the migration to roll back, and execute after receiving user approval.
- Only the most recent migration is rolled back.
- After rollback,
extract-schemais automatically executed.
Create new migration
cd api && bun run db:new {migration_name}
db/migrations/YYYYMMDDHHMMSS_{migration_name}.sqlA file is created.- Open the created file and guide with the template structure below:
-- migrate:up
-- migrate:down
Step 3: Report results
Summarize the execution result, and analyze the cause if an error occurs.
File location
| Path | Purpose |
|---|---|
api/db/migrations/ |
Migration file |
api/db/schema/ |
Extracted schema file |
api/db/dev.env |
DB connection info |
Error handling
| Symptom | Cause | Resolution |
|---|---|---|
| Connection failure | DATABASE_URL error or DB server down | api/db/dev.env Check, check DB server status |
| already applied | Migration already applied | db:status-devWith current status check then guide |
| SQL syntax error | Migration file syntax error | Fix the file using the line/column info in the error message |
| index already exists | Attempt to create duplicate index | CREATE INDEX IF NOT EXISTSChange to or check existing index |