alembic-migration

name

alembic-migration

description

Generate Alembic database migrations for SQLModel/SQLAlchemy with async PostgreSQL. Use when: (1) Creating new migration files, (2) Setting up Alembic in a project, (3) Handling schema changes (add/drop columns, tables, indexes), (4) Data migrations, (5) Multi-tenant or multi-database migrations. Generates async-compatible migrations with proper upgrade/downgrade functions. NOT for Django migrations or raw SQL scripts.

Alembic Migration Generator

Generate database migrations for FastAPI services using Alembic, SQLModel, and asyncpg.

Quick Reference

Command	Purpose
/alembic-migration init	Set up Alembic in a new service
/alembic-migration create <name>	Generate new migration file
/alembic-migration autogenerate	Auto-detect model changes

Project Setup

1. Initialize Alembic (First Time Only)

Create alembic/ directory structure:

service/
├── alembic/
│   ├── versions/           # Migration files
│   ├── env.py              # Alembic environment config
│   └── script.py.mako      # Migration template
├── alembic.ini             # Alembic configuration
└── models/
    └── __init__.py         # SQLModel definitions

2. alembic.ini

[alembic]
script_location = alembic
prepend_sys_path = .
version_path_separator = os

[post_write_hooks]
hooks = ruff
ruff.type = exec
ruff.executable = ruff
ruff.options = format REVISION_SCRIPT_FILENAME

[loggers]
keys = root,sqlalchemy,alembic

[handlers]
keys = console

[formatters]
keys = generic

[logger_root]
level = WARN
handlers = console

[logger_sqlalchemy]
level = WARN
handlers =
qualname = sqlalchemy.engine

[logger_alembic]
level = INFO
handlers =
qualname = alembic

[handler_console]
class = StreamHandler
args = (sys.stderr,)
level = NOTSET
formatter = generic

[formatter_generic]
format = %(levelname)-5.5s [%(name)s] %(message)s
datefmt = %H:%M:%S

3. env.py (Async)

See references/env-async.md for complete async env.py template.

4. script.py.mako

"""${message}

Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa
import sqlmodel
${imports if imports else ""}

# revision identifiers
revision: str = ${repr(up_revision)}
down_revision: Union[str, None] = ${repr(down_revision)}
branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}


def upgrade() -> None:
    ${upgrades if upgrades else "pass"}


def downgrade() -> None:
    ${downgrades if downgrades else "pass"}

Creating Migrations

Auto-generate from Model Changes

alembic revision --autogenerate -m "add users table"

Manual Migration

alembic revision -m "add custom index"

Migration Patterns

See references for specific patterns:

• Schema changes: See references/schema-changes.md
• Data migrations: See references/data-migrations.md
• Indexes & constraints: See references/indexes.md

Running Migrations

# Upgrade to latest
alembic upgrade head

# Upgrade to specific revision
alembic upgrade abc123

# Downgrade one revision
alembic downgrade -1

# Show current revision
alembic current

# Show history
alembic history --verbose

Dependencies

[project]
dependencies = [
    "alembic>=1.13.0",
    "sqlmodel>=0.0.22",
    "asyncpg>=0.29.0",
    "greenlet>=3.0.0",  # Required for async
]

Environment Variables

DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/dbname