sqlspec 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

sqlspec/_serialization.py

@@ -13,7 +13,7 @@ try:
 
 except ImportError:
     try:
-        from orjson import dumps as _encode_json  # pyright: ignore[reportMissingImports]
+        from orjson import dumps as _encode_json  # pyright: ignore[reportMissingImports,reportUnknownVariableType]
         from orjson import loads as decode_json  # type: ignore[no-redef]
 
         def encode_json(data: Any) -> str:

sqlspec/_typing.py

@@ -29,7 +29,6 @@ class DataclassProtocol(Protocol):
 T = TypeVar("T")
 T_co = TypeVar("T_co", covariant=True)
 
-
 try:
     from pydantic import BaseModel, FailFast, TypeAdapter
 
@@ -110,6 +109,35 @@ except ImportError:
     UNSET = UnsetType.UNSET  # pyright: ignore[reportConstantRedefinition]
     MSGSPEC_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
 
+try:
+    from litestar.dto.data_structures import DTOData  # pyright: ignore[reportUnknownVariableType]
+
+    LITESTAR_INSTALLED = True
+except ImportError:
+
+    @runtime_checkable
+    class DTOData(Protocol[T]):  # type: ignore[no-redef]
+        """Placeholder implementation"""
+
+        __slots__ = ("_backend", "_data_as_builtins")
+
+        def __init__(self, backend: Any, data_as_builtins: Any) -> None:
+            """Placeholder init"""
+
+        def create_instance(self, **kwargs: Any) -> T:
+            """Placeholder implementation"""
+            return cast("T", kwargs)
+
+        def update_instance(self, instance: T, **kwargs: Any) -> T:
+            """Placeholder implementation"""
+            return cast("T", kwargs)
+
+        def as_builtins(self) -> Any:
+            """Placeholder implementation"""
+            return {}
+
+    LITESTAR_INSTALLED = False  # pyright: ignore[reportConstantRedefinition]
+
 
 class EmptyEnum(Enum):
     """A sentinel enum used as placeholder."""
@@ -122,10 +150,12 @@ Empty: Final = EmptyEnum.EMPTY
 
 
 __all__ = (
+    "LITESTAR_INSTALLED",
     "MSGSPEC_INSTALLED",
     "PYDANTIC_INSTALLED",
     "UNSET",
     "BaseModel",
+    "DTOData",
     "DataclassProtocol",
     "Empty",
     "EmptyEnum",

sqlspec/adapters/adbc/config.py

@@ -2,31 +2,31 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING
 
-from sqlspec.config import GenericDatabaseConfig
+from sqlspec.base import GenericDatabaseConfig, NoPoolConfig
 from sqlspec.typing import Empty, EmptyType
 
 if TYPE_CHECKING:
     from collections.abc import Generator
     from typing import Any
 
-    from adbc_driver_manager.dbapi import Connection, Cursor
+    from adbc_driver_manager.dbapi import Connection
 
 __all__ = ("AdbcDatabaseConfig",)
 
-ConnectionT = TypeVar("ConnectionT", bound="Connection")
-CursorT = TypeVar("CursorT", bound="Cursor")
-
 
 @dataclass
-class AdbcDatabaseConfig(GenericDatabaseConfig):
+class AdbcDatabaseConfig(NoPoolConfig["Connection"], GenericDatabaseConfig):
     """Configuration for ADBC connections.
 
     This class provides configuration options for ADBC database connections using the
     ADBC Driver Manager.([1](https://arrow.apache.org/adbc/current/python/api/adbc_driver_manager.html))
     """
 
+    __supports_connection_pooling = False
+    __is_async = False
+
     uri: str | EmptyType = Empty
     """Database URI"""
     driver_name: str | EmptyType = Empty

sqlspec/adapters/aiosqlite/config.py

@@ -4,7 +4,7 @@ from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
-from sqlspec.config import GenericDatabaseConfig
+from sqlspec.base import GenericDatabaseConfig, NoPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
@@ -19,7 +19,7 @@ __all__ = ("AiosqliteConfig",)
 
 
 @dataclass
-class AiosqliteConfig(GenericDatabaseConfig):
+class AiosqliteConfig(NoPoolConfig["Connection"], GenericDatabaseConfig):
     """Configuration for Aiosqlite database connections.
 
     This class provides configuration options for Aiosqlite database connections, wrapping all parameters

sqlspec/adapters/asyncmy/config.py

@@ -4,6 +4,10 @@ from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, TypeVar
 
+from asyncmy.connection import Connection
+from asyncmy.pool import Pool
+
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
@@ -11,9 +15,7 @@ if TYPE_CHECKING:
     from collections.abc import AsyncGenerator
     from typing import Any
 
-    from asyncmy.connection import Connection
     from asyncmy.cursors import Cursor, DictCursor
-    from asyncmy.pool import Pool
 
 __all__ = (
     "AsyncMyConfig",
@@ -25,7 +27,7 @@ T = TypeVar("T")
 
 
 @dataclass
-class AsyncmyPoolConfig:
+class AsyncmyPoolConfig(GenericPoolConfig):
     """Configuration for Asyncmy's connection pool.
 
     This class provides configuration options for Asyncmy database connection pools.
@@ -104,9 +106,12 @@ class AsyncmyPoolConfig:
 
 
 @dataclass
-class AsyncMyConfig:
+class AsyncMyConfig(DatabaseConfigProtocol[Connection, Pool], GenericDatabaseConfig):
     """Asyncmy Configuration."""
 
+    __is_async__ = True
+    __supports_connection_pooling__ = True
+
     pool_config: AsyncmyPoolConfig | None = None
     """Asyncmy Pool configuration"""
 

sqlspec/adapters/asyncpg/config.py

@@ -2,13 +2,16 @@ from __future__ import annotations
 
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, TypeVar, Union
 
 from asyncpg import Record
 from asyncpg import create_pool as asyncpg_create_pool
+from asyncpg.connection import Connection
+from asyncpg.pool import Pool, PoolConnectionProxy
+from typing_extensions import TypeAlias
 
 from sqlspec._serialization import decode_json, encode_json
-from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
@@ -17,8 +20,6 @@ if TYPE_CHECKING:
     from collections.abc import AsyncGenerator, Awaitable, Callable, Coroutine
     from typing import Any
 
-    from asyncpg.connection import Connection
-    from asyncpg.pool import Pool, PoolConnectionProxy
 
 __all__ = (
     "AsyncPgConfig",
@@ -28,6 +29,8 @@ __all__ = (
 
 T = TypeVar("T")
 
+PgConnection: TypeAlias = Union[Connection, PoolConnectionProxy]
+
 
 @dataclass
 class AsyncPgPoolConfig(GenericPoolConfig):
@@ -70,9 +73,12 @@ class AsyncPgPoolConfig(GenericPoolConfig):
 
 
 @dataclass
-class AsyncPgConfig(GenericDatabaseConfig):
+class AsyncPgConfig(DatabaseConfigProtocol[PgConnection, Pool], GenericDatabaseConfig):
     """Asyncpg Configuration."""
 
+    __is_async__ = True
+    __supports_connection_pooling__ = True
+
     pool_config: AsyncPgPoolConfig | None = None
     """Asyncpg Pool configuration"""
     json_deserializer: Callable[[str], Any] = decode_json
@@ -132,9 +138,7 @@ class AsyncPgConfig(GenericDatabaseConfig):
         return self.create_pool()
 
     @asynccontextmanager
-    async def provide_connection(
-        self, *args: Any, **kwargs: Any
-    ) -> AsyncGenerator[Connection | PoolConnectionProxy, None]:
+    async def provide_connection(self, *args: Any, **kwargs: Any) -> AsyncGenerator[PoolConnectionProxy, None]:
         """Create a connection instance.
 
         Returns:

sqlspec/adapters/duckdb/__init__.py

@@ -0,0 +1,3 @@
+from sqlspec.adapters.duckdb.config import DuckDBConfig
+
+__all__ = ("DuckDBConfig",)

sqlspec/adapters/duckdb/config.py

@@ -4,14 +4,15 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, cast
 
-from sqlspec.config import GenericDatabaseConfig
+from duckdb import DuckDBPyConnection
+
+from sqlspec.base import GenericDatabaseConfig, NoPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
 if TYPE_CHECKING:
     from collections.abc import Generator, Sequence
 
-    from duckdb import DuckDBPyConnection
 
 __all__ = ("DuckDBConfig", "ExtensionConfig")
 
@@ -23,21 +24,21 @@ class ExtensionConfig:
     This class provides configuration options for DuckDB extensions, including installation
     and post-install configuration settings.
 
-    Args:
-        name: The name of the extension to install
-        config: Optional configuration settings to apply after installation
-        force_install: Whether to force reinstall if already present
-        repository: Optional repository name to install from
-        repository_url: Optional repository URL to install from
-        version: Optional version of the extension to install
+    For details see: https://duckdb.org/docs/extensions/overview
     """
 
     name: str
+    """The name of the extension to install"""
     config: dict[str, Any] | None = None
+    """Optional configuration settings to apply after installation"""
     force_install: bool = False
+    """Whether to force reinstall if already present"""
     repository: str | None = None
+    """Optional repository name to install from"""
     repository_url: str | None = None
+    """Optional repository URL to install from"""
     version: str | None = None
+    """Optional version of the extension to install"""
 
     @classmethod
     def from_dict(cls, name: str, config: dict[str, Any] | bool | None = None) -> ExtensionConfig:
@@ -65,7 +66,7 @@ class ExtensionConfig:
 
 
 @dataclass
-class DuckDBConfig(GenericDatabaseConfig):
+class DuckDBConfig(NoPoolConfig[DuckDBPyConnection], GenericDatabaseConfig):
     """Configuration for DuckDB database connections.
 
     This class provides configuration options for DuckDB database connections, wrapping all parameters
@@ -114,13 +115,13 @@ class DuckDBConfig(GenericDatabaseConfig):
             msg = "When configuring extensions in the 'config' dictionary, the value must be a dictionary or sequence of extension names"
             raise ImproperConfigurationError(msg)
         if not isinstance(_e, dict):
-            _e = {str(ext): {"force_install": False} for ext in _e}
+            _e = {str(ext): {"force_install": False} for ext in _e}  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
 
-        if len(set(_e.keys()).intersection({ext.name for ext in self.extensions})) > 0:
+        if len(set(_e.keys()).intersection({ext.name for ext in self.extensions})) > 0:  # pyright: ignore[ reportUnknownArgumentType]
             msg = "Configuring the same extension in both 'extensions' and as a key in 'config['extensions']' is not allowed"
             raise ImproperConfigurationError(msg)
 
-        self.extensions.extend([ExtensionConfig.from_dict(name, ext_config) for name, ext_config in _e.items()])
+        self.extensions.extend([ExtensionConfig.from_dict(name, ext_config) for name, ext_config in _e.items()])  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
 
     def _configure_extensions(self, connection: DuckDBPyConnection) -> None:
         """Configure extensions for the connection.
@@ -177,7 +178,7 @@ class DuckDBConfig(GenericDatabaseConfig):
         import duckdb
 
         try:
-            connection = duckdb.connect(**self.connection_config_dict)
+            connection = duckdb.connect(**self.connection_config_dict)  # pyright: ignore[reportUnknownMemberType]
             self._configure_extensions(connection)
             return connection
         except Exception as e:

sqlspec/adapters/oracledb/__init__.py

@@ -1,4 +1,4 @@
-from .config import (
+from sqlspec.adapters.oracledb.config import (
     OracleAsyncDatabaseConfig,
     OracleAsyncPoolConfig,
     OracleSyncDatabaseConfig,

sqlspec/adapters/oracledb/config/_asyncio.py

@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class OracleAsyncPoolConfig(OracleGenericPoolConfig[AsyncConnectionPool, AsyncConnection]):
+class OracleAsyncPoolConfig(OracleGenericPoolConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Oracle Pool Config"""
 
 
 @dataclass
-class OracleAsyncDatabaseConfig(OracleGenericDatabaseConfig[AsyncConnectionPool, AsyncConnection]):
+class OracleAsyncDatabaseConfig(OracleGenericDatabaseConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Oracle database Configuration."""
 
+    __is_async__ = True
+    __supports_connection_pooling__ = True
+
     pool_config: OracleAsyncPoolConfig | None = None
     """Oracle Pool configuration"""
     pool_instance: AsyncConnectionPool | None = None
@@ -70,7 +73,7 @@ class OracleAsyncDatabaseConfig(OracleGenericDatabaseConfig[AsyncConnectionPool,
 
         pool_config = self.pool_config_dict
         self.pool_instance = oracledb_create_pool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."
             raise ImproperConfigurationError(msg)
         return self.pool_instance

sqlspec/adapters/oracledb/config/_common.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Generic, TypeVar
 
 from oracledb import ConnectionPool
 
-from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
 from sqlspec.typing import Empty
 
 if TYPE_CHECKING:
@@ -32,7 +32,7 @@ PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
 
 
 @dataclass
-class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+class OracleGenericPoolConfig(Generic[ConnectionT, PoolT], GenericPoolConfig):
     """Configuration for Oracle database connection pools.
 
     This class provides configuration options for both synchronous and asynchronous Oracle
@@ -58,7 +58,7 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
     """New password for password change operations"""
     wallet_password: str | EmptyType = Empty
     """Password for accessing Oracle Wallet"""
-    access_token: str | tuple | Callable | EmptyType = Empty
+    access_token: str | tuple[str, ...] | Callable[[], str] | EmptyType = Empty
     """Token for token-based authentication"""
     host: str | EmptyType = Empty
     """Database server hostname"""
@@ -112,11 +112,11 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
     """If True, allows connections with different tags"""
     config_dir: str | EmptyType = Empty
     """Directory containing Oracle configuration files"""
-    appcontext: list | EmptyType = Empty
+    appcontext: list[str] | EmptyType = Empty
     """Application context list"""
-    shardingkey: list | EmptyType = Empty
+    shardingkey: list[str] | EmptyType = Empty
     """Sharding key list"""
-    supershardingkey: list | EmptyType = Empty
+    supershardingkey: list[str] | EmptyType = Empty
     """Super sharding key list"""
     debug_jdwp: str | EmptyType = Empty
     """JDWP debugging string"""
@@ -137,7 +137,7 @@ class OracleGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
 
 
 @dataclass
-class OracleGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+class OracleGenericDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT], GenericDatabaseConfig):
     """Oracle database Configuration.
 
     This class provides the base configuration for Oracle database connections, extending

sqlspec/adapters/oracledb/config/_sync.py

@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class OracleSyncPoolConfig(OracleGenericPoolConfig[ConnectionPool, Connection]):
+class OracleSyncPoolConfig(OracleGenericPoolConfig[Connection, ConnectionPool]):
     """Sync Oracle Pool Config"""
 
 
 @dataclass
-class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Connection]):
+class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[Connection, ConnectionPool]):
     """Oracle database Configuration."""
 
+    __is_async__ = False
+    __supports_connection_pooling__ = True
+
     pool_config: OracleSyncPoolConfig | None = None
     """Oracle Pool configuration"""
     pool_instance: ConnectionPool | None = None
@@ -70,7 +73,7 @@ class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Conne
 
         pool_config = self.pool_config_dict
         self.pool_instance = oracledb_create_pool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."
             raise ImproperConfigurationError(msg)
         return self.pool_instance
@@ -91,5 +94,5 @@ class OracleSyncDatabaseConfig(OracleGenericDatabaseConfig[ConnectionPool, Conne
             A connection instance.
         """
         db_pool = self.provide_pool(*args, **kwargs)
-        with db_pool.acquire() as connection:
+        with db_pool.acquire() as connection:  # pyright: ignore[reportUnknownMemberType]
             yield connection

sqlspec/adapters/psycopg/config/__init__.py

@@ -1,5 +1,5 @@
-from ._async import PsycoPgAsyncDatabaseConfig, PsycoPgAsyncPoolConfig
-from ._sync import PsycoPgSyncDatabaseConfig, PsycoPgSyncPoolConfig
+from sqlspec.adapters.psycopg.config._async import PsycoPgAsyncDatabaseConfig, PsycoPgAsyncPoolConfig
+from sqlspec.adapters.psycopg.config._sync import PsycoPgSyncDatabaseConfig, PsycoPgSyncPoolConfig
 
 __all__ = (
     "PsycoPgAsyncDatabaseConfig",

sqlspec/adapters/psycopg/config/_async.py

@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class PsycoPgAsyncPoolConfig(PsycoPgGenericPoolConfig[AsyncConnectionPool, AsyncConnection]):
+class PsycoPgAsyncPoolConfig(PsycoPgGenericPoolConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Psycopg Pool Config"""
 
 
 @dataclass
-class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPool, AsyncConnection]):
+class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnection, AsyncConnectionPool]):
     """Async Psycopg database Configuration."""
 
+    __is_async__ = True
+    __supports_connection_pooling__ = True
+
     pool_config: PsycoPgAsyncPoolConfig | None = None
     """Psycopg Pool configuration"""
     pool_instance: AsyncConnectionPool | None = None
@@ -58,7 +61,7 @@ class PsycoPgAsyncDatabaseConfig(PsycoPgGenericDatabaseConfig[AsyncConnectionPoo
 
         pool_config = self.pool_config_dict
         self.pool_instance = AsyncConnectionPool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
             raise ImproperConfigurationError(msg)
         return self.pool_instance

sqlspec/adapters/psycopg/config/_common.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Generic, TypeVar
 
-from sqlspec.config import GenericDatabaseConfig, GenericPoolConfig
+from sqlspec.base import DatabaseConfigProtocol, GenericDatabaseConfig, GenericPoolConfig
 from sqlspec.typing import Empty
 
 if TYPE_CHECKING:
@@ -27,7 +27,7 @@ PoolT = TypeVar("PoolT", bound="ConnectionPool | AsyncConnectionPool")
 
 
 @dataclass
-class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
+class PsycoPgGenericPoolConfig(Generic[ConnectionT, PoolT], GenericPoolConfig):
     """Configuration for Psycopg connection pools.
 
     This class provides configuration options for both synchronous and asynchronous Psycopg
@@ -62,7 +62,7 @@ class PsycoPgGenericPoolConfig(Generic[PoolT, ConnectionT], GenericPoolConfig):
 
 
 @dataclass
-class PsycoPgGenericDatabaseConfig(Generic[PoolT, ConnectionT], GenericDatabaseConfig):
+class PsycoPgGenericDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT], GenericDatabaseConfig):
     """Psycopg database Configuration.
 
     This class provides the base configuration for Psycopg database connections, extending

sqlspec/adapters/psycopg/config/_sync.py

@@ -26,14 +26,17 @@ __all__ = (
 
 
 @dataclass
-class PsycoPgSyncPoolConfig(PsycoPgGenericPoolConfig[ConnectionPool, Connection]):
+class PsycoPgSyncPoolConfig(PsycoPgGenericPoolConfig[Connection, ConnectionPool]):
     """Sync Psycopg Pool Config"""
 
 
 @dataclass
-class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Connection]):
+class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[Connection, ConnectionPool]):
     """Sync Psycopg database Configuration."""
 
+    __is_async__ = False
+    __supports_connection_pooling__ = True
+
     pool_config: PsycoPgSyncPoolConfig | None = None
     """Psycopg Pool configuration"""
     pool_instance: ConnectionPool | None = None
@@ -58,7 +61,7 @@ class PsycoPgSyncDatabaseConfig(PsycoPgGenericDatabaseConfig[ConnectionPool, Con
 
         pool_config = self.pool_config_dict
         self.pool_instance = ConnectionPool(**pool_config)
-        if self.pool_instance is None:
+        if self.pool_instance is None:  # pyright: ignore[reportUnnecessaryComparison]
             msg = "Could not configure the 'pool_instance'. Please check your configuration."  # type: ignore[unreachable]
             raise ImproperConfigurationError(msg)
         return self.pool_instance

sqlspec/adapters/sqlite/config.py

@@ -4,7 +4,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Literal
 
-from sqlspec.config import GenericDatabaseConfig
+from sqlspec.base import GenericDatabaseConfig, NoPoolConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
 
@@ -16,7 +16,7 @@ __all__ = ("SqliteConfig",)
 
 
 @dataclass
-class SqliteConfig(GenericDatabaseConfig):
+class SqliteConfig(NoPoolConfig["Connection"], GenericDatabaseConfig):
     """Configuration for SQLite database connections.
 
     This class provides configuration options for SQLite database connections, wrapping all parameters
@@ -25,7 +25,7 @@ class SqliteConfig(GenericDatabaseConfig):
     For details see: https://docs.python.org/3/library/sqlite3.html#sqlite3.connect
     """
 
-    database: str
+    database: str = ":memory:"
     """The path to the database file to be opened. Pass ":memory:" to open a connection to a database that resides in RAM instead of on disk."""
 
     timeout: float | EmptyType = Empty

sqlspec/base.py

@@ -0,0 +1,87 @@
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator, Awaitable, Generator
+from contextlib import AbstractAsyncContextManager, AbstractContextManager
+from dataclasses import dataclass
+from typing import Any, ClassVar, Generic, TypeVar, Union
+
+__all__ = (
+    "DatabaseConfigProtocol",
+    "GenericPoolConfig",
+    "NoPoolConfig",
+)
+
+ConnectionT = TypeVar("ConnectionT")
+PoolT = TypeVar("PoolT")
+
+
+@dataclass
+class DatabaseConfigProtocol(Generic[ConnectionT, PoolT], ABC):
+    """Protocol defining the interface for database configurations."""
+
+    __is_async__: ClassVar[bool] = False
+    __supports_connection_pooling__: ClassVar[bool] = False
+
+    @abstractmethod
+    def create_connection(self) -> Union[ConnectionT, Awaitable[ConnectionT]]:
+        """Create and return a new database connection."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def provide_connection(
+        self, *args: Any, **kwargs: Any
+    ) -> Union[
+        Generator[ConnectionT, None, None],
+        AsyncGenerator[ConnectionT, None],
+        AbstractContextManager[ConnectionT],
+        AbstractAsyncContextManager[ConnectionT],
+    ]:
+        """Provide a database connection context manager."""
+        raise NotImplementedError
+
+    @property
+    @abstractmethod
+    def connection_config_dict(self) -> dict[str, Any]:
+        """Return the connection configuration as a dict."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def create_pool(self) -> Union[PoolT, Awaitable[PoolT]]:
+        """Create and return connection pool."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def provide_pool(
+        self, *args: Any, **kwargs: Any
+    ) -> Union[PoolT, Awaitable[PoolT], AbstractContextManager[PoolT], AbstractAsyncContextManager[PoolT]]:
+        """Provide pool instance."""
+        raise NotImplementedError
+
+    @property
+    def is_async(self) -> bool:
+        """Return whether the configuration is for an async database."""
+        return self.__is_async__
+
+    @property
+    def support_connection_pooling(self) -> bool:
+        """Return whether the configuration supports connection pooling."""
+        return self.__supports_connection_pooling__
+
+
+class NoPoolConfig(DatabaseConfigProtocol[ConnectionT, None]):
+    """Base class for database configurations that do not implement a pool."""
+
+    def create_pool(self) -> None:
+        """This database backend has not implemented the pooling configurations."""
+
+    def provide_pool(self, *args: Any, **kwargs: Any) -> None:
+        """This database backend has not implemented the pooling configurations."""
+
+
+@dataclass
+class GenericPoolConfig:
+    """Generic Database Pool Configuration."""
+
+
+@dataclass
+class GenericDatabaseConfig:
+    """Generic Database Configuration."""

sqlspec/filters.py

@@ -25,12 +25,13 @@ __all__ = (
 )
 
 T = TypeVar("T")
+StatementT = TypeVar("StatementT", bound="str")
 
 
 class StatementFilter(Protocol):
     """Protocol for filters that can be appended to a statement."""
 
-    def append_to_statement(self, statement: str) -> str:
+    def append_to_statement(self, statement: StatementT) -> StatementT:
         """Append the filter to the statement."""
         return statement