How do I install the Alembic Migration skill?

Run npx skillmds@latest add vstorm-co/alembic-migration-2 in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Alembic Migration safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Alembic Migration?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Alembic Migration free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Alembic Migration?

vstorm-co (@vstorm-co) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Alembic Migration by vstorm-co — Agent Skill

Name: Alembic Migration
Author: vstorm-co

Alembic Migration

Create, review, and apply database schema changes with Alembic. Use whenever a SQLAlchemy model is added or changed, a column/index/constraint needs to change, or a data backfill is required — anything that alters the PostgreSQL schema.

vstorm-co Updated Sep 22, 2026

File contents

Alembic Migrations

This project uses async SQLAlchemy 2.0 + Alembic on PostgreSQL. Migrations live in backend/alembic/versions/ and are numbered (0001_…, 0002_…).

Workflow

Change the model first in backend/app/db/models/ (Mapped[...] + mapped_column(), __repr__, relationships with ondelete="CASCADE"). Make sure the model is imported in backend/app/db/models/__init__.py so autogenerate sees it.

Autogenerate the migration:

cd backend && uv run alembic revision --autogenerate -m "add <thing>"
# or: make db-migrate

ALWAYS review the generated file. Autogenerate is a draft, not the truth:
- Confirm upgrade() matches your intent and downgrade() actually reverses it.
- Check the down_revision chains onto the current head (uv run alembic heads).
- Watch for dropped columns/tables you didn't intend, server defaults, enum changes, and JSON/array types.
- Name the revision file with the next sequential prefix to match the existing convention.

Apply and verify:

cd backend && uv run alembic upgrade head   # or: make db-upgrade
uv run alembic current                       # confirm at head

Then round-trip once to prove downgrade() works: alembic downgrade -1 && alembic upgrade head.

Data migrations / backfills

For backfills, add explicit op.execute(...) or a small data-loop in upgrade() (see the existing *_backfill_*.py migrations for the pattern). Keep schema and data changes in separate, well-named revisions when practical.

Rules

Never edit a migration that has already been applied in shared environments — add a new one.
make dev / make bootstrap run alembic upgrade head automatically; you don't need a separate step in dev.
Keep models and migrations in sync — a model change without a migration will pass tests (sessions are mocked) but break on real Postgres.

---name: alembic-migration-2description: Create, review, and apply database schema changes with Alembic. Use whenever a SQLAlchemy model is added or changed, a column/index/constraint needs to change, or a data backfill is required — anything that alters the PostgreSQL schema.---# Alembic MigrationsThis project uses **async SQLAlchemy 2.0 + Alembic** on PostgreSQL. Migrations live in `backend/alembic/versions/` and are numbered (`0001_…`, `0002_…`).## Workflow1. **Change the model first** in `backend/app/db/models/` (`Mapped[...]` + `mapped_column()`, `__repr__`, relationships with `ondelete="CASCADE"`). Make sure the model is imported in `backend/app/db/models/__init__.py` so autogenerate sees it.2. **Autogenerate** the migration: ```bash cd backend && uv run alembic revision --autogenerate -m "add <thing>" # or: make db-migrate ```3. **ALWAYS review the generated file.** Autogenerate is a draft, not the truth: - Confirm `upgrade()` matches your intent and `downgrade()` actually reverses it. - Check the `down_revision` chains onto the current head (`uv run alembic heads`). - Watch for dropped columns/tables you didn't intend, server defaults, enum changes, and JSON/array types. - Name the revision file with the next sequential prefix to match the existing convention.4. **Apply and verify:** ```bash cd backend && uv run alembic upgrade head # or: make db-upgrade uv run alembic current # confirm at head ``` Then round-trip once to prove `downgrade()` works: `alembic downgrade -1 && alembic upgrade head`.## Data migrations / backfillsFor backfills, add explicit `op.execute(...)` or a small data-loop in `upgrade()` (see the existing `*_backfill_*.py` migrations for the pattern). Keep schema and data changes in separate, well-named revisions when practical.## Rules- Never edit a migration that has already been applied in shared environments — add a new one.- `make dev` / `make bootstrap` run `alembic upgrade head` automatically; you don't need a separate step in dev.- Keep models and migrations in sync — a model change without a migration will pass tests (sessions are mocked) but break on real Postgres.

Frequently asked questions