fastapi-alembic-migrations

Configure Alembic migrations for SQLAlchemy 2.0 async projects with async-ready env.py templates.

Updated Jan 24, 2026
One-click install
npx skills add https://github.com/amaozhao/MySkills --skill fastapi-alembic-migrations
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: fastapi-alembic-migrations
Source: https://github.com/amaozhao/MySkills/tree/main/skills/fastapi-alembic-migrations
Command: npx skills add https://github.com/amaozhao/MySkills --skill fastapi-alembic-migrations

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill provides a ready-to-use configuration for integrating Alembic migrations with SQLAlchemy 2.0 in asynchronous projects, addressing the challenge of running migrations in async environments and ensuring compatibility with FastAPI apps.

Core Features & Use Cases

  • Async-ready Alembic setup for SQLAlchemy 2.0 with auto-detection of models.
  • Custom env.py template that uses async engines and proper target_metadata.
  • Use Case: Initialize migrations in a new FastAPI project using async SQLAlchemy and apply migrations without blocking.

Quick Start

Initialize Alembic for an async project and adapt env.py to use an async engine, then generate and apply migrations with the usual alembic commands.

Frequently Asked Questions about fastapi-alembic-migrations

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

FAQPage Schema
How do I run Alembic migrations with async SQLAlchemy in FastAPI?

To run Alembic migrations with async SQLAlchemy, you need an async-ready env.py that configures an async engine and sets target_metadata for autogenerate. This setup enables generating and applying migrations without blocking the FastAPI event loop.

Why does alembic revision fail with an async engine?

Alembic revision fails with an async engine because the default env.py uses synchronous database connections. You must adapt env.py to use async engine configuration and proper model import hooks for autogenerate to function in asynchronous contexts.

How do I set up initial Alembic migrations in a new FastAPI project using async SQLAlchemy 2.0?

Setting up initial Alembic migrations involves configuring Alembic for SQLAlchemy 2.0 async projects with a custom env.py template. This enables auto-detection of models and allows you to apply initial migrations using standard alembic commands without blocking.

Does Alembic support auto-detection of models in an asynchronous FastAPI project?

Yes, Alembic supports auto-detection of models in asynchronous projects when configured with an async-ready env.py. It uses model import hooks and proper target_metadata to ensure automatic formatting and model discovery for autogenerate.

What is the best way to configure Alembic for SQLAlchemy 2.0 async projects?

The best way to configure Alembic for SQLAlchemy 2.0 async projects is using an async-ready env.py template that establishes an async engine and proper target_metadata. This ensures compatibility with FastAPI and enables non-blocking migrations.

Can I use standard alembic commands to apply migrations in an async FastAPI environment?

Yes, you can use standard alembic commands to apply migrations in an async FastAPI environment once env.py is adapted to use an async engine. This configuration allows generating and applying migrations without blocking the application.