alembic — SKILL.md

Variant: standard · When to use: the skill is invoked, produces wired Alembic config + a reviewed migration script (or the relevant slice), and control returns to the caller.

Overview

This skill teaches an agent to run Alembic schema migrations on top of an existing SQLAlchemy 2.x data layer, across SQLite, PostgreSQL, and MySQL from one migration history. It assumes a working Base.metadata already exists (that is the sibling sqlalchemy skill's job) and wires Alembic to it. The primary path is sync — the standard run_migrations_online() shape on a sync connection — with a short async aside. Two pieces are load-bearing: (1) autogenerate drafts, you review — it has documented blind spots that cause silent data loss if applied blindly; and (2) the SQLite batch / move-and-copy gotcha — SQLite can't ALTER most things, so migrations are written in batch_alter_table style that recreates the table on SQLite while emitting ordinary ALTER on PG/MySQL. This skill also owns the create_all() vs Alembic decision and the baseline-stamp path for adopting Alembic on an already-created database.

When to activate

• ✅ Wiring Alembic (env.py + alembic.ini) to an existing SQLAlchemy Base.metadata so autogenerate can diff the live schema against your models.
• ✅ Authoring a migration — empty (revision) or drafted (revision --autogenerate) — and reviewing/editing it before applying.
• ✅ Running upgrade / downgrade, inspecting history / current / heads, or resolving multiple heads with merge.
• ✅ Writing ONE migration that must apply on SQLite, PostgreSQL, and MySQL — reaching for batch (move-and-copy) operations.
• ✅ Deciding Base.metadata.create_all() vs Alembic for a project, or stamping a baseline to adopt Alembic on a create_all'd database.

Do NOT activate when: