sqlspec 0.26.0__py3-none-any.whl → 0.28.0__py3-none-any.whl

sqlspec/extensions/aiosql/adapter.py

@@ -6,23 +6,22 @@ from files using aiosql while using SQLSpec's features for execution and type ma
 """
 
 import logging
-from collections.abc import AsyncGenerator, Generator
-from contextlib import asynccontextmanager, contextmanager
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, TypeVar, Union, cast
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import Any, ClassVar, Generic, TypeVar
 
 from sqlspec.core.result import SQLResult
 from sqlspec.core.statement import SQL, StatementConfig
-from sqlspec.exceptions import MissingDependencyError
-from sqlspec.typing import AIOSQL_INSTALLED
-
-if TYPE_CHECKING:
-    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+from sqlspec.typing import AiosqlAsyncProtocol, AiosqlParamType, AiosqlSQLOperationType, AiosqlSyncProtocol
+from sqlspec.utils.module_loader import ensure_aiosql
 
 logger = logging.getLogger("sqlspec.extensions.aiosql")
 
 __all__ = ("AiosqlAsyncAdapter", "AiosqlSyncAdapter")
 
 T = TypeVar("T")
+DriverT = TypeVar("DriverT", bound="SyncDriverAdapterBase | AsyncDriverAdapterBase")
 
 
 class AsyncCursorLike:
@@ -34,7 +33,7 @@ class AsyncCursorLike:
             return list(self.result.data)
         return []
 
-    async def fetchone(self) -> Optional[Any]:
+    async def fetchone(self) -> Any | None:
         rows = await self.fetchall()
         return rows[0] if rows else None
 
@@ -48,18 +47,12 @@ class CursorLike:
             return list(self.result.data)
         return []
 
-    def fetchone(self) -> Optional[Any]:
+    def fetchone(self) -> Any | None:
         rows = self.fetchall()
         return rows[0] if rows else None
 
 
-def _check_aiosql_available() -> None:
-    if not AIOSQL_INSTALLED:
-        msg = "aiosql"
-        raise MissingDependencyError(msg, "aiosql")
-
-
-def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
+def _normalize_dialect(dialect: "str | Any | None") -> str:
     """Normalize dialect name for SQLGlot compatibility.
 
     Args:
@@ -71,12 +64,12 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
     if dialect is None:
         return "sql"
 
-    if hasattr(dialect, "__name__"):
-        dialect_str = str(dialect.__name__).lower()  # pyright: ignore
-    elif hasattr(dialect, "name"):
-        dialect_str = str(dialect.name).lower()  # pyright: ignore
-    elif isinstance(dialect, str):
+    if isinstance(dialect, str):
         dialect_str = dialect.lower()
+    elif hasattr(dialect, "__name__"):
+        dialect_str = str(dialect.__name__).lower()
+    elif hasattr(dialect, "name"):
+        dialect_str = str(dialect.name).lower()
     else:
         dialect_str = str(dialect).lower()
 
@@ -91,19 +84,19 @@ def _normalize_dialect(dialect: "Union[str, Any, None]") -> str:
     return dialect_mapping.get(dialect_str, dialect_str)
 
 
-class _AiosqlAdapterBase:
+class _AiosqlAdapterBase(Generic[DriverT]):
     """Base adapter class providing common functionality for aiosql integration."""
 
-    def __init__(self, driver: "Union[SyncDriverAdapterBase, AsyncDriverAdapterBase]") -> None:
+    def __init__(self, driver: DriverT) -> None:
         """Initialize the base adapter.
 
         Args:
             driver: SQLSpec driver to use for execution.
         """
-        _check_aiosql_available()
-        self.driver = driver
+        ensure_aiosql()
+        self.driver: DriverT = driver
 
-    def process_sql(self, query_name: str, op_type: "Any", sql: str) -> str:
+    def process_sql(self, query_name: str, op_type: "AiosqlSQLOperationType", sql: str) -> str:
         """Process SQL string for aiosql compatibility.
 
         Args:
@@ -116,7 +109,7 @@ class _AiosqlAdapterBase:
         """
         return sql
 
-    def _create_sql_object(self, sql: str, parameters: "Any" = None) -> SQL:
+    def _create_sql_object(self, sql: str, parameters: "AiosqlParamType" = None) -> SQL:
         """Create SQL object with proper configuration.
 
         Args:
@@ -134,7 +127,7 @@ class _AiosqlAdapterBase:
         )
 
 
-class AiosqlSyncAdapter(_AiosqlAdapterBase):
+class AiosqlSyncAdapter(_AiosqlAdapterBase[SyncDriverAdapterBase], AiosqlSyncProtocol):
     """Synchronous adapter that implements aiosql protocol using SQLSpec drivers.
 
     This adapter bridges aiosql's synchronous driver protocol with SQLSpec's sync drivers,
@@ -152,7 +145,7 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         super().__init__(driver)
 
     def select(
-        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType", record_class: Any | None = None
     ) -> Generator[Any, None, None]:
         """Execute a SELECT query and return results as generator.
 
@@ -182,8 +175,8 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
             yield from result.data
 
     def select_one(
-        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
-    ) -> Optional[dict[str, Any]]:
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType", record_class: Any | None = None
+    ) -> tuple[Any, ...] | None:
         """Execute a SELECT query and return first result.
 
         Args:
@@ -206,13 +199,14 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
-            return cast("Optional[dict[str, Any]]", result.data[0])
+            row = result.data[0]
+            return tuple(row.values()) if isinstance(row, dict) else row
         return None
 
-    def select_value(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+    def select_value(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> Any | None:
         """Execute a SELECT query and return first value of first row.
 
         Args:
@@ -235,7 +229,9 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         return row
 
     @contextmanager
-    def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Generator[Any, None, None]:
+    def select_cursor(
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType"
+    ) -> Generator[Any, None, None]:
         """Execute a SELECT query and return cursor context manager.
 
         Args:
@@ -251,7 +247,7 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
 
         yield CursorLike(result)
 
-    def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> int:
+    def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> int:
         """Execute INSERT/UPDATE/DELETE and return affected rows.
 
         Args:
@@ -263,11 +259,11 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Returns:
             Number of affected rows
         """
-        result = cast("SQLResult", self.driver.execute(self._create_sql_object(sql, parameters), connection=conn))
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         return result.rows_affected if hasattr(result, "rows_affected") else 0
 
-    def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> int:
+    def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> int:
         """Execute INSERT/UPDATE/DELETE with many parameter sets.
 
         Args:
@@ -279,13 +275,11 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         Returns:
             Number of affected rows
         """
-        result = cast(
-            "SQLResult", self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)
-        )
+        result = self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         return result.rows_affected if hasattr(result, "rows_affected") else 0
 
-    def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+    def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> Any | None:
         """Execute INSERT with RETURNING and return result.
 
         Args:
@@ -300,7 +294,18 @@ class AiosqlSyncAdapter(_AiosqlAdapterBase):
         return self.select_one(conn, query_name, sql, parameters)
 
 
-class AiosqlAsyncAdapter(_AiosqlAdapterBase):
+class _AsyncCursorContextManager(Generic[T]):
+    def __init__(self, cursor_like: T) -> None:
+        self._cursor_like = cursor_like
+
+    async def __aenter__(self) -> T:
+        return self._cursor_like
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        pass
+
+
+class AiosqlAsyncAdapter(_AiosqlAdapterBase[AsyncDriverAdapterBase], AiosqlAsyncProtocol):
     """Asynchronous adapter that implements aiosql protocol using SQLSpec drivers.
 
     This adapter bridges aiosql's async driver protocol with SQLSpec's async drivers,
@@ -318,7 +323,7 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         super().__init__(driver)
 
     async def select(
-        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType", record_class: Any | None = None
     ) -> list[Any]:
         """Execute a SELECT query and return results as list.
 
@@ -342,15 +347,15 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         if hasattr(result, "data") and result.data is not None and isinstance(result, SQLResult):
             return list(result.data)
         return []
 
     async def select_one(
-        self, conn: Any, query_name: str, sql: str, parameters: "Any", record_class: Optional[Any] = None
-    ) -> Optional[Any]:
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType", record_class: Any | None = None
+    ) -> Any | None:
         """Execute a SELECT query and return first result.
 
         Args:
@@ -373,13 +378,14 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
                 "Use schema_type in driver.execute or _sqlspec_schema_type in parameters."
             )
 
-        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
         if hasattr(result, "data") and result.data and isinstance(result, SQLResult):
-            return result.data[0]
+            row = result.data[0]
+            return tuple(row.values()) if isinstance(row, dict) else row
         return None
 
-    async def select_value(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+    async def select_value(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> Any | None:
         """Execute a SELECT query and return first value of first row.
 
         Args:
@@ -401,8 +407,9 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
             return row[0] if len(row) > 0 else None
         return row
 
-    @asynccontextmanager
-    async def select_cursor(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> AsyncGenerator[Any, None]:
+    async def select_cursor(
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType"
+    ) -> "_AsyncCursorContextManager[Any]":
         """Execute a SELECT query and return cursor context manager.
 
         Args:
@@ -414,11 +421,10 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         Yields:
             Cursor-like object with results
         """
-        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
-
-        yield AsyncCursorLike(result)
+        result = await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
+        return _AsyncCursorContextManager(AsyncCursorLike(result))
 
-    async def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> None:
+    async def insert_update_delete(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> None:
         """Execute INSERT/UPDATE/DELETE.
 
         Args:
@@ -430,9 +436,11 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         Note:
             Returns None per aiosql async protocol
         """
-        await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)  # type: ignore[misc]
+        await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
-    async def insert_update_delete_many(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> None:
+    async def insert_update_delete_many(
+        self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType"
+    ) -> None:
         """Execute INSERT/UPDATE/DELETE with many parameter sets.
 
         Args:
@@ -444,9 +452,9 @@ class AiosqlAsyncAdapter(_AiosqlAdapterBase):
         Note:
             Returns None per aiosql async protocol
         """
-        await self.driver.execute_many(self._create_sql_object(sql), parameters=parameters, connection=conn)  # type: ignore[misc]
+        await self.driver.execute(self._create_sql_object(sql, parameters), connection=conn)
 
-    async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "Any") -> Optional[Any]:
+    async def insert_returning(self, conn: Any, query_name: str, sql: str, parameters: "AiosqlParamType") -> Any | None:
         """Execute INSERT with RETURNING and return result.
 
         Args:

sqlspec/extensions/fastapi/__init__.py

@@ -0,0 +1,21 @@
+"""FastAPI extension for SQLSpec.
+
+Extends Starlette integration with dependency injection helpers for FastAPI's
+Depends() system, including filter dependency builders.
+"""
+
+from sqlspec.config import StarletteConfig
+from sqlspec.extensions.fastapi.extension import SQLSpecPlugin
+from sqlspec.extensions.fastapi.providers import DependencyDefaults, FieldNameType, FilterConfig, provide_filters
+from sqlspec.extensions.starlette.middleware import SQLSpecAutocommitMiddleware, SQLSpecManualMiddleware
+
+__all__ = (
+    "DependencyDefaults",
+    "FieldNameType",
+    "FilterConfig",
+    "SQLSpecAutocommitMiddleware",
+    "SQLSpecManualMiddleware",
+    "SQLSpecPlugin",
+    "StarletteConfig",
+    "provide_filters",
+)

sqlspec/extensions/fastapi/extension.py

@@ -0,0 +1,331 @@
+from typing import TYPE_CHECKING, Any, overload
+
+from fastapi import Request
+
+from sqlspec.extensions.fastapi.providers import DEPENDENCY_DEFAULTS
+from sqlspec.extensions.fastapi.providers import provide_filters as _provide_filters
+from sqlspec.extensions.starlette.extension import SQLSpecPlugin as _StarlettePlugin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlspec.config import AsyncDatabaseConfig, SyncDatabaseConfig
+    from sqlspec.core.filters import FilterTypes
+    from sqlspec.driver import AsyncDriverAdapterBase, SyncDriverAdapterBase
+    from sqlspec.extensions.fastapi.providers import DependencyDefaults, FilterConfig
+
+__all__ = ("SQLSpecPlugin",)
+
+
+class SQLSpecPlugin(_StarlettePlugin):
+    """SQLSpec integration for FastAPI applications.
+
+    Extends Starlette integration with dependency injection helpers for FastAPI's
+    Depends() system.
+
+    Example:
+        from fastapi import Depends, FastAPI
+        from sqlspec import SQLSpec
+        from sqlspec.adapters.asyncpg import AsyncpgConfig
+        from sqlspec.extensions.fastapi import SQLSpecPlugin
+
+        sqlspec = SQLSpec()
+        config = AsyncpgConfig(
+            pool_config={"dsn": "postgresql://localhost/mydb"},
+            extension_config={
+                "starlette": {
+                    "commit_mode": "autocommit",
+                    "session_key": "db"
+                }
+            }
+        )
+        sqlspec.add_config(config, name="default")
+
+        app = FastAPI()
+        db_ext = SQLSpecPlugin(sqlspec, app)
+
+        @app.get("/users")
+        async def list_users(db = Depends(db_ext.provide_session())):
+            result = await db.execute("SELECT * FROM users")
+            return {"users": result.all()}
+    """
+
+    @overload
+    def provide_session(
+        self, key: None = None
+    ) -> "Callable[[Request], AsyncDriverAdapterBase | SyncDriverAdapterBase]": ...
+
+    @overload
+    def provide_session(self, key: str) -> "Callable[[Request], AsyncDriverAdapterBase | SyncDriverAdapterBase]": ...
+
+    @overload
+    def provide_session(self, key: "type[AsyncDatabaseConfig]") -> "Callable[[Request], AsyncDriverAdapterBase]": ...
+
+    @overload
+    def provide_session(self, key: "type[SyncDatabaseConfig]") -> "Callable[[Request], SyncDriverAdapterBase]": ...
+
+    @overload
+    def provide_session(self, key: "AsyncDatabaseConfig") -> "Callable[[Request], AsyncDriverAdapterBase]": ...
+
+    @overload
+    def provide_session(self, key: "SyncDatabaseConfig") -> "Callable[[Request], SyncDriverAdapterBase]": ...
+
+    def provide_session(
+        self,
+        key: "str | type[AsyncDatabaseConfig | SyncDatabaseConfig] | AsyncDatabaseConfig | SyncDatabaseConfig | None" = None,
+    ) -> "Callable[[Request], AsyncDriverAdapterBase | SyncDriverAdapterBase]":
+        """Create dependency factory for session injection.
+
+        Returns a callable that can be used with FastAPI's Depends() to inject
+        a database session into route handlers.
+
+        Args:
+            key: Optional session key (str), config type for type narrowing, or None.
+
+        Returns:
+            Dependency callable for FastAPI Depends().
+
+        Example:
+            # No args - returns union type
+            @app.get("/users")
+            async def get_users(db = Depends(db_ext.provide_session())):
+                return await db.execute("SELECT * FROM users")
+
+            # String key for multi-database
+            @app.get("/products")
+            async def get_products(db = Depends(db_ext.provide_session("products"))):
+                return await db.execute("SELECT * FROM products")
+
+            # Config instance for type narrowing
+            config = AsyncpgConfig(...)
+            @app.get("/typed")
+            async def typed_query(db = Depends(db_ext.provide_session(config))):
+                # db is properly typed as AsyncDriverAdapterBase
+                return await db.execute("SELECT 1")
+
+            # Config type/class for type narrowing
+            @app.get("/typed2")
+            async def typed_query2(db = Depends(db_ext.provide_session(AsyncpgConfig))):
+                # db is properly typed as AsyncDriverAdapterBase
+                return await db.execute("SELECT 1")
+        """
+        # Extract string key if provided, ignore config types/instances (used only for type narrowing)
+        session_key = key if isinstance(key, str) or key is None else None
+
+        def dependency(request: Request) -> "AsyncDriverAdapterBase | SyncDriverAdapterBase":
+            return self.get_session(request, session_key)  # type: ignore[no-any-return]
+
+        return dependency
+
+    def provide_async_session(self, key: "str | None" = None) -> "Callable[[Request], AsyncDriverAdapterBase]":
+        """Create dependency factory for async session injection.
+
+        Type-narrowed version of provide_session() that returns AsyncDriverAdapterBase.
+        Useful when using string keys and you know the config is async.
+
+        Args:
+            key: Optional session key for multi-database configurations.
+
+        Returns:
+            Dependency callable that returns AsyncDriverAdapterBase.
+
+        Example:
+            @app.get("/users")
+            async def get_users(db = Depends(db_ext.provide_async_session())):
+                # db is AsyncDriverAdapterBase
+                return await db.execute("SELECT * FROM users")
+
+            @app.get("/products")
+            async def get_products(db = Depends(db_ext.provide_async_session("products_db"))):
+                # db is AsyncDriverAdapterBase for "products_db" key
+                return await db.execute("SELECT * FROM products")
+        """
+
+        def dependency(request: Request) -> "AsyncDriverAdapterBase":
+            return self.get_session(request, key)  # type: ignore[no-any-return]
+
+        return dependency
+
+    def provide_sync_session(self, key: "str | None" = None) -> "Callable[[Request], SyncDriverAdapterBase]":
+        """Create dependency factory for sync session injection.
+
+        Type-narrowed version of provide_session() that returns SyncDriverAdapterBase.
+        Useful when using string keys and you know the config is sync.
+
+        Args:
+            key: Optional session key for multi-database configurations.
+
+        Returns:
+            Dependency callable that returns SyncDriverAdapterBase.
+
+        Example:
+            @app.get("/users")
+            def get_users(db = Depends(db_ext.provide_sync_session())):
+                # db is SyncDriverAdapterBase
+                return db.execute("SELECT * FROM users")
+        """
+
+        def dependency(request: Request) -> "SyncDriverAdapterBase":
+            return self.get_session(request, key)  # type: ignore[no-any-return]
+
+        return dependency
+
+    @overload
+    def provide_connection(self, key: None = None) -> "Callable[[Request], Any]": ...
+
+    @overload
+    def provide_connection(self, key: str) -> "Callable[[Request], Any]": ...
+
+    @overload
+    def provide_connection(self, key: "type[AsyncDatabaseConfig]") -> "Callable[[Request], Any]": ...
+
+    @overload
+    def provide_connection(self, key: "type[SyncDatabaseConfig]") -> "Callable[[Request], Any]": ...
+
+    @overload
+    def provide_connection(self, key: "AsyncDatabaseConfig") -> "Callable[[Request], Any]": ...
+
+    @overload
+    def provide_connection(self, key: "SyncDatabaseConfig") -> "Callable[[Request], Any]": ...
+
+    def provide_connection(
+        self,
+        key: "str | type[AsyncDatabaseConfig | SyncDatabaseConfig] | AsyncDatabaseConfig | SyncDatabaseConfig | None" = None,
+    ) -> "Callable[[Request], Any]":
+        """Create dependency factory for connection injection.
+
+        Returns a callable that can be used with FastAPI's Depends() to inject
+        a database connection into route handlers.
+
+        Args:
+            key: Optional session key (str), config type for type narrowing, or None.
+
+        Returns:
+            Dependency callable for FastAPI Depends().
+
+        Example:
+            # No args
+            @app.get("/raw")
+            async def raw_query(conn = Depends(db_ext.provide_connection())):
+                cursor = await conn.cursor()
+                await cursor.execute("SELECT 1")
+                return await cursor.fetchone()
+
+            # With config instance
+            config = AsyncpgConfig(...)
+            @app.get("/typed")
+            async def typed_query(conn = Depends(db_ext.provide_connection(config))):
+                cursor = await conn.cursor()
+                await cursor.execute("SELECT 1")
+                return await cursor.fetchone()
+
+            # With config type/class
+            @app.get("/typed2")
+            async def typed_query2(conn = Depends(db_ext.provide_connection(AsyncpgConfig))):
+                cursor = await conn.cursor()
+                await cursor.execute("SELECT 1")
+                return await cursor.fetchone()
+        """
+        # Extract string key if provided, ignore config types/instances (used only for type narrowing)
+        connection_key = key if isinstance(key, str) or key is None else None
+
+        def dependency(request: Request) -> Any:
+            return self.get_connection(request, connection_key)
+
+        return dependency
+
+    def provide_async_connection(self, key: "str | None" = None) -> "Callable[[Request], Any]":
+        """Create dependency factory for async connection injection.
+
+        Type-narrowed version of provide_connection() for async connections.
+        Useful when using string keys and you know the config is async.
+
+        Args:
+            key: Optional session key for multi-database configurations.
+
+        Returns:
+            Dependency callable for async connection.
+
+        Example:
+            @app.get("/raw")
+            async def raw_query(conn = Depends(db_ext.provide_async_connection())):
+                cursor = await conn.cursor()
+                await cursor.execute("SELECT 1")
+                return await cursor.fetchone()
+        """
+
+        def dependency(request: Request) -> Any:
+            return self.get_connection(request, key)
+
+        return dependency
+
+    def provide_sync_connection(self, key: "str | None" = None) -> "Callable[[Request], Any]":
+        """Create dependency factory for sync connection injection.
+
+        Type-narrowed version of provide_connection() for sync connections.
+        Useful when using string keys and you know the config is sync.
+
+        Args:
+            key: Optional session key for multi-database configurations.
+
+        Returns:
+            Dependency callable for sync connection.
+
+        Example:
+            @app.get("/raw")
+            def raw_query(conn = Depends(db_ext.provide_sync_connection())):
+                cursor = conn.cursor()
+                cursor.execute("SELECT 1")
+                return cursor.fetchone()
+        """
+
+        def dependency(request: Request) -> Any:
+            return self.get_connection(request, key)
+
+        return dependency
+
+    @staticmethod
+    def provide_filters(
+        config: "FilterConfig", dep_defaults: "DependencyDefaults | None" = None
+    ) -> "Callable[..., list[FilterTypes]]":
+        """Create filter dependency for FastAPI routes.
+
+        Dynamically generates a FastAPI dependency function that parses query
+        parameters into SQLSpec filter objects. The returned callable can be used
+        with FastAPI's Depends() for automatic filter injection.
+
+        Args:
+            config: Filter configuration specifying which filters to enable.
+            dep_defaults: Optional dependency defaults for customization.
+
+        Returns:
+            Callable for use with Depends() that returns list of filters.
+
+        Example:
+            from fastapi import Depends
+            from sqlspec.extensions.fastapi import FilterConfig
+
+            @app.get("/users")
+            async def list_users(
+                db = Depends(db_ext.provide_session()),
+                filters = Depends(
+                    db_ext.provide_filters({
+                        "id_filter": UUID,
+                        "search": "name,email",
+                        "search_ignore_case": True,
+                        "pagination_type": "limit_offset",
+                        "sort_field": "created_at",
+                    })
+                ),
+            ):
+                stmt = sql("SELECT * FROM users")
+                for filter in filters:
+                    stmt = filter.append_to_statement(stmt)
+                result = await db.execute(stmt)
+                return result.all()
+        """
+
+        if dep_defaults is None:
+            dep_defaults = DEPENDENCY_DEFAULTS
+
+        return _provide_filters(config, dep_defaults=dep_defaults)