database-migration

Overview of database-migration skill

What the database-migration skill helps you do

The database-migration skill is for planning and generating database schema and data migration work across common ORM and SQL workflows, with special attention to rollback safety and zero-downtime releases. It is most useful when you need more than a generic “write a migration” prompt: for example, when a change touches live production data, requires staged deployment, or must work within a specific migration framework such as Sequelize or TypeORM.

Who should use this database-migration skill

Best-fit users are Database Engineering teams, backend engineers, platform engineers, and AI-assisted developers who need migration output that is operationally aware, not just syntactically correct. If you are changing tables, backfilling data, renaming columns safely, or moving between ORM patterns, this skill gives the model a stronger default frame than a blank prompt.

What job-to-be-done it is best at

Use the database-migration skill when the real task is to produce a migration plan that can actually be executed: migration files, phased rollout steps, rollback paths, and data transformation considerations. The core value is not just code generation. It is reducing migration guesswork around order of operations, compatibility windows, and failure recovery.

Main differentiators vs a normal coding prompt

Compared with an ordinary prompt, this database-migration skill is opinionated around:

• ORM-aware migration examples
• explicit up and down patterns
• zero-downtime thinking
• schema change plus data change workflows
• rollback procedures as a first-class requirement

That makes it a better fit for production changes than a generic “generate SQL” request.

What is in scope and what is not

The current skill content is strongest on migration patterns and example structures, especially for Sequelize and TypeORM. It is lighter on repository-specific automation, validation scripts, and decision rules because the skill folder only exposes SKILL.md. That means it can guide and draft migration work well, but you should still provide your own stack details, constraints, and deployment model to get reliable output.

How to Use database-migration skill

Install context for database-migration skill

If you use the Skills system from this repository, install the skill from the repo and then invoke it in an agent session that already has access to your codebase and schema context. A typical install looks like:

npx skills add https://github.com/wshobson/agents --skill database-migration

Because this skill ships mainly as a single SKILL.md, expect the value to come from how you frame the request and how much schema context you supply.

Read this file first before using it

Start with:

• plugins/framework-migration/skills/database-migration/SKILL.md

Since there are no visible supporting rules/, resources/, or scripts for this skill, you do not need a long repo-reading phase. The practical reading path is simple: inspect SKILL.md, then move quickly into your own schema files, ORM config, and existing migration history.

What input the skill needs to work well

The database-migration skill performs much better when you provide:

• current ORM or migration tool: Sequelize, TypeORM, Prisma, raw SQL, etc.
• current schema or model definitions
• target schema change
• whether data backfill is needed
• table sizes or traffic sensitivity
• downtime tolerance
• rollback expectation
• target database engine: PostgreSQL, MySQL, etc.
• deployment style: one-shot, phased, blue/green, canary

Without these details, the model may return a valid-looking migration that is unsafe for production.

Turn a rough goal into a strong database-migration prompt

Weak prompt:

Create a migration to rename a column.

Stronger prompt:

Use the database-migration skill. We use TypeORM with PostgreSQL.
Current table: users(id, full_name, created_at).
Goal: replace full_name with first_name and last_name.
Constraints: production table has 20M rows, cannot block writes, rollout must be zero-downtime, app and migration may be deployed separately.
Need:
1. phased migration plan
2. TypeORM migration files
3. data backfill strategy
4. rollback plan
5. application compatibility notes during transition

The second version gives the skill what it needs to choose a safer expand-migrate-contract approach instead of a risky direct rename.

Best workflow for real migration tasks

A practical database-migration usage flow is:

1. Ask for a migration strategy first.
2. Review risks, locking behavior, and rollback assumptions.
3. Ask for the actual migration file in your framework.
4. Ask for app-layer compatibility changes if the rollout is staged.
5. Ask for verification queries and rollback steps.
6. Run in staging with production-like data shape before trusting the output.

This sequencing matters because migration code generated too early often bakes in the wrong rollout model.

ORM patterns the skill is strongest at

Repository evidence shows explicit examples for:

• Sequelize migrations
• TypeORM migrations

The description also names broader ORM/platform migration use, but the visible examples are strongest in those two ecosystems. If you use another stack, ask the model to translate the same migration intent into your toolchain rather than assuming native depth.

When to ask for zero-downtime guidance explicitly

Do not assume the model will always optimize for online migration safety. Say so directly when any of these are true:

• large tables
• high write volume
• independent app and DB deploys
• column renames or type changes
• backfills on hot paths
• constraint changes on production traffic

For database-migration for Database Engineering teams, this is usually the difference between a toy answer and a deployable one.

What outputs to request from the skill

For high-confidence use, ask the database-migration skill to return a bundle, not just a file:

• migration code
• rollout sequence
• rollback sequence
• data backfill logic
• assumptions and risks
• validation checklist
• post-migration cleanup steps

This prevents hidden operational work from being omitted.

Practical warning on direct destructive changes

The skill is best used to avoid unsafe one-step changes such as:

• dropping old columns immediately
• renaming hot columns in place without compatibility
• changing types without conversion strategy
• adding non-null constraints before backfill
• rewriting large tables without planning lock impact

If your first output does any of those on a production path, ask for a phased alternative.

database-migration skill FAQ

Is this database-migration skill only for ORM migrations

No. The skill is framed around database schema and data migrations across ORMs and platforms. In practice, the visible examples are ORM-oriented, especially Sequelize and TypeORM, so you will get the best results when you state your exact stack and ask for SQL or framework translation as needed.

Is the database-migration skill good for beginners

Yes, with limits. It is accessible because the examples are concrete, but it assumes you can judge whether a migration is operationally safe. Beginners can use it to draft migration files and rollout plans, but should not treat the first answer as production-ready without review.

When should I not use database-migration

Skip this skill when your task is purely conceptual and not about actual schema/data change execution. It is also a weak fit if you expect full environment-specific validation from the repository alone, because this skill does not include extra scripts, rules, or test harnesses in the exposed folder.

How is this better than asking an AI to write SQL

The database-migration guide value is that it frames the task around migration lifecycle, not just syntax. A plain SQL prompt often misses rollback, compatibility windows, staged backfills, and ORM migration conventions. This skill is better when deployment safety matters as much as code correctness.

Does it support zero-downtime deployments

Yes, that is one of the clear intended use cases. But you still need to specify what zero-downtime means in your environment. The phrase is too broad on its own; the model needs your deploy order, read/write traffic shape, and compatibility constraints.

How to Improve database-migration skill

Give the skill schema diff plus operational constraints

The fastest way to improve database-migration output quality is to provide both the schema change and the runtime constraints together. For example:

Current: orders.status VARCHAR nullable
Target: orders.status ENUM not null
DB: PostgreSQL
Rows: 80M
Traffic: constant writes
Requirement: no downtime, rollback available, deploy app separately

This pushes the model toward phased migration design instead of a simplistic alter statement.

Ask for expand-migrate-contract when safety matters

If the first draft looks too destructive, explicitly request an expand-migrate-contract plan. That usually improves results for:

• renames
• type conversions
• non-null introductions
• table splits
• denormalization or normalization changes

This is one of the most reliable ways to get better database-migration usage from the skill.

Require validation and rollback in the first response

A common failure mode is receiving a correct up migration with a weak or unrealistic down. Improve this by asking for:

• rollback conditions
• data loss warnings
• verification queries
• success criteria after each phase

That forces the model to reason about reversibility early.

Provide existing migration style from your repo

If your project already has migration conventions, paste one or two representative files and ask the skill to match them. This materially improves naming, transaction handling, timestamp style, and framework idioms. It is especially useful for Sequelize and TypeORM, where teams often have local patterns beyond the framework default.

Iterate on lock risk, not only code correctness

After the first output, ask follow-up questions such as:

• Which steps may lock the table?
• Which steps can run while writes continue?
• What should be split into separate deploys?
• Which part is irreversible after backfill?
• What monitoring should we watch during rollout?

This is often where the database-migration skill becomes genuinely valuable for Database Engineering work rather than just generating boilerplate.

Watch for these common failure modes

Be cautious if the generated migration:

• assumes tiny tables
• omits rollback
• drops old fields too early
• combines schema change and massive backfill in one risky step
• ignores app compatibility during transition
• uses framework syntax that does not match your version

These are normal reasons to refine the prompt, not signs that the skill is unusable.

Best way to improve results after the first draft

Treat the first answer as a migration proposal, not a final artifact. Then ask the skill to revise based on:

• your actual table sizes
• index situation
• expected deploy order
• canary or staging findings
• any failed assumptions from review

That feedback loop is the most practical way to get production-grade value from the database-migration install and usage workflow.