fix: register session listeners in framework extension configs (#709)

advanced_alchemy/extensions/flask/config.py

@@ -18,6 +18,7 @@
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
 from advanced_alchemy.exceptions import ImproperConfigurationError
+from advanced_alchemy.routing.maker import adispose_session_maker, dispose_session_maker
 from advanced_alchemy.service import schema_dump
 
 if TYPE_CHECKING:
@@ -84,19 +85,18 @@ class SQLAlchemySyncConfig(_SQLAlchemySyncConfig):
     def create_session_maker(self) -> "Callable[[], Session]":
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration runs.
+        See issue #709.
+
         Returns:
             Callable[[], Session]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     def init_app(self, app: "Flask", portal: "Optional[Portal]" = None) -> None:
         """Initialize the Flask application with this configuration.
@@ -142,6 +142,7 @@ def close_engines(self, portal: "Portal") -> None:
         """
         if self.engine_instance is not None:
             self.engine_instance.dispose()
+        dispose_session_maker(self.session_maker)
 
     def create_all_metadata(self) -> None:  # pragma: no cover
         """Create all metadata tables in the database."""
@@ -173,19 +174,17 @@ class SQLAlchemyAsyncConfig(_SQLAlchemyAsyncConfig):
     def create_session_maker(self) -> "Callable[[], AsyncSession]":
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration runs.
+
         Returns:
             Callable[[], AsyncSession]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     def init_app(self, app: "Flask", portal: "Optional[Portal]" = None) -> None:
         """Initialize the Flask application with this configuration.
@@ -246,6 +245,8 @@ def close_engines(self, portal: "Portal") -> None:
         """
         if self.engine_instance is not None:
             _ = portal.call(self.engine_instance.dispose)
+        if self.session_maker is not None:
+            _ = portal.call(adispose_session_maker, self.session_maker)
 
     async def create_all_metadata(self) -> None:  # pragma: no cover
         """Create all metadata tables in the database."""

advanced_alchemy/extensions/litestar/plugins/init/config/asyncio.py

@@ -22,6 +22,7 @@
 )
 from advanced_alchemy.extensions.litestar.plugins.init.config.engine import EngineConfig
 from advanced_alchemy.routing.context import reset_routing_context
+from advanced_alchemy.routing.maker import adispose_session_maker
 
 logger = logging.getLogger("advanced_alchemy.extensions.litestar")
 
@@ -201,16 +202,15 @@ def __post_init__(self) -> None:
     def create_session_maker(self) -> "Callable[[], AsyncSession]":
         """Get a session maker. If none exists yet, create one.
 
+        Delegates to the base-class implementation so that listener
+        registration (file-object, timestamp, cache) runs.
+
         Returns:
             Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.get_engine()
-        return self.session_maker_class(**session_kws)  # pyright: ignore[reportUnknownVariableType,reportUnknownMemberType]
+        return super().create_session_maker()
 
     @asynccontextmanager
     async def lifespan(
@@ -228,6 +228,7 @@ async def lifespan(
                 engine = deps[self.engine_dependency_key]
                 if hasattr(engine, "dispose"):
                     await cast("AsyncEngine", engine).dispose()
+            await adispose_session_maker(self.session_maker)
 
     def provide_engine(self, state: "State") -> "AsyncEngine":
         """Create an engine instance.

advanced_alchemy/extensions/litestar/plugins/init/config/sync.py

@@ -22,6 +22,7 @@
 )
 from advanced_alchemy.extensions.litestar.plugins.init.config.engine import EngineConfig
 from advanced_alchemy.routing.context import reset_routing_context
+from advanced_alchemy.routing.maker import dispose_session_maker
 
 logger = logging.getLogger("advanced_alchemy.extensions.litestar")
 
@@ -202,16 +203,15 @@ def __post_init__(self) -> None:
     def create_session_maker(self) -> "Callable[[], Session]":
         """Get a session maker. If none exists yet, create one.
 
+        Delegates to the base-class implementation so that listener
+        registration (file-object, timestamp, cache) runs. See issue #709.
+
         Returns:
             Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.get_engine()
-        return self.session_maker_class(**session_kws)
+        return super().create_session_maker()
 
     @asynccontextmanager
     async def lifespan(
@@ -229,6 +229,7 @@ async def lifespan(
                 engine = deps[self.engine_dependency_key]
                 if hasattr(engine, "dispose"):
                     cast("Engine", engine).dispose()
+            dispose_session_maker(self.session_maker)
 
     def provide_engine(self, state: "State") -> "Engine":
         """Create an engine instance.

advanced_alchemy/extensions/sanic/config.py

@@ -34,6 +34,7 @@
 from advanced_alchemy.config import EngineConfig as _EngineConfig
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
+from advanced_alchemy.routing.maker import adispose_session_maker, dispose_session_maker
 from advanced_alchemy.service import schema_dump
 
 logger = logging.getLogger("advanced_alchemy.extensions.sanic")
@@ -187,6 +188,7 @@ async def on_startup(_: Any) -> None:  # pyright: ignore[reportUnusedFunction]
         async def on_shutdown(_: Any) -> None:  # pyright: ignore[reportUnusedFunction]
             if self.engine_instance is not None:
                 await self.engine_instance.dispose()
+            await adispose_session_maker(self.session_maker)
             if hasattr(self.app.ctx, self.engine_key):  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType,reportOptionalMemberAccess]
                 delattr(self.app.ctx, self.engine_key)  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType,reportOptionalMemberAccess]
             if hasattr(self.app.ctx, self.session_maker_key):  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType,reportOptionalMemberAccess]
@@ -213,19 +215,18 @@ async def on_startup(self) -> None:
     def create_session_maker(self) -> Callable[[], "AsyncSession"]:
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration
+        (file-object, timestamp, cache) runs. See issue #709.
+
         Returns:
             Callable[[], Session]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     async def session_handler(
         self, session: "AsyncSession", request: "Request", response: "HTTPResponse"
@@ -298,6 +299,7 @@ async def close_engine(self) -> None:  # pragma: no cover
         """Close the engine."""
         if self.engine_instance is not None:
             await self.engine_instance.dispose()
+        await adispose_session_maker(self.session_maker)
 
     async def on_shutdown(self) -> None:  # pragma: no cover
         """Handles the shutdown event by disposing of the SQLAlchemy engine.
@@ -426,19 +428,18 @@ async def on_startup(self) -> None:
     def create_session_maker(self) -> Callable[[], "Session"]:
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration runs.
+        See issue #709.
+
         Returns:
             Callable[[], Session]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     async def session_handler(
         self, session: "Session", request: "Request", response: "HTTPResponse"
@@ -508,9 +509,11 @@ def get_session_from_request(self, request: Request) -> "Session":
 
     async def close_engine(self) -> None:  # pragma: no cover
         """Close the engine."""
+        loop = asyncio.get_event_loop()
         if self.engine_instance is not None:
-            loop = asyncio.get_event_loop()
             await loop.run_in_executor(None, self.engine_instance.dispose)
+        if self.session_maker is not None:
+            await loop.run_in_executor(None, dispose_session_maker, self.session_maker)
 
     async def on_shutdown(self) -> None:  # pragma: no cover
         """Handles the shutdown event by disposing of the SQLAlchemy engine.

advanced_alchemy/extensions/starlette/config.py

@@ -21,6 +21,7 @@
 from advanced_alchemy.config.asyncio import SQLAlchemyAsyncConfig as _SQLAlchemyAsyncConfig
 from advanced_alchemy.config.sync import SQLAlchemySyncConfig as _SQLAlchemySyncConfig
 from advanced_alchemy.routing.context import reset_routing_context
+from advanced_alchemy.routing.maker import adispose_session_maker, dispose_session_maker
 from advanced_alchemy.service import schema_dump
 
 if TYPE_CHECKING:
@@ -245,19 +246,18 @@ async def on_startup(self) -> None:
     def create_session_maker(self) -> Callable[[], "AsyncSession"]:
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration
+        (file-object, timestamp, cache) runs. See issue #709.
+
         Returns:
             Callable[[], Session]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     async def session_handler(
         self, session: "AsyncSession", request: "Request", response: "Response"
@@ -334,6 +334,7 @@ async def close_engine(self) -> None:  # pragma: no cover
         """Close the engine."""
         if self.engine_instance is not None:
             await self.engine_instance.dispose()
+        await adispose_session_maker(self.session_maker)
 
     async def on_shutdown(self) -> None:  # pragma: no cover
         """Handles the shutdown event by disposing of the SQLAlchemy engine.
@@ -408,19 +409,18 @@ async def on_startup(self) -> None:
     def create_session_maker(self) -> Callable[[], "Session"]:
         """Get a session maker. If none exists yet, create one.
 
+        Preserves ``engine_instance`` caching and then delegates to the
+        base-class implementation so that listener registration runs.
+        See issue #709.
+
         Returns:
             Callable[[], Session]: Session factory used by the plugin.
         """
         if self.session_maker:
             return self.session_maker
-
-        session_kws = self.session_config_dict
         if self.engine_instance is None:
             self.engine_instance = self.get_engine()
-        if session_kws.get("bind") is None:
-            session_kws["bind"] = self.engine_instance
-        self.session_maker = self.session_maker_class(**session_kws)
-        return self.session_maker
+        return super().create_session_maker()
 
     async def session_handler(
         self, session: "Session", request: "Request", response: "Response"
@@ -497,6 +497,7 @@ async def close_engine(self) -> None:  # pragma: no cover
         """Close the engines."""
         if self.engine_instance is not None:
             await run_in_threadpool(self.engine_instance.dispose)
+        await run_in_threadpool(lambda: dispose_session_maker(self.session_maker))
 
     async def on_shutdown(self) -> None:  # pragma: no cover
         """Handles the shutdown event by disposing of the SQLAlchemy engine.

advanced_alchemy/routing/__init__.py

@@ -41,7 +41,12 @@
     stick_to_primary_var,
     use_bind_group,
 )
-from advanced_alchemy.routing.maker import RoutingAsyncSessionMaker, RoutingSyncSessionMaker
+from advanced_alchemy.routing.maker import (
+    RoutingAsyncSessionMaker,
+    RoutingSyncSessionMaker,
+    adispose_session_maker,
+    dispose_session_maker,
+)
 from advanced_alchemy.routing.selectors import RandomSelector, ReplicaSelector, RoundRobinSelector
 from advanced_alchemy.routing.session import RoutingAsyncSession, RoutingSyncSession
 
@@ -53,6 +58,8 @@
     "RoutingAsyncSessionMaker",
     "RoutingSyncSession",
     "RoutingSyncSessionMaker",
+    "adispose_session_maker",
+    "dispose_session_maker",
     "force_primary_var",
     "primary_context",
     "replica_context",

advanced_alchemy/routing/maker.py

@@ -17,6 +17,8 @@
 __all__ = (
     "RoutingAsyncSessionMaker",
     "RoutingSyncSessionMaker",
+    "adispose_session_maker",
+    "dispose_session_maker",
 )
 
 
@@ -351,3 +353,31 @@ async def close_all(self) -> None:
         for engine_list in self._engines.values():
             for engine in engine_list:
                 await engine.dispose()
+
+
+def dispose_session_maker(session_maker: Any) -> None:
+    """Dispose all engines owned by a sync routing session maker.
+
+    No-op for non-routing session makers; the framework is responsible for
+    disposing ``engine_instance`` separately. Use during application shutdown
+    to release connections held by routing pools (primary + replicas).
+
+    Args:
+        session_maker: A session maker instance (any type).
+    """
+    if isinstance(session_maker, RoutingSyncSessionMaker):
+        session_maker.close_all()
+
+
+async def adispose_session_maker(session_maker: Any) -> None:
+    """Dispose all engines owned by an async routing session maker.
+
+    No-op for non-routing session makers; the framework is responsible for
+    disposing ``engine_instance`` separately. Use during application shutdown
+    to release connections held by routing pools (primary + replicas).
+
+    Args:
+        session_maker: A session maker instance (any type).
+    """
+    if isinstance(session_maker, RoutingAsyncSessionMaker):
+        await session_maker.close_all()

pyproject.toml

@@ -212,7 +212,7 @@ search = 'version = "{current_version}"'
 # NOTE: mysql-connector-python 9.6.0 (released 2026-01-21) removed Python 3.12+ wheels.
 # This is an Oracle packaging bug. Pinning to versions before that date until fixed.
 # Check https://pypi.org/project/mysql-connector-python/#files for updates.
-exclude-newer-package = { mysql-connector-python = "2026-01-20" }
+exclude-newer-package = { mysql-connector-python = "2026-01-20T00:00:00Z" }
 
 [build-system]
 build-backend = "hatchling.build"