Global fallback for fastapi

Author: abondar

examples/fastapi/_tests.py

@@ -57,8 +57,12 @@ async def client() -> ClientManagerType:
 
 @pytest.fixture(scope="module")
 async def client_east() -> ClientManagerType:
+    # app_east uses _enable_global_fallback=False, so we need to explicitly
+    # enter the context from app.state to make it current for tests
     async with client_manager(app_east) as c:
-        yield c
+        ctx = app_east.state._tortoise_context
+        with ctx:  # Enter context to make it current via contextvar
+            yield c
 
 
 class UserTester:

examples/fastapi/main_custom_timezone.py

@@ -10,11 +10,14 @@
 @asynccontextmanager
 async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     # app startup
+    # Disable global fallback since this is the secondary app in tests
+    # (main app already uses global fallback). Context is stored in app.state.
     async with register_orm(
         app,
         use_tz=False,
         timezone="Asia/Shanghai",
         add_exception_handlers=True,
+        _enable_global_fallback=False,
     ):
         # db connected
         yield

tests/contrib/test_fastapi.py

@@ -31,6 +31,7 @@ async def test_await(
         use_tz=False,
         timezone="UTC",
         _create_db=False,
+        _enable_global_fallback=True,
     )
     await orm.close_orm()
     mocked_close_connections.assert_awaited_once()

tortoise/__init__.py

@@ -300,6 +300,7 @@ async def init(
         routers: list[str | type] | None = None,
         table_name_generator: Callable[[type[Model]], str] | None = None,
         init_connections: bool = True,
+        _enable_global_fallback: bool = False,
     ) -> TortoiseContext:
         """
         Sets up Tortoise-ORM: loads apps and models, configures database connections but does not
@@ -368,6 +369,10 @@ async def init(
         :param init_connections:
             When ``False``, skips initializing connection clients while still loading apps
             and validating connection names against the config.
+        :param _enable_global_fallback:
+            When ``True``, stores the context as a global fallback for cross-task access.
+            This is used by RegisterTortoise (FastAPI) where asgi-lifespan runs lifespan
+            in a background task. Default is ``False`` for pure context isolation.
 
         :raises ConfigurationError: For any configuration error
 
@@ -425,6 +430,7 @@ async def init(
             routers=routers,
             table_name_generator=table_name_generator,
             init_connections=init_connections,
+            _enable_global_fallback=_enable_global_fallback,
         )
 
         return ctx

tortoise/context.py

@@ -45,15 +45,55 @@
     "tortoise_context", default=None
 )
 
+# Optional global fallback context for cross-task access.
+# This is used by RegisterTortoise (FastAPI) where asgi-lifespan runs lifespan
+# in a background task, but requests/tests run in a different task.
+# Disabled by default; enabled via Tortoise.init(_enable_global_fallback=True).
+_global_context: TortoiseContext | None = None
+
 
 def get_current_context() -> TortoiseContext | None:
     """
     Get the currently active TortoiseContext, or None if no context is active.
 
+    Checks the contextvar first (for proper isolation), then falls back to
+    the global context if one was set via _enable_global_fallback.
+
     Returns:
         The current TortoiseContext if one is active, None otherwise.
     """
-    return _current_context.get()
+    ctx = _current_context.get()
+    if ctx is not None:
+        return ctx
+    return _global_context
+
+
+def set_global_context(ctx: TortoiseContext) -> None:
+    """
+    Set the global fallback context for cross-task access.
+
+    This is used by RegisterTortoise (FastAPI) where asgi-lifespan runs lifespan
+    in a background task, but requests/tests run in a different task.
+    The global context allows these cross-task scenarios to work without
+    explicit context passing.
+
+    Args:
+        ctx: The TortoiseContext to set as global fallback.
+
+    Raises:
+        ConfigurationError: If a global context is already set. Only one global
+            context can be active at a time. For multiple isolated contexts,
+            use explicit TortoiseContext() without global fallback.
+    """
+    global _global_context
+    if _global_context is not None:
+        raise ConfigurationError(
+            "Global context fallback is already enabled by another Tortoise.init() call. "
+            "Only one global context can be active at a time. "
+            "Use explicit TortoiseContext() for multiple isolated contexts, "
+            "or set _enable_global_fallback=False for secondary apps."
+        )
+    _global_context = ctx
 
 
 def require_context() -> TortoiseContext:
@@ -230,6 +270,7 @@ async def init(
         routers: list[str | type] | None = None,
         table_name_generator: Callable[[type[Model]], str] | None = None,
         init_connections: bool = True,
+        _enable_global_fallback: bool = False,
     ) -> None:
         """
         Initialize this context with database configuration.
@@ -255,6 +296,8 @@ async def init(
             table_name_generator: Optional callable to generate table names.
             init_connections: If False, skips initializing connection clients while still
                 loading apps and validating connection names against the config.
+            _enable_global_fallback: If True, sets this context as the global fallback
+                for cross-task access (e.g., asgi-lifespan scenarios). Default is False.
 
         Raises:
             ConfigurationError: If configuration is invalid or incomplete.
@@ -334,6 +377,10 @@ async def init(
 
         self._inited = True
 
+        # Set global fallback for cross-task access if enabled
+        if _enable_global_fallback:
+            set_global_context(self)
+
     def _init_timezone(self, use_tz: bool, timezone: str) -> None:
         """Initialize timezone settings for this context."""
         self._use_tz = use_tz
@@ -478,9 +525,13 @@ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """
         Exit the async context manager, close connections, and restore previous context.
         """
+        global _global_context
         await self.close_connections()
         self._apps = None
         self._inited = False
+        # Clear global context if this context was set as the global fallback
+        if _global_context is self:
+            _global_context = None
         self.__exit__(exc_type, exc_val, exc_tb)
 
 
@@ -558,5 +609,6 @@ async def test_create_user(db):
     "TortoiseContext",
     "get_current_context",
     "require_context",
+    "set_global_context",
     "tortoise_test_context",
 ]

tortoise/contrib/fastapi/__init__.py

@@ -9,6 +9,7 @@
 
 from tortoise import Tortoise
 from tortoise.connection import get_connections
+from tortoise.context import TortoiseContext
 from tortoise.exceptions import DoesNotExist, IntegrityError
 from tortoise.log import logger
 
@@ -103,6 +104,10 @@ class RegisterTortoise(AbstractAsyncContextManager):
         A boolean that specifies if datetime will be timezone-aware by default or not.
     timezone:
         Timezone to use, default is UTC.
+    _enable_global_fallback:
+        If True, enables global context fallback for cross-task access (e.g., when
+        using asgi-lifespan which runs lifespan in a background task). Default is True.
+        Set to False when running multiple apps in the same process to avoid conflicts.
 
     Raises
     ------
@@ -122,6 +127,7 @@ def __init__(
         use_tz: bool = False,
         timezone: str = "UTC",
         _create_db: bool = False,
+        _enable_global_fallback: bool = True,
     ) -> None:
         self.app = app
         self.config = config
@@ -132,6 +138,8 @@ def __init__(
         self.use_tz = use_tz
         self.timezone = timezone
         self._create_db = _create_db
+        self._enable_global_fallback = _enable_global_fallback
+        self._context: TortoiseContext | None = None
 
         if add_exception_handlers and app is not None:
             from starlette.middleware.exceptions import ExceptionMiddleware
@@ -151,24 +159,32 @@ async def wrap_middleware_call(self, *args, **kw) -> None:
 
             ExceptionMiddleware.__call__ = wrap_middleware_call  # type:ignore
 
-    async def init_orm(self) -> None:  # pylint: disable=W0612
-        await Tortoise.init(
+    async def init_orm(self) -> TortoiseContext:  # pylint: disable=W0612
+        self._context = await Tortoise.init(
             config=self.config,
             config_file=self.config_file,
             db_url=self.db_url,
             modules=self.modules,
             use_tz=self.use_tz,
             timezone=self.timezone,
             _create_db=self._create_db,
+            _enable_global_fallback=self._enable_global_fallback,
         )
+        # Store context in app.state for explicit access when global fallback is disabled
+        if self.app is not None:
+            self.app.state._tortoise_context = self._context
         logger.info("Tortoise-ORM started, %s, %s", get_connections()._get_storage(), Tortoise.apps)
         if self.generate_schemas:
             logger.info("Tortoise-ORM generating schema")
             await Tortoise.generate_schemas()
+        return self._context
 
-    @staticmethod
-    async def close_orm() -> None:  # pylint: disable=W0612
+    async def close_orm(self) -> None:  # pylint: disable=W0612
         await Tortoise.close_connections()
+        # Clear context from app.state
+        if self.app is not None and hasattr(self.app.state, "_tortoise_context"):
+            delattr(self.app.state, "_tortoise_context")
+        self._context = None
         logger.info("Tortoise-ORM shutdown")
 
     def __call__(self, *args, **kwargs) -> Self: