Alembic Migration
Developmentalembic-migrationAlembic Migration is an Agent Skill for development published in the vstorm-co/full-stack-ai-agent-template repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/vstorm-co/full-stack-ai-agent-template/blob/HEAD/template/{{cookiecutter.project_slug}}/.claude/skills/alembic-migration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/alembic-migration, but wait for my approval before writing files or running scripts.Copying this prompt does not install or run the skill. Review third-party files before use.
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 withondelete="CASCADE"). Make sure the model is imported inbackend/app/db/models/__init__.pyso 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 anddowngrade()actually reverses it. - Check the
down_revisionchains 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.
- Confirm
-
Apply and verify:
cd backend && uv run alembic upgrade head # or: make db-upgrade uv run alembic current # confirm at headThen 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 bootstraprunalembic upgrade headautomatically; 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.