Database Migrations with Alembic in FastAPI 2026

Database Migrations with Alembic in FastAPI 2026

Database migrations are essential for evolving your schema safely over time. In 2026, using Alembic with SQLModel and async support has become the standard way to manage database changes in FastAPI applications.

TL;DR — Key Takeaways 2026

• Use Alembic for version-controlled database schema changes
• Combine Alembic with SQLModel for type-safe models
• Always run migrations in a controlled environment
• Use revision heads and branches for complex deployments
• Automate migrations in your CI/CD pipeline

1. Project Setup with Alembic

# Initialize Alembic
alembic init migrations

# Update alembic.ini
sqlalchemy.url = postgresql+asyncpg://user:pass@localhost/dbname

2. Modern env.py Configuration

# migrations/env.py
from logging.config import fileConfig
from sqlalchemy.ext.asyncio import AsyncEngine
from sqlmodel import SQLModel
from alembic import context

config = context.config
target_metadata = SQLModel.metadata

def run_migrations_online():
    connectable = AsyncEngine(...)  # your async engine

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            compare_type=True,
            compare_server_default=True,
        )

        with context.begin_transaction():
            context.run_migrations()

3. Creating and Running Migrations

# Create a new migration
alembic revision --autogenerate -m "add user table"

# Review and edit the generated migration file
# Then apply it
alembic upgrade head

# Downgrade if needed
alembic downgrade -1

4. Best Practices in 2026

• Always review autogenerated migrations before applying
• Use meaningful migration messages
• Include both upgrade and downgrade logic
• Run migrations in a separate step during deployment
• Use branches for complex schema changes
• Combine with database seeding scripts when needed

Conclusion

Alembic provides robust, version-controlled database migrations that integrate beautifully with SQLModel and FastAPI. In 2026, a well-managed migration strategy is a hallmark of professional backend development, allowing safe schema evolution without downtime or data loss.

Next steps:

• Set up Alembic migrations in your FastAPI projects following these patterns
• Related articles: FastAPI Project Structure Best Practices 2026 • Async Database Operations with SQLModel in FastAPI 2026