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.

[vansh070605]

I think option 2, an optional dependency extra, would be a reasonable approach.

Alembic is useful for production SQLModel applications, but it isn't required by SQLModel itself. SQLModel can be used without migrations, so making Alembic and Typer core dependencies would add packages to every SQLModel installation, including users who don't use the migration CLI.

An optional extra would keep the base installation lightweight while still providing a first-party workflow, for example:

pip install "sqlmodel[migrations]"

or the equivalent with `uv`.

I also think this fits reasonably well with the current documentation. The SQLModel docs describe migrations as something that is generally useful for production applications, rather than as a requirement for using SQLModel.

One thing I would clarify before implementing the CLI is whether the goal is to provide a stable SQLModel-specific migration abstraction, or mainly a convenient wrapper around Alembic. If it is primarily a wrapper around Alembic, keeping it behind an optional dependency seems like the least invasive approach.

[vmskonakanchi]

Thanks @amasen02 and @vansh070605 for the guidance.

I've reworked the implementation to follow the optional-extra direction (option 2):

• alembic and typer moved from core dependencies to a migrations optional extra, so the base install stays lightweight and users opt in with pip install "sqlmodel[migrations]".
• Guarded CLI imports that show a friendly install hint instead of a raw ModuleNotFoundError when the extra is missing.
• No uv.lock changes (left for the maintainers' release workflow to regenerate on merge).

On the design question @vansh070605 raised: the CLI is intentionally a thin, typed wrapper around alembic.command exposed through Typer, not a SQLModel-specific migration abstraction. It just provides a first-party sqlmodel migrations ... entry point and template wiring; the underlying behaviour stays Alembic's.

One blocker I want to surface: the auto-close bot rejects any change to pyproject.toml, not only uv.lock. I opened a reworked PR that adds only the optional extra (no lockfile change) and it was still auto-closed, because declaring the extra necessarily edits pyproject.toml. Since an installable CLI has to declare its dependencies somewhere, this part can't land through an external PR without a maintainer.

Could a maintainer confirm whether the optional-extra approach is acceptable, and if so help land the pyproject.toml change (or advise the preferred path)? This is a roadmap item (#654) and continues the work in #689. Happy to adjust scope or design as preferred.

[vansh070605]

The thin wrapper approach around alembic.command with guarded imports makes complete sense here.

To get around the bot auto-closing on pyproject.toml changes, a common workaround is to open a PR containing only the code and tests (making sure CLI tests gracefully skip or mock if the dependencies aren't present in CI), leaving pyproject.toml unmodified. You can provide the required [project.optional-dependencies] diff directly in the PR description for the maintainer to commit upon merge.

This gets the actual implementation reviewed without triggering the supply-chain security bot.