How to Automate Database Migrations

Database migration work is the process of changing durable data structures without losing data, breaking application code, or making rollback impossible. A good migration plan covers schema history, application call sites, data movement, deployment order, validation checks, and the production risks that reviewers need to see.

The work is worth systematizing because migrations are easy to underestimate. A column rename, constraint change, enum edit, or backfill may look small in the diff while touching every active customer record. The safest teams treat migrations as operational changes, not routine code edits.

Why migration work quietly costs you

Bad migrations rarely fail at the moment someone writes the file. They fail when a deploy hits a lock, when old application code cannot read the new shape, when rollback would drop data, or when a generated ORM diff encodes a destructive change nobody inspected.

The hidden cost is review fatigue. Engineers remember to check the obvious parts of the diff, but not always the migration history, table size, indexes, background backfill path, seed compatibility, generated client changes, or validation query. A repeatable process keeps those checks out of memory and inside the work.

What the manual process looks like

Safe migration work usually follows this ritual:

1. Read the migration history, schema definitions, application call sites, and repository conventions.
2. Classify the change: schema-only, data backfill, expand-contract, index, constraint, destructive cleanup, or ORM metadata update.
3. Plan the sequence. Add nullable fields before writes, backfill separately when needed, deploy reads and writes safely, then enforce constraints or remove the old shape.
4. Check lock, table-scan, downtime, and rollback risk for indexes, constraints, large updates, default values, and destructive operations.
5. Generate or write the migration in the repository's own toolchain, then inspect the generated SQL or diff before trusting it.
6. Update application code, generated clients, seeds, fixtures, and tests where the schema contract changed.
7. Run migration, rollback or reversibility checks where available, and relevant tests against disposable data.
8. Draft the pull request with sequencing, validation evidence, and production-risk notes.

The process is deliberate because the database is shared state. Fast is useful only when the change is also ordered and reviewable.

What an agent can automate

An agent is useful when it works inside the repository and treats the migration as a production operation:

• Inspect before writing. It reads schema history, app call sites, migration naming conventions, and test patterns before choosing a path.
• Classify the risk. It identifies whether the change is expand-contract, data backfill, index work, constraint enforcement, ORM metadata, or a destructive cleanup that needs explicit approval.
• Use the native toolchain. It generates or writes migrations using the repository's own migration tools instead of inventing a second path.
• Verify the generated change. It checks ordering, timestamp uniqueness, generated SQL, relation names, nullability, defaults, indexes, unique constraints, enum changes, seed compatibility, and drift checks where relevant.
• Prepare the review. It runs the requested verification command and drafts a pull request with validation notes, lock or downtime risk, rollback notes, and any code changes required by the new schema.

The agent can do the tedious inspection and drafting. It should not apply a production migration itself.

The guardrails that make it safe

The key guardrail is a hard boundary around destructive changes and production application. The playbook tells the database engineer never to drop data, rewrite a large table, or make a backwards-incompatible contract change without explicit human approval and a rollback plan.

The second guardrail is repository-native verification. The agent uses the repository's own migration, rollback, client-generation, seed, and test commands where they exist. That keeps the evidence tied to the codebase reviewers will actually merge.

Set it up in Task Machine

The Database migrations playbook installs a Database Engineer agent, the Migrations land safely goal, and migration skills for production-risk review and ORM migration guardrails. Setup takes a few minutes. You need a Task Machine workspace and permission to install playbooks (workspace owners have it). The playbook needs a connected repository and runnable database checks before it can do useful migration work.

1. Find the playbook

Open Playbooks and search for "database migrations", or browse the Engineering category. The card shows that this playbook installs an agent, a goal, and migration skills rather than a standing workflow or schedule.

2. Preview what it installs

Click Preview & install to inspect the bundle. The preview lists the Database Engineer, the Migrations land safely goal, the database-migration skill, the Prisma migration assistant skill, and the starter task proposal that will land after install.

3. Describe the migration context

Click Start setup and choose the repository, then write the schema change brief, data migration or rollback risks, and verification command. The best setup answers name the table, desired schema contract, deployment sequence concerns, and exact command the agent should run.

4. Generate and review

Click Generate customized playbook. Review the generated Database Engineer instructions, goal, skills, and starter task proposal. Confirm that the brief says to use the repository's own migration toolchain and that production application remains outside the agent's authority.

5. Install

Click Install customized playbook. A follow-up lands in your inbox to start Database migrations. Approving that starter task gives the installed agent its first concrete assignment. From there, the agent inspects the repository, drafts the migration and PR notes, runs the requested checks, and waits for review before anything moves toward production.

What good looks like

A good migration run leaves reviewers with evidence, not faith.

Check for these outcomes:

• The sequence is explicit. The PR explains whether the change is schema-only, backfill, expand-contract, index, constraint, destructive cleanup, or ORM metadata work.
• The verification is reproducible. The migration command, rollback or reversibility check where available, and relevant tests are named in the notes.
• The production risk is visible. Lock, table-scan, downtime, data-loss, seed, generated-client, and rollback concerns are called out instead of hidden in the diff.

Common questions

Can an agent safely write migration code? Yes, when it works inside the repository's conventions and the result still goes through review. The risky part is not writing the file. The risky part is skipping sequence, rollback, and validation thinking.

Should the agent ever run a production migration? No. The playbook is for planning, drafting, and verifying migration work. Production application stays with the humans who own deployment.

What if the ORM generates a destructive diff? The agent should inspect generated SQL or migration output before trusting it. Destructive changes require explicit approval and a rollback plan.

Why does this playbook create a starter task instead of a workflow? Migration work is scoped assignment by assignment. The bundle installs the agent and goal, then proposes the first task so you can add the concrete migration brief before approving it.