Skip to content

commandDatabases

Write Migration

Drafts an up and down migration for the schema change you describe, then checks it for table locks, data loss and rollout order.

npx workspacetemplates add write-migration --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/write-migration.md14 lines · 1.2 KBFile
---
description: Drafts an up and down migration for the schema change you describe, then checks it for table locks, data loss and rollout order.
argument-hint: "[describe the schema change]"
---

Write a migration for: $ARGUMENTS

1. Find the migration tool (Prisma, Alembic, Rails, Flyway, Knex, Django, goose, Drizzle) and copy the naming and style of the latest migration. Read the current schema for the affected tables.
2. Write the up and the down. If the down cannot restore dropped data, say so plainly in a comment.
3. Review against the database dialect: does this take a long lock (ADD COLUMN with default on old Postgres, type change, index without CONCURRENTLY, NOT NULL on a big table)? Does it drop or truncate data? Is it safe with the old code still running?
4. Split risky changes into stages: add nullable column, deploy code that writes both, backfill in batches, then add the constraint, then drop the old one.
5. Never run the migration. Never edit a migration that has already been applied or merged.

Output the file(s), a risk list (lock, data loss, deploy order) and the exact command to test on a copy of the database. Ask before generating any follow-up stage.

What it does

A migration that works on an empty dev database can still lock a busy table for minutes. This command writes the migration in your project's own tool and format, and includes a matching step to undo it.

Before it finishes it reviews the change for table locks, data loss and the order of deploy versus migrate, and splits risky changes into safe stages.

Example

you › /write-migration make users.phone required, existing rows have nulls

agent › Unsafe as one step on 2M rows. Wrote 3 migrations: 0042 add default-free check as NOT VALID, 0043 backfill phone from profiles in batches of 5,000, 0044 VALIDATE CONSTRAINT.
Down steps included. Test with: npx prisma migrate dev on a restored copy.

Questions

Does it run the migration?
Never. It writes the files and gives you the command to test on a copy first.
Why does it split some changes into several migrations?
Large tables can lock while one step runs, so risky changes are staged to keep the app running between deploys.
  • Add Index

    CommandDatabases

    Free
  • Explain Query

    CommandDatabases

    Free
  • Schema Diff Review

    CommandDatabases

    Free
  • Seed Database

    CommandDatabases

    Free