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: