alembic

Generates, reviews, and applies Alembic database migrations for SQLModel models.

Updated Sep 13, 2026
One-click install
npx skills add https://github.com/abdulazeezoj/monovella-poc --skill alembic-abdulazeezoj
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: alembic
Source: https://github.com/abdulazeezoj/monovella-poc/tree/main/.agents/skills/alembic
Command: npx skills add https://github.com/abdulazeezoj/monovella-poc --skill alembic-abdulazeezoj

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Database schema changes in this project must be captured as versioned Alembic migrations, but autogenerate can silently produce empty migrations, miss models, or conflict with tables created outside migration history. This Skill documents the project's specific Alembic setup and its two real failure modes so migrations are generated and applied correctly. ## Core Features & Use Cases - Migration generation and application: Run uv run alembic revision --autogenerate and uv run alembic upgrade head against the project's async SQLModel setup, with the database URL wired from settings.database_url. - Gotcha diagnosis: Explains the prepend_sys_path = src import requirement and the create_all()-outside-migrations bug that makes autogenerate report "No changes detected". - Migration review guidance: Shows what a generated migration file looks like and what to check before applying it, including rename drop/add traps and downgrade correctness. - Use Case: After adding an email column to the Item model in src/api/models.py, generate a migration, review the generated op.add_column call, and apply it with alembic upgrade head before starting the app. ## Quick Start Ask the assistant to generate and apply an Alembic migration for a model change you just made in src/api/models.py.

Frequently Asked Questions about alembic

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create an Alembic migration after changing a SQLModel model?

Run `uv run alembic revision --autogenerate -m "describe your change"` to diff the models against the last-known schema and write a migration file, then `uv run alembic upgrade head` to apply it. Always review the generated file before applying.

Why does alembic autogenerate say no changes detected?

This usually means tables were created outside migration history, for example by a `SQLModel.metadata.create_all()` call at app startup, so the live database already matches the models. It can also mean the model is not importable from env.py, so autogenerate never sees it.

How do I fix ModuleNotFoundError: No module named 'api' in Alembic?

Set `prepend_sys_path = src` in alembic.ini so env.py's `from api...` imports resolve in a src-layout project. Without it, autogenerate either fails outright or silently imports a stale installed copy of the package.

Can Alembic autogenerate detect column renames?

No. Autogenerate treats a rename as a drop plus an add, which destroys existing data in the old column. Hand-edit the migration to use `op.alter_column("table", "old", new_column_name="new")` instead.

How do I roll back an Alembic migration?

Run `uv run alembic downgrade -1` to undo exactly one revision by executing its `downgrade()` function. Use `alembic history` to see the full revision chain and `alembic current` to check which revision the database is on.