Guide · Agent skill
How to use the Database Migration Patterns agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The database-migrations skill is a set of guidance files that tells an AI agent how to make database schema and data changes safely. It is written for backend developers who change live production databases, and it covers PostgreSQL and MySQL plus common tools such as Prisma, Drizzle, Kysely, Django, TypeORM and golang-migrate. After this guide you will know how to install the skill, ask for migrations in plain language, and check what the agent produces.
Database Migration Patternsaffaan-m/ECC · MIT Download the skill Quick start
- 1Download the ZIP. Get the database-migrations ZIP from this skill's page on the directory.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Describe the change in plain language. Name the change, your database engine and your ORM or migration tool, for example adding a column to a Postgres table with Prisma.
- 5Review the migration against the checklist. Check for a down step, no full table locks, defaulted or nullable new columns, concurrent indexes and a separate backfill.
- 6Test on production-sized data before deploying. Run the migration against a copy of production data and confirm it does not lock tables under real load.
What does the database-migrations skill make the agent do?
When you ask the agent to change a database, such as adding a column, creating a table, adding an index or backfilling data, the skill points it toward established safety practices. The source describes these core principles: every change is a migration rather than a manual change to the production database; migrations move forward only in production, so rollbacks are done with a new forward migration; schema and data migrations are kept separate; migrations are tested against production-sized data; and migrations are not edited after they have been deployed.
The skill also includes a pre-apply checklist. It asks for migrations with both up and down steps (or an explicit mark that the change is irreversible), no full table locks on large tables, new columns that are either defaulted or nullable, indexes created concurrently, backfills in their own migration, testing on a copy of production data, and a documented rollback plan.
How do you install the skill?
Download the ZIP file from the skill's page on this directory. Unzip it so the database-migrations folder lands in one of two places: ~/.claude/skills/ to make it available across your projects, or .claude/skills/ inside a single project to share it with that project.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ in your project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
How do you trigger the skill with a natural request?
You do not need a special command. Describe the database change in plain language and mention the database or tool you use. The skill is meant to activate when you create or change tables, add or remove columns or indexes, run data migrations such as backfills or conversions, plan zero-downtime schema changes, or set up migration tooling for a new project.
Be specific about your engine and ORM, because the guidance differs between PostgreSQL and MySQL and between tools.
- "Add an avatar_url column to the users table in our Postgres database using Prisma."
- "Plan a zero-downtime change to add an index on the orders table, which has about 50 million rows."
- "Backfill the new status column for existing rows, and keep it in a separate migration from the schema change."
- "Set up golang-migrate for a new Go service on PostgreSQL."
What does a safe PostgreSQL example look like?
The skill includes examples of safer and riskier column additions. Adding a nullable column is a lock-free change. Adding a column with a default is fast on Postgres 11 and later, according to the source. Adding a NOT NULL column to an existing table without a default is marked as bad because it requires a full table rewrite.
-- GOOD: Nullable column, no lock
ALTER TABLE users ADD COLUMN avatar_url TEXT;
-- GOOD: Column with default (Postgres 11+ instant, no rewrite)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;
-- BAD: NOT NULL on existing table without default (requires full rewrite)
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL;What should you check before applying a migration?
Run the checklist from the skill against each migration before you apply it. Treat it as a review aid: the agent should work through it, and you should confirm the answers yourself, especially for large tables and production data.
- Does every migration have a down step, or is it explicitly marked irreversible?
- Does it avoid full table locks on large tables?
- Are new columns defaulted or nullable?
- Are indexes created concurrently rather than inline?
- Is the data backfill in its own migration?
- Has it been tested on a copy of production data?
- Is there a documented rollback plan?
What does the skill need and what are its safety notes?
The skill lists no required dependencies. It does not run scripts and does not use the network. The package contains one file, SKILL.md, which holds the guidance.
The skill only supplies guidance and examples. It does not run migrations or connect to your database. You or your normal tooling still apply every change, so review the agent's migration code before it reaches production.
Tips for getting better results
Give the agent your engine, ORM and table size up front, since locking risk depends on how many rows a table holds. Ask for the down migration and rollback plan in the same request so they are not forgotten. Keep your schema and data changes in separate requests, which mirrors the skill's own rule.
- State the database engine and version if you know it.
- Name your ORM or migration tool, such as Prisma, Drizzle, Django or golang-migrate.
- Ask for a separate migration for backfills.
- Test the generated migration against a copy of production-sized data.
What people use it for
- Adding a nullable column to a large users table without locking writes.
- Creating an index concurrently on a busy table in PostgreSQL.
- Backfilling a new column in a separate migration after the schema change.
- Setting up migration tooling for a new project using golang-migrate or Django.
- Planning a zero-downtime schema change that is rolled out in stages.
Frequently asked questions
How do I install the database-migrations skill?
Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project folder. In the Claude apps you can instead upload it under Settings, then Capabilities, then Skills.
Is the database-migrations skill free to use?
The source lists the licence as MIT. Check the repository's licence file for the full terms before you use it in your own work.
What does the database-migrations skill require?
The skill lists no required dependencies. It does not run scripts and does not use the network. You still need your own database and migration tooling to apply any migration.
Does the skill run migrations on my database?
No. The skill only supplies guidance and examples. It does not connect to a database or apply changes, so you or your existing tools must run every migration.
Which databases and tools does it support?
It covers PostgreSQL and MySQL, plus Prisma, Drizzle, Kysely, Django, TypeORM and golang-migrate. The source notes that advice may not apply directly to databases outside these engines and tools.
Why does the skill say not to edit migrations after deployment?
The skill's core principles say migrations should not be edited once they have run in production. To undo a change in production, write a new forward migration instead.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a backend developer changing a live production database, or a team planning zero-downtime changes on large tables. Skip it for throwaway prototypes where data loss and downtime do not matter, since the checklists add overhead. If you use a database or tool outside PostgreSQL, MySQL and the listed ORMs, expect to adapt the advice yourself.
Download the skill