Most AI database mistakes are invisible in development: a migration that locks a large table, a backfill in one transaction, a missing constraint that lets bad rows in. This agent asks how much data there is before designing anything, because a design that works at 10,000 rows can fail at 10 million.
When to use the Database Engineer agent
- Schema changes on tables that already hold real data
- Slow queries and missing indexes
- Planning a migration with a backfill
- Data that has turned up duplicated or inconsistent
What is in the agent file
| Name | database-engineer |
|---|---|
| Tools | Read, Write, Edit, Grep, Glob, Bash. It can edit files and run commands, so review its diff. |
| Model | sonnet, up to 40 turns per task |
| Kit | Engineer kit, 109 lines |
How it works. Beyond its role statement, the file sets out 5 rules it follows: Migration safety classification; Severity rubric; Constraints before conventions; Type decisions that are expensive to reverse; Query diagnosis order.
What it reports. Every run ends in the same structure: Change summary, Migration plan, Rollback, Backfill, Verification, Findings.
Excerpt from the agent file
The settings and opening instructions, as they appear in .claude/agents/database-engineer.md:
---
name: database-engineer
description: Designs schemas, queries, indexes and migrations with data integrity and rollback safety. Invoke by name for schema changes, query or index tuning, migration planning, or when data has turned up inconsistent.
model: sonnet
maxTurns: 40
tools: Read, Write, Edit, Grep, Glob, Bash
---
You are a Database Engineer. Your job is to make invalid states unrepresentable and changes reversible.
When given a database task:
1. Read the existing schema and at least two comparable tables. Match the conventions already there — id strategy, timestamp columns, naming, soft-delete policy.
2. Establish the data volume. A design that is fine at 10k rows and wrong at 10M is wrong. Ask or measure; never assume small.
3. For a schema change, classify the migration against the lock table below **before** writing it.
4. For a slow query, read the execution plan before changing anything.
5. Express every business rule you can as a constraint, so no code path can violate it.
6. Write the migration with expand/contract sequencing, a tested down path, and a batched backfill kept separate.
7. Report the lock profile, the rollback path, and whether rollback is actually possible.The full file continues with the rules above and the exact report format. It is included in the Agentsforce kit.
Example requests
Name the agent to be sure Claude uses it, or describe the task and let its description trigger it:
- "Use database-engineer to add a unique email constraint to users without downtime."
- "This query takes 4 seconds. Read the plan and tell me what to change."
- "Plan the migration that splits address into its own table, with rollback."
- "Use database-engineer to find how duplicate subscriptions got into the table."
When to use a different agent
| If you need | Use instead |
|---|---|
| Choosing a hosted database or ORM from scratch | Use tech-lead to weigh the options first |
| Supabase row-level security policies | Use supabase-firebase-engineer |
| Warehouse and analytics pipelines | Use data-pipeline-engineer |
Works well with
- API Engineer: designs and changes endpoints that clients depend on
- Debugging Specialist: finds why a bug happens before changing code
- Code Reviewer: checks what a change did, not whether a file looks fine
Related playbooks in the kit, which Claude loads when the task calls for them: zero-downtime-migrations, query-optimization, data-integrity-constraints, relational-schema-design.
How to get it
- Write your own: the free Subagent Generator drafts a starter database engineer file you can edit and save in
.claude/agents/. - Use the tested version: Agentsforce includes this agent with 54 other specialists and 89 playbooks for a one-time $49, installed with one command.
Frequently asked questions
Can Claude Code run database migrations safely?
It can write them; whether they are safe depends on the method. This agent classifies the lock each statement takes, separates the backfill, writes a tested down path and runs it on a copy, not production.
Does it work with Postgres and MySQL?
Its rules are written for relational databases in general, and it matches the conventions of your existing schema, such as id strategy, timestamps and naming.
Why does it insist on constraints?
A rule enforced only in application code can be bypassed by any other code path or script. A database constraint cannot, so it expresses every rule it can as one.