fix(fastapi): support Typer 0.26 CLI registration (#748)

## Summary

- Updates the FastAPI CLI integration for Typer 0.26+, where Typer
vendors Click and no longer accepts external `click.Group` objects
through `TyperGroup.add_command()`.
- Keeps `register_database_commands(app)` returning the existing Click
migration command group, matching the existing adapter naming pattern.
- Routes FastAPI CLI registration through `assign_cli_group(app)`, with
an internal Typer bridge that exposes both `database` and `db` and
delegates to the existing Click commands.
- Updates FastAPI examples to use the public `assign_cli_group(app)`
adapter surface.
- Includes the current dependency/version bump that exposed the Typer
0.26 compatibility issue.

Author: cofin

.github/workflows/ci.yml

@@ -180,6 +180,9 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras --dev
 
+      - name: Test docs examples
+        run: uv run make docs-test
+
       - name: Build docs
         run: uv run make docs
 

advanced_alchemy/extensions/fastapi/extension.py

@@ -38,13 +38,36 @@
 
 def assign_cli_group(app: "FastAPI") -> None:  # pragma: no cover
     try:
+        import typer
+        from click import ClickException
+        from click.exceptions import Exit as ClickExit
         from fastapi_cli.cli import app as fastapi_cli_app  # pyright: ignore[reportUnknownVariableType]
-        from typer.main import get_group
     except ImportError:
         print("FastAPI CLI is not installed.  Skipping CLI registration.")  # noqa: T201
         return
-    click_app = get_group(fastapi_cli_app)  # pyright: ignore[reportUnknownArgumentType]
-    click_app.add_command(register_database_commands(app))
+
+    def run_database_command(ctx: typer.Context) -> None:
+        database_group = register_database_commands(app)
+        args = list(ctx.args) or ["--help"]
+        try:
+            database_group.main(
+                args=args,
+                prog_name=ctx.info_name or database_group.name,
+                standalone_mode=False,
+            )
+        except ClickExit as e:
+            raise typer.Exit(e.exit_code) from e
+        except ClickException as e:
+            e.show()
+            raise typer.Exit(e.exit_code) from e
+
+    for name in ("database", "db"):
+        fastapi_cli_app.command(
+            name=name,
+            help="Manage SQLAlchemy database components.",
+            context_settings={"allow_extra_args": True, "ignore_unknown_options": True, "help_option_names": []},
+            add_help_option=False,
+        )(run_database_command)
 
 
 class AdvancedAlchemy(StarletteAdvancedAlchemy):

docs/PYPI_README.md

@@ -38,7 +38,7 @@ offering:
     - Unified interface for various storage backends ([`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/) and [`obstore`](https://developmentseed.org/obstore/latest/))
     - Optional lifecycle event hooks integrated with SQLAlchemy's event system to automatically save and delete files as records are inserted, updated, or deleted.
 - Optimized JSON types including a custom JSON type for Oracle
-- Integrated support for UUID6 and UUID7 using [`uuid-utils`](https://github.com/aminalaee/uuid-utils) (install with the `uuid` extra)
+- Integrated support for UUID6 and UUID7 ([`uuid-utils`](https://github.com/aminalaee/uuid-utils) when installed, otherwise native in Python 3.14+, with UUID4 fallback on older versions).
 - Integrated support for Nano ID using [`fastnanoid`](https://github.com/oliverlambson/fastnanoid) (install with the `nanoid` extra)
 - Custom encrypted text type with multiple backend support including [`pgcrypto`](https://www.postgresql.org/docs/current/pgcrypto.html) for PostgreSQL and the Fernet implementation from [`cryptography`](https://cryptography.io/en/latest/) for other databases
 - Custom password hashing type with multiple backend support including [`Argon2`](https://github.com/P-H-C/phc-winner-argon2), [`Passlib`](https://passlib.readthedocs.io/en/stable/), and [`Pwdlib`](https://pwdlib.readthedocs.io/en/stable/) with automatic salt generation

examples/fastapi/fastapi_filters.py

@@ -85,10 +85,8 @@ async def list_authors(
     Run `uv run examples/fastapi/fastapi_service.py` to launch the FastAPI CLI with the database commands registered
     """
     from fastapi_cli.cli import app as fastapi_cli_app  # pyright: ignore[reportUnknownVariableType]
-    from typer.main import get_group
 
-    from advanced_alchemy.extensions.fastapi.cli import register_database_commands
+    from advanced_alchemy.extensions.fastapi import assign_cli_group
 
-    click_app = get_group(fastapi_cli_app)  # pyright: ignore[reportUnknownArgumentType]
-    click_app.add_command(register_database_commands(app))
-    click_app()
+    assign_cli_group(app)
+    fastapi_cli_app()

examples/fastapi/fastapi_service.py

@@ -140,10 +140,8 @@ async def delete_author(
     Run `uv run examples/fastapi/fastapi_service.py --help` to launch the FastAPI CLI with the database commands registered
     """
     from fastapi_cli.cli import app as fastapi_cli_app  # pyright: ignore[reportUnknownVariableType]
-    from typer.main import get_group
 
-    from advanced_alchemy.extensions.fastapi.cli import register_database_commands
+    from advanced_alchemy.extensions.fastapi import assign_cli_group
 
-    click_app = get_group(fastapi_cli_app)  # pyright: ignore[reportUnknownArgumentType]
-    click_app.add_command(register_database_commands(app))
-    click_app()
+    assign_cli_group(app)
+    fastapi_cli_app()

examples/fastapi/fastapi_service_full.py

@@ -191,10 +191,8 @@ async def delete_author(
     Run `uv run examples/fastapi/fastapi_service.py --help` to launch the FastAPI CLI with the database commands registered
     """
     from fastapi_cli.cli import app as fastapi_cli_app  # pyright: ignore[reportUnknownVariableType]
-    from typer.main import get_group
 
-    from advanced_alchemy.extensions.fastapi.cli import register_database_commands
+    from advanced_alchemy.extensions.fastapi import assign_cli_group
 
-    click_app = get_group(fastapi_cli_app)  # pyright: ignore[reportUnknownArgumentType]
-    click_app.add_command(register_database_commands(app))
-    click_app()
+    assign_cli_group(app)
+    fastapi_cli_app()

pyproject.toml

@@ -46,7 +46,7 @@ maintainers = [
 name = "advanced_alchemy"
 readme = "docs/PYPI_README.md"
 requires-python = ">=3.9"
-version = "1.10.0"
+version = "1.11.0"
 
 [project.urls]
 Changelog = "https://advanced-alchemy.litestar.dev/latest/changelog"
@@ -178,7 +178,7 @@ test = [
 allow_dirty = true
 commit = false
 commit_args = "--no-verify"
-current_version = "1.10.0"
+current_version = "1.11.0"
 ignore_missing_files = false
 ignore_missing_version = false
 message = "chore(release): bump to v{new_version}"

tests/unit/test_extensions/test_fastapi/test_extension.py

@@ -1,17 +1,21 @@
 import sys
+import types
 from collections.abc import AsyncGenerator, Generator
 from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING, Annotated, Callable, Literal, Union, cast
 from unittest.mock import MagicMock
 
+import click as base_click
 import pytest
+import typer
 from fastapi import Depends, FastAPI, HTTPException, Request, Response
 from fastapi.testclient import TestClient
 from pytest import FixtureRequest
 from pytest_mock import MockerFixture
 from sqlalchemy import Engine
 from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
 from sqlalchemy.orm import Session
+from typer.testing import CliRunner
 from typing_extensions import assert_type
 
 from advanced_alchemy.exceptions import ImproperConfigurationError
@@ -55,6 +59,77 @@ def alchemy(config: AnyConfig, app: FastAPI) -> AdvancedAlchemy:
     return AdvancedAlchemy(config, app=app)
 
 
+def _install_fastapi_cli_app(monkeypatch: pytest.MonkeyPatch, typer_app: typer.Typer) -> None:
+    fastapi_cli = types.ModuleType("fastapi_cli")
+    fastapi_cli_cli = types.ModuleType("fastapi_cli.cli")
+    fastapi_cli_cli.app = typer_app
+    setattr(fastapi_cli, "cli", fastapi_cli_cli)
+    monkeypatch.setitem(sys.modules, "fastapi_cli", fastapi_cli)
+    monkeypatch.setitem(sys.modules, "fastapi_cli.cli", fastapi_cli_cli)
+
+
+def test_assign_cli_group_delegates_database_and_db(monkeypatch: pytest.MonkeyPatch) -> None:
+    from advanced_alchemy.extensions.fastapi import extension as fastapi_extension
+    from advanced_alchemy.extensions.fastapi.extension import assign_cli_group
+
+    seen: list[tuple[FastAPI, str]] = []
+
+    def fake_register_database_commands(app: FastAPI) -> base_click.Group:
+        @base_click.group(name="database")
+        def database_group() -> None:
+            pass
+
+        @database_group.command(name="upgrade")
+        @base_click.argument("revision", default="head")
+        def upgrade_database(revision: str) -> None:
+            seen.append((app, revision))
+
+        return database_group
+
+    monkeypatch.setattr(fastapi_extension, "register_database_commands", fake_register_database_commands)
+    app = FastAPI()
+    typer_app = typer.Typer(context_settings={"help_option_names": ["-h", "--help"]})
+    _install_fastapi_cli_app(monkeypatch, typer_app)
+
+    assign_cli_group(app)
+
+    runner = CliRunner()
+    result = runner.invoke(typer_app, ["database", "upgrade", "abc123"])
+    alias_result = runner.invoke(typer_app, ["db", "upgrade"])
+
+    assert result.exit_code == 0, result.output
+    assert alias_result.exit_code == 0, alias_result.output
+    assert seen == [(app, "abc123"), (app, "head")]
+
+
+def test_assign_cli_group_delegates_database_help(monkeypatch: pytest.MonkeyPatch) -> None:
+    from advanced_alchemy.extensions.fastapi import extension as fastapi_extension
+    from advanced_alchemy.extensions.fastapi.extension import assign_cli_group
+
+    def fake_register_database_commands(app: FastAPI) -> base_click.Group:
+        @base_click.group(name="database")
+        def database_group() -> None:
+            pass
+
+        @database_group.command(name="upgrade")
+        def upgrade_database() -> None:
+            pass
+
+        return database_group
+
+    monkeypatch.setattr(fastapi_extension, "register_database_commands", fake_register_database_commands)
+    app = FastAPI()
+    typer_app = typer.Typer(context_settings={"help_option_names": ["-h", "--help"]})
+    _install_fastapi_cli_app(monkeypatch, typer_app)
+    assign_cli_group(app)
+
+    result = CliRunner().invoke(typer_app, ["database", "--help"])
+
+    assert result.exit_code == 0, result.output
+    assert "Commands:" in result.output
+    assert "upgrade" in result.output
+
+
 async def test_infer_types_from_config(async_config: SQLAlchemyAsyncConfig, sync_config: SQLAlchemySyncConfig) -> None:
     if TYPE_CHECKING:
         alchemy = AdvancedAlchemy(config=[async_config, sync_config])