Guidance requested: integrated Alembic migration CLI dependencies

[vmskonakanchi]

Hi maintainers,

I revived the work from #689 against current main in #2061. The implementation adds a sqlmodel migrations CLI with Alembic commands and documentation. The test matrix passed, but #2061 was closed automatically because it modifies pyproject.toml and uv.lock.

The feature needs Alembic and Typer available at runtime for the console command. Before proposing it again, could you advise which packaging direction you prefer?

1. Make Alembic and Typer core runtime dependencies.
2. Expose the migration CLI through an optional dependency extra.
3. Keep migrations as documented integration/template guidance rather than a SQLModel CLI.

The updated implementation preserves the current PDM/uv setup and current CI, and replaces the original deprecated entry-point loader with importlib.metadata. I am happy to adapt the PR to the preferred design.

Thanks!

[amasen02]

Architectural & Packaging Guidance

To give you a clear direction before reopening the PR, here is how Tiangolo's ecosystem (FastAPI, SQLModel, Typer) typically resolves this dilemma, along with why your PR was automatically closed:

---

1. Which Packaging Direction?

❌ Direction 1: Core Runtime Dependencies (Not Recommended)

Making alembic and typer mandatory runtime dependencies goes against the design principles of SQLModel:

• SQLModel is fundamentally a lightweight bridge between SQLAlchemy and Pydantic.
• Many deployments (serverless functions, microservices reading from existing DBs, data analysis scripts, SQLite in-memory testing) do not execute migrations at runtime.
• Forcing alembic and typer on all installs adds unnecessary bloat and potential version conflict surface.

💡 Direction 2: Optional Dependency Extra (sqlmodel[migrations]) (Best for CLI Feature)

If the maintainers want an integrated CLI, the standard approach used across Tiangolo projects (similar to fastapi[standard] or uvicorn[standard]) is an optional extra:

# pyproject.toml
[project.optional-dependencies]
migrations = [
    "alembic >= 1.13.0",
    "typer >= 0.12.0",
]

In the CLI entry point / command handler, guard the import with a friendly instruction:

try:
    import alembic
    import typer
except ImportError:
    raise RuntimeError(
        "To use migration commands, install SQLModel with migration dependencies:\n"
        "  pip install \"sqlmodel[migrations]\""
    )

📖 Direction 3: Official Documentation & env.py Guidance (Lowest Maintenance)

It is also worth noting that Alembic already provides a battle-tested CLI (alembic init, alembic revision --autogenerate, alembic upgrade head). In practice, integrating SQLModel with Alembic requires only a 2-line adjustment in alembic/env.py:

from sqlmodel import SQLModel
import my_app.models  # ensure models are registered in metadata

target_metadata = SQLModel.metadata

Wrapping Alembic commands inside a custom sqlmodel proxy CLI often incurs ongoing maintenance overhead as Alembic options and configuration evolve. Maintaining rich documentation or a template guide is often favored by maintainers for this reason.

---

2. Why your PR was automatically closed & How to avoid it

Tiangolo repositories utilize automated CI bots that strictly reject external PRs modifying lockfiles (uv.lock or pdm.lock). This is a security and supply-chain policy:

• Never commit changes to uv.lock in your PR.
• Only update pyproject.toml (adding [project.optional-dependencies] or documentation).
• Allow the repository maintainers' release workflow to regenerate lockfiles upon merge.