Summary

This carries forward the Alembic migration CLI from #689 against current main, with the packaging concerns from #2062 resolved. It supersedes #2061, which was auto-closed for modifying dependency files.

It adds an optional sqlmodel migrations CLI (thin, typed wrappers around alembic.command, exposed via Typer) plus documentation, and lays the groundwork for an extensible sqlmodel CLI via entry points.

Packaging changes (addressing why #2061 was closed)

Following the guidance in discussion #2062:

• Optional extra instead of core dependencies. alembic and typer are now under [project.optional-dependencies] as a migrations extra, so the base sqlmodel install stays lightweight. Users opt in with pip install "sqlmodel[migrations]".
• No lockfile changes. uv.lock is unchanged in this PR; it can be regenerated by the maintainers' release workflow on merge.
• Guarded imports. If the extra is not installed, the CLI raises a friendly message telling the user to install sqlmodel[migrations] rather than a raw ModuleNotFoundError.

CLI structure

sqlmodel
└── migrations
    ├── init
    ├── revision
    ├── show
    ├── merge
    ├── upgrade
    └── downgrade

Docs

• Adds an advanced migrations guide with an Installation section covering the migrations extra.

Validation

• uv run pytest tests/test_cli — passes (6 tests)
• uv run ruff check sqlmodel/cli tests/test_cli — passes
• uv run sqlmodel migrations --help — lists all commands
• Verified the guarded import shows the friendly install message when typer is unavailable

Context

• Supersedes Add Alembic migration CLI integration #2061 (auto-closed)
• Continues Alembic integration and documentation #689
• Discussion: Guidance requested: integrated Alembic migration CLI dependencies #2062
• Roadmap item: 🚀 Roadmap #654

Happy to adapt the design (e.g. wrapper vs. abstraction scope) based on maintainer preference.