Skills Guide

db-migration

VerifiedCaution

Safely generate, review, and apply Alembic database migrations for schema changes.

Download and use
Sby Skills Guide Bot
DevelopmentIntermediate
7/24/2026
Claude CodeCursorCodexWindsurf
#alembic#database-migrations#sqlalchemy#schema-evolution#rollback-safety

Recommended for

Backend developerClaude CodeCode reviewFrontend developerCursorFullstack developer

Automated summary

Generates, reviews, and applies Alembic migrations while enforcing that each one is reversible and tested before it ships.

Strengths

  • Forces a manual review of the generated file and flags what autogenerate misses (partial indexes, custom constraints, enum changes)
  • Always validates the upgrade / downgrade -1 / upgrade cycle before running the test suite
  • Gives an explicit two-release column rename procedure with a data migration step
  • Calls out precautions for large tables (>1M rows) using lock-timeout and an offline strategy

Limitations

  • Assumes a Python/SQLAlchemy project already wired to Alembic; no other migration tooling is covered
  • Does not go beyond the add → migrate → remove pattern for complex data backfills
  • Risk detection depends on the human review step; there is no automated diff analysis
When to use it

Use it whenever a model under app/models/ changes and a safe, reversible Alembic migration must be produced.

When not to use it

Skip it if the project does not use Alembic, or for a hand-written schema change with no corresponding SQLAlchemy model.

Security analysis

Caution
Quality score88/100

The skill guides database schema changes using powerful migration tooling. While it includes safety rules and review steps, the actual execution involves potentially destructive database operations and shell commands, warranting caution.

Findings
  • •Instructs execution of Alembic migration commands which can modify or drop database schema/data.
  • •No allowed-tools declared, so the agent may run arbitrary shell commands like alembic and pytest.
  • •Downgrade/upgrade cycles can cause data loss if migrations are not reversible or are misapplied.
How this analysis is made

Examples

Add a column with an index
I added a `last_login_at` column and an index on `users.email` in app/models/user.py — generate the Alembic migration, review it for anything autogenerate misses, and verify the downgrade works.
Rename a column safely
We want to rename `users.fullname` to `users.display_name`. Walk me through the two-release plan with Alembic migrations and the data migration step.
Drop a deprecated column
The `legacy_token` column on `sessions` is no longer referenced anywhere. Generate the migration to drop it, confirm the downgrade restores it, and run pytest after applying.

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

  1. Understand the schema change

    • What model changed in app/models/?
    • Is this additive (safe) or destructive (risky)?

  2. Generate the migration

    alembic revision --autogenerate -m "description_of_change"

  3. 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

  4. Test the migration

    alembic upgrade head      # apply
alembic downgrade -1      # verify rollback works
alembic upgrade head      # re-apply

  5. 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-timeout and offline strategy

Output

Report: migration filename, what it does, whether downgrade was tested, any risks.

From the file to a first result

The download contains exactly the content displayed on this page. This copy may differ from the latest version in the source repository.

View the source and supporting files

This download contains SKILL.md only. Any scripts, references, templates and dependencies are not included. Get the required files from the source, preserving their directory structure, before continuing.

1. Download the file

Download SKILL.md

From the root of a test project, save the file as .skill-downloads/db-migration-mryiqfzq/SKILL.md, or use the command below. This folder is for inspecting the skill before installation.

Command for macOS/Linux or WSL: requires a POSIX shell and curl. On Windows without WSL, use the download button and create the folder manually.

mkdir -p '.skill-downloads/db-migration-mryiqfzq' && curl --fail --show-error --location 'https://skills-guides.com/api/skills/db-migration-mryiqfzq/download' --output '.skill-downloads/db-migration-mryiqfzq/SKILL.md.part' && mv '.skill-downloads/db-migration-mryiqfzq/SKILL.md.part' '.skill-downloads/db-migration-mryiqfzq/SKILL.md'

2. Check prerequisites

Read SKILL.md before using it. If it references scripts or external services, inspect them and prepare the required access in your test environment.

No recognized prerequisites section in this file. This does not mean it is self-contained: libraries, tools and access requirements may be mentioned elsewhere in the content or source repository.

The platforms on this page are catalog indications. The paths below follow tool documentation; they do not prove this skill has been run in those tools. No minimum tool version is confirmed for this listing.

3. Load the skill

This file does not provide a usable name/description header for this native procedure. It remains available to download and inspect; use the manual method below.

Manual method or another tool: attach SKILL.md to a conversation, or open it in an agent that can read files. Include any required supporting resources. No universal folder is recognized by every tool.

4. Try a first task

Use a short, synthetic input: an API endpoint, a small document or an interface brief. In a new conversation, attach the file or give the agent its path, then adapt this request:

Read .skill-downloads/db-migration-mryiqfzq/SKILL.md and apply its instructions to this example: [describe a test input]. Identify any missing files, dependencies or access. Produce the result requested by the skill without inventing data or running unreviewed scripts.

Expected result: output matching the skill instructions, or a precise list of missing prerequisites. A read confirmation alone does not validate a first use. If an external resource is unavailable, that path remains untested.

Related skills

React Hook Form Best Practices

Development

Master React Hook Form: avoid anti-patterns, manage subscriptions, and handle reset, dirty state, and controlled inputs correctly.

Claude CodeCursorWindsurf+2intermediateSafe 108,623
Skills Guide Bot

Emotion to Mantine Migration

Development

Migrate Emotion styled-components to Mantine components with style props and CSS modules. Use when converting .styled.tsx files or removing @emotion imports.

Claude CodeCursorWindsurf+1intermediateSafe 48,981
Skills Guide Bot

Scope Creep Detector

Development

Analyzes git diffs against a stated intent to detect scope creep, unrelated files, broad PRs, and oversized changes, then suggests keep, split, or justify actions.

Claude CodeCursorCodexintermediateSafe 135,015
Skills Guide Bot