db-migration
A workflow assistant for safely managing database migrations using Alembic, including generation, testing, and rollback.
Install
mkdir -p .claude/skills/db-migration && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/16470" && unzip -o skill.zip -d .claude/skills/db-migration && rm skill.zipInstalls to .claude/skills/db-migration
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
Safely generates, reviews, and applies Alembic database migrations.Key capabilities
- →Generate Alembic migration scripts
- →Review generated `upgrade()` and `downgrade()` functions
- →Test migration application and rollback
- →Run tests after applying migrations
- →Identify risks in schema changes
How it works
This skill generates an Alembic migration script based on schema changes, guides the user through reviewing its upgrade and downgrade functions, and then tests its application and rollback. It also runs application tests post-migration.
Inputs & outputs
When to use db-migration
- →Generate a migration for a model change
- →Verify that a database migration has a working downgrade
- →Test migrations before production deployment
About this skill
Skill: db-migration
Safely generates, reviews, and applies Alembic database migrations.
When to Use
- Adding new tables or columns
- Renaming columns (with a deprecation plan)
- Adding indexes or constraints
- Removing deprecated columns (after safe deprecation window)
Steps
-
Understand the schema change
- What model changed in
app/models/? - Is this additive (safe) or destructive (risky)?
- What model changed in
-
Generate the migration
alembic revision --autogenerate -m "description_of_change" -
Review the generated file (never skip this)
- Check
upgrade()matches what you intend - Check
downgrade()is correct and reversible - Watch for: dropped columns, renamed columns, changed types
- Autogenerate misses: partial indexes, custom constraints, enum changes
- Check
-
Test the migration
alembic upgrade head # apply alembic downgrade -1 # verify rollback works alembic upgrade head # re-apply -
Run tests after applying migration:
pytest -x -v
Safety Rules
- Never apply a migration that lacks a working
downgrade() - Never drop a column that is still referenced in code
- Rename columns in two releases: add new → migrate data → remove old
- Large table migrations (>1M rows) need
--lock-timeoutand offline strategy
Output
Report: migration filename, what it does, whether downgrade was tested, any risks.
When not to use it
- →Applying a migration that lacks a working `downgrade()`
- →Dropping a column that is still referenced in code
- →Renaming columns without a two-release deprecation plan
Limitations
- →Never apply a migration that lacks a working `downgrade()`.
- →Never drop a column that is still referenced in code.
- →Autogenerate misses: partial indexes, custom constraints, enum changes.
How it compares
This skill enforces a structured and safe process for Alembic migrations, including mandatory review and testing steps, which prevents common pitfalls of manual migration application.
Compared to similar skills
db-migration side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| db-migration (this skill) | 0 | 4mo | Review | Intermediate |
| async-sqlalchemy-patterns | 0 | 4mo | Review | Advanced |
| DB Schema Surgeon | 0 | 6mo | No flags | Advanced |
| senior-data-engineer | 21 | 8mo | Review | Advanced |
Try saying
Example prompts that trigger this skill in your AI assistant.
You might also like
async-sqlalchemy-patterns
majiayu000
Async SQLAlchemy 2.0+ database patterns for FastAPI including session management, connection pooling, Alembic migrations, relationship loading strategies, and query optimization. Use when implementing database models, configuring async sessions, setting up migrations, optimizing queries, managing re
DB Schema Surgeon
adriangmrraa
Gestión del esquema PostgreSQL, Auto-Healing y arquitectura RAG híbrida.
senior-data-engineer
davila7
World-class data engineering skill for building scalable data pipelines, ETL/ELT systems, and data infrastructure. Expertise in Python, SQL, Spark, Airflow, dbt, Kafka, and modern data stack. Includes data modeling, pipeline orchestration, data quality, and DataOps. Use when designing data architectures, building data pipelines, optimizing data workflows, or implementing data governance.
django-pro
sickn33
Master Django 5.x with async views, DRF, Celery, and Django Channels. Build scalable web applications with proper architecture, testing, and deployment. Use PROACTIVELY for Django development, ORM optimization, or complex Django patterns.
senior-backend
davila7
Comprehensive backend development skill for building scalable backend systems using NodeJS, Express, Go, Python, Postgres, GraphQL, REST APIs. Includes API scaffolding, database optimization, security implementation, and performance tuning. Use when designing APIs, optimizing database queries, implementing business logic, handling authentication/authorization, or reviewing backend code.
supabase-python
alinaqi
FastAPI with Supabase and SQLAlchemy/SQLModel