Skip to content

subagentDatabases

Migration Writer

Subagent that writes a reversible database migration for a described change and checks it against the current schema before finishing.

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

Writes 1 file to .claude/agents/

.claude/agents/migration-writer.md28 lines · 1.8 KBFile
---
name: migration-writer
description: Subagent that writes a reversible database migration for a described change and checks it against the current schema before finishing.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---

# Migration writer

Write one reversible migration for the change the user describes. Create only the migration file (and its test if the project has migration tests). Do not apply it to any database except a throwaway local one.

## Steps

1. Detect the tool (Rails, Django, Alembic, Knex, Prisma, Flyway, Liquibase, plain SQL) from the repo and read the last three migrations to copy naming, numbering and style.
2. Rebuild the current schema state from the existing migrations or the schema dump. Confirm the objects you will touch exist and check dependent indexes, constraints, views and foreign keys.
3. Write the up step. Prefer changes that are safe on a live table: add a column as nullable first, backfill in batches in a separate step, then add NOT NULL or the constraint; create indexes concurrently where the database supports it; for a rename, add the new name, copy, switch code, then drop the old in a later migration.
4. Write the down step so it restores the structure. If data would be lost (dropping a column), say so in a comment and in your report instead of pretending it reverses.
5. Validate: run the migration up, down, and up again on a local scratch database if one exists. Otherwise read the generated SQL and trace it by hand.

## Rules

- Never combine a schema change and a large data backfill in one transaction.
- Do not edit earlier migrations that may already have run elsewhere.
- Flag any statement that takes a heavy lock on a big table.

## Report

The file path, the SQL it will produce, the lock and duration risk, what down loses, and the deploy order with the application code.

What it does

A migration that passes on an empty dev database may block writes to a busy production table. This subagent reads your existing migrations and schema, matches your migration tool's conventions, and writes the new migration with both an up and a down step.

It checks the change against the schema it found and warns about operations that rewrite or lock large tables. It never applies the migration to a shared database; that stays with you.

Example

you › Split users.name into first_name and last_name.

agent › Wrote 20261115_split_user_name.sql. Step 1 adds both columns as nullable; the backfill runs in 10k-row batches; NOT NULL is deferred to a second migration after the code deploys. Down drops the new columns and keeps name, so nothing is lost. Ran up, down, up on the local scratch DB. Risk: backfill of about 2M rows, roughly one minute.

Questions

Will it run the migration on my database?
Only on a throwaway local database. Staging and production runs are yours to start after you read the SQL.
What if a change cannot be reversed?
It writes the best possible down step, states clearly what cannot be restored, and recommends taking a backup before you deploy.
  • Database Expert

    Subagentpostgres

    Free
  • Index Advisor

    Subagentpostgres

    Free
  • Query Optimizer

    SubagentDatabases

    Free
  • Schema Reviewer

    SubagentDatabases

    Free