sqlspec 0.11.1__py3-none-any.whl → 0.12.1__py3-none-any.whl

sqlspec/base.py

@@ -1,196 +1,29 @@
-# ruff: noqa: PLR6301
+import asyncio
 import atexit
-import contextlib
-import re
-from abc import ABC, abstractmethod
-from collections.abc import Awaitable, Sequence
-from dataclasses import dataclass, field
-from typing import (
-    TYPE_CHECKING,
-    Annotated,
-    Any,
-    ClassVar,
-    Generic,
-    Optional,
-    TypeVar,
-    Union,
-    cast,
-    overload,
+from collections.abc import Awaitable, Coroutine
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
+
+from sqlspec.config import (
+    AsyncConfigT,
+    AsyncDatabaseConfig,
+    DatabaseConfigProtocol,
+    DriverT,
+    NoPoolAsyncConfig,
+    NoPoolSyncConfig,
+    SyncConfigT,
+    SyncDatabaseConfig,
 )
-
-from sqlspec.exceptions import NotFoundError
-from sqlspec.statement import SQLStatement
-from sqlspec.typing import ConnectionT, ModelDTOT, PoolT, StatementParameterType, T
-from sqlspec.utils.sync_tools import ensure_async_
+from sqlspec.utils.logging import get_logger
 
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager, AbstractContextManager
 
-    from sqlspec.filters import StatementFilter
-
-
-__all__ = (
-    "AsyncDatabaseConfig",
-    "AsyncDriverAdapterProtocol",
-    "CommonDriverAttributes",
-    "DatabaseConfigProtocol",
-    "GenericPoolConfig",
-    "NoPoolAsyncConfig",
-    "NoPoolSyncConfig",
-    "SQLSpec",
-    "SQLStatement",
-    "SyncDatabaseConfig",
-    "SyncDriverAdapterProtocol",
-)
-
-AsyncConfigT = TypeVar("AsyncConfigT", bound="Union[AsyncDatabaseConfig[Any, Any, Any], NoPoolAsyncConfig[Any, Any]]")
-SyncConfigT = TypeVar("SyncConfigT", bound="Union[SyncDatabaseConfig[Any, Any, Any], NoPoolSyncConfig[Any, Any]]")
-ConfigT = TypeVar(
-    "ConfigT",
-    bound="Union[Union[AsyncDatabaseConfig[Any, Any, Any], NoPoolAsyncConfig[Any, Any]], SyncDatabaseConfig[Any, Any, Any], NoPoolSyncConfig[Any, Any]]",
-)
-DriverT = TypeVar("DriverT", bound="Union[SyncDriverAdapterProtocol[Any], AsyncDriverAdapterProtocol[Any]]")
-# Regex to find :param or %(param)s style placeholders, skipping those inside quotes
-PARAM_REGEX = re.compile(
-    r"""
-    (?P<dquote>"([^"]|\\")*") | # Double-quoted strings
-    (?P<squote>'([^']|\\')*') | # Single-quoted strings
-    : (?P<var_name_colon>[a-zA-Z_][a-zA-Z0-9_]*) | # :var_name
-    % \( (?P<var_name_perc>[a-zA-Z_][a-zA-Z0-9_]*) \) s # %(var_name)s
-    """,
-    re.VERBOSE,
-)
-
-
-@dataclass
-class DatabaseConfigProtocol(ABC, Generic[ConnectionT, PoolT, DriverT]):
-    """Protocol defining the interface for database configurations."""
-
-    connection_type: "type[ConnectionT]" = field(init=False)
-    driver_type: "type[DriverT]" = field(init=False)
-    pool_instance: "Optional[PoolT]" = field(default=None)
-    __is_async__: "ClassVar[bool]" = False
-    __supports_connection_pooling__: "ClassVar[bool]" = False
-
-    def __hash__(self) -> int:
-        return id(self)
-
-    @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[AbstractContextManager[ConnectionT], AbstractAsyncContextManager[ConnectionT]]":
-        """Provide a database connection context manager."""
-        raise NotImplementedError
-
-    @abstractmethod
-    def provide_session(
-        self,
-        *args: Any,
-        **kwargs: Any,
-    ) -> "Union[AbstractContextManager[DriverT], AbstractAsyncContextManager[DriverT]]":
-        """Provide a database session 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 close_pool(self) -> "Optional[Awaitable[None]]":
-        """Terminate the 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 NoPoolSyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
-    """Base class for a sync database configurations that do not implement a pool."""
-
-    __is_async__ = False
-    __supports_connection_pooling__ = False
-    pool_instance: None = None
-
-    def create_pool(self) -> None:
-        """This database backend has not implemented the pooling configurations."""
-        return
+    from sqlspec.typing import ConnectionT, PoolT
 
-    def close_pool(self) -> None:
-        return
 
-    def provide_pool(self, *args: Any, **kwargs: Any) -> None:
-        """This database backend has not implemented the pooling configurations."""
-        return
+__all__ = ("SQLSpec",)
 
-
-class NoPoolAsyncConfig(DatabaseConfigProtocol[ConnectionT, None, DriverT]):
-    """Base class for an async database configurations that do not implement a pool."""
-
-    __is_async__ = True
-    __supports_connection_pooling__ = False
-    pool_instance: None = None
-
-    async def create_pool(self) -> None:
-        """This database backend has not implemented the pooling configurations."""
-        return
-
-    async def close_pool(self) -> None:
-        return
-
-    def provide_pool(self, *args: Any, **kwargs: Any) -> None:
-        """This database backend has not implemented the pooling configurations."""
-        return
-
-
-@dataclass
-class GenericPoolConfig:
-    """Generic Database Pool Configuration."""
-
-
-@dataclass
-class SyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Sync Database Configuration."""
-
-    __is_async__ = False
-    __supports_connection_pooling__ = True
-
-
-@dataclass
-class AsyncDatabaseConfig(DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]):
-    """Generic Async Database Configuration."""
-
-    __is_async__ = True
-    __supports_connection_pooling__ = True
+logger = get_logger()
 
 
 class SQLSpec:
@@ -200,34 +33,64 @@ class SQLSpec:
 
     def __init__(self) -> None:
         self._configs: dict[Any, DatabaseConfigProtocol[Any, Any, Any]] = {}
-        # Register the cleanup handler to run at program exit
         atexit.register(self._cleanup_pools)
 
+    @staticmethod
+    def _get_config_name(obj: Any) -> str:
+        """Get display name for configuration object."""
+        # Try to get __name__ attribute if it exists, otherwise use str()
+        return getattr(obj, "__name__", str(obj))
+
     def _cleanup_pools(self) -> None:
-        """Clean up all open database pools at program exit."""
-        for config in self._configs.values():
-            if config.support_connection_pooling and config.pool_instance is not None:
-                with contextlib.suppress(Exception):
-                    ensure_async_(config.close_pool)()
+        """Clean up all registered connection pools."""
+        cleaned_count = 0
+
+        for config_type, config in self._configs.items():
+            if config.supports_connection_pooling:
+                try:
+                    if config.is_async:
+                        close_pool_awaitable = config.close_pool()
+                        if close_pool_awaitable is not None:
+                            try:
+                                loop = asyncio.get_running_loop()
+                                if loop.is_running():
+                                    _task = asyncio.ensure_future(close_pool_awaitable, loop=loop)  # noqa: RUF006
+
+                                else:
+                                    asyncio.run(cast("Coroutine[Any, Any, None]", close_pool_awaitable))
+                            except RuntimeError:  # No running event loop
+                                asyncio.run(cast("Coroutine[Any, Any, None]", close_pool_awaitable))
+                    else:
+                        config.close_pool()
+                    cleaned_count += 1
+                except Exception as e:
+                    logger.warning("Failed to clean up pool for config %s: %s", config_type.__name__, e)
+
+        self._configs.clear()
+        logger.info("Pool cleanup completed. Cleaned %d pools.", cleaned_count)
 
     @overload
-    def add_config(self, config: "SyncConfigT") -> "type[SyncConfigT]": ...
+    def add_config(self, config: "SyncConfigT") -> "type[SyncConfigT]":  # pyright: ignore[reportInvalidTypeVarUse]
+        ...
 
     @overload
-    def add_config(self, config: "AsyncConfigT") -> "type[AsyncConfigT]": ...
+    def add_config(self, config: "AsyncConfigT") -> "type[AsyncConfigT]":  # pyright: ignore[reportInvalidTypeVarUse]
+        ...
 
-    def add_config(
-        self,
-        config: "Union[SyncConfigT, AsyncConfigT]",
-    ) -> "Union[Annotated[type[SyncConfigT], int], Annotated[type[AsyncConfigT], int]]":  # pyright: ignore[reportInvalidTypeVarUse]
-        """Add a new configuration to the manager.
+    def add_config(self, config: "Union[SyncConfigT, AsyncConfigT]") -> "type[Union[SyncConfigT, AsyncConfigT]]":  # pyright: ignore[reportInvalidTypeVarUse]
+        """Add a configuration instance to the registry.
+
+        Args:
+            config: The configuration instance to add.
 
         Returns:
-            A unique type key that can be used to retrieve the configuration later.
+            The type of the added configuration, annotated with its ID for potential use in type systems.
         """
-        key = Annotated[type(config), id(config)]  # type: ignore[valid-type]
-        self._configs[key] = config
-        return key  # type: ignore[return-value]  # pyright: ignore[reportReturnType]
+        config_type = type(config)
+        if config_type in self._configs:
+            logger.warning("Configuration for %s already exists. Overwriting.", config_type.__name__)
+        self._configs[config_type] = config
+        return config_type
 
     @overload
     def get_config(self, name: "type[SyncConfigT]") -> "SyncConfigT": ...
@@ -236,21 +99,26 @@ class SQLSpec:
     def get_config(self, name: "type[AsyncConfigT]") -> "AsyncConfigT": ...
 
     def get_config(
-        self,
-        name: "Union[type[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]], Any]",
+        self, name: "Union[type[DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]], Any]"
     ) -> "DatabaseConfigProtocol[ConnectionT, PoolT, DriverT]":
-        """Retrieve a configuration by its type.
+        """Retrieve a configuration instance by its type or a key.
+
+        Args:
+            name: The type of the configuration or a key associated with it.
 
         Returns:
-            DatabaseConfigProtocol: The configuration instance for the given type.
+            The configuration instance.
 
         Raises:
-            KeyError: If no configuration is found for the given type.
+            KeyError: If the configuration is not found.
         """
         config = self._configs.get(name)
         if not config:
+            logger.error("No configuration found for %s", name)
             msg = f"No configuration found for {name}"
             raise KeyError(msg)
+
+        logger.debug("Retrieved configuration: %s", self._get_config_name(name))
         return config
 
     @overload
@@ -258,7 +126,9 @@ class SQLSpec:
         self,
         name: Union[
             "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
-            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",  # pyright: ignore[reportInvalidTypeVarUse]
+            "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "ConnectionT": ...
 
@@ -267,7 +137,9 @@ class SQLSpec:
         self,
         name: Union[
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
-            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",  # pyright: ignore[reportInvalidTypeVarUse]
+            "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Awaitable[ConnectionT]": ...
 
@@ -278,17 +150,28 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Union[ConnectionT, Awaitable[ConnectionT]]":
-        """Create and return a new database connection from the specified configuration.
+        """Get a database connection for the specified configuration.
 
         Args:
-            name: The configuration type to use for creating the connection.
+            name: The configuration name or instance.
 
         Returns:
-            Either a connection instance or an awaitable that resolves to a connection instance.
+            A database connection or an awaitable yielding a connection.
         """
-        config = self.get_config(name)
+        if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig)):
+            config = name
+            config_name = config.__class__.__name__
+        else:
+            config = self.get_config(name)
+            config_name = self._get_config_name(name)
+
+        logger.debug("Getting connection for config: %s", config_name, extra={"config_type": config_name})
         return config.create_connection()
 
     @overload
@@ -297,6 +180,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "DriverT": ...
 
@@ -306,6 +191,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Awaitable[DriverT]": ...
 
@@ -316,25 +203,45 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Union[DriverT, Awaitable[DriverT]]":
-        """Create and return a new database session from the specified configuration.
+        """Get a database session (driver adapter) for the specified configuration.
 
         Args:
-            name: The configuration type to use for creating the session.
+            name: The configuration name or instance.
 
         Returns:
-            Either a driver instance or an awaitable that resolves to a driver instance.
+            A driver adapter instance or an awaitable yielding one.
         """
-        config = self.get_config(name)
-        connection = self.get_connection(name)
-        if isinstance(connection, Awaitable):
+        if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig)):
+            config = name
+            config_name = config.__class__.__name__
+        else:
+            config = self.get_config(name)
+            config_name = self._get_config_name(name)
+
+        logger.debug("Getting session for config: %s", config_name, extra={"config_type": config_name})
+
+        connection_obj = self.get_connection(name)
+
+        if isinstance(connection_obj, Awaitable):
+
+            async def _create_driver_async() -> "DriverT":
+                resolved_connection = await connection_obj  # pyright: ignore
+                return cast(  # pyright: ignore
+                    "DriverT",
+                    config.driver_type(connection=resolved_connection, default_row_type=config.default_row_type),
+                )
 
-            async def _create_session() -> DriverT:
-                return cast("DriverT", config.driver_type(await connection))  # pyright: ignore
+            return _create_driver_async()
 
-            return _create_session()
-        return cast("DriverT", config.driver_type(connection))  # pyright: ignore
+        return cast(  # pyright: ignore
+            "DriverT", config.driver_type(connection=connection_obj, default_row_type=config.default_row_type)
+        )
 
     @overload
     def provide_connection(
@@ -342,6 +249,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -353,6 +262,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -365,6 +276,10 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -372,14 +287,22 @@ class SQLSpec:
         """Create and provide a database connection from the specified configuration.
 
         Args:
-            name: The configuration type to use for creating the connection.
-            *args: Positional arguments to pass to the configuration's provide_connection method.
-            **kwargs: Keyword arguments to pass to the configuration's provide_connection method.
+            name: The configuration name or instance.
+            *args: Positional arguments to pass to the config's provide_connection.
+            **kwargs: Keyword arguments to pass to the config's provide_connection.
+
 
         Returns:
-            Either a synchronous or asynchronous context manager that provides a database connection.
+            A sync or async context manager yielding a connection.
         """
-        config = self.get_config(name)
+        if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig)):
+            config = name
+            config_name = config.__class__.__name__
+        else:
+            config = self.get_config(name)
+            config_name = self._get_config_name(name)
+
+        logger.debug("Providing connection context for config: %s", config_name, extra={"config_type": config_name})
         return config.provide_connection(*args, **kwargs)
 
     @overload
@@ -388,6 +311,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -399,6 +324,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -411,6 +338,10 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
         *args: Any,
         **kwargs: Any,
@@ -418,26 +349,38 @@ class SQLSpec:
         """Create and provide a database session from the specified configuration.
 
         Args:
-            name: The configuration type to use for creating the session.
-            *args: Positional arguments to pass to the configuration's provide_session method.
-            **kwargs: Keyword arguments to pass to the configuration's provide_session method.
+            name: The configuration name or instance.
+            *args: Positional arguments to pass to the config's provide_session.
+            **kwargs: Keyword arguments to pass to the config's provide_session.
 
         Returns:
-            Either a synchronous or asynchronous context manager that provides a database session.
+            A sync or async context manager yielding a driver adapter instance.
         """
-        config = self.get_config(name)
+        if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig)):
+            config = name
+            config_name = config.__class__.__name__
+        else:
+            config = self.get_config(name)
+            config_name = self._get_config_name(name)
+
+        logger.debug("Providing session context for config: %s", config_name, extra={"config_type": config_name})
         return config.provide_session(*args, **kwargs)
 
     @overload
     def get_pool(
-        self, name: "type[Union[NoPoolSyncConfig[ConnectionT, DriverT], NoPoolAsyncConfig[ConnectionT, DriverT]]]"
-    ) -> "None": ...  # pyright: ignore[reportInvalidTypeVarUse]
-
+        self,
+        name: "Union[type[Union[NoPoolSyncConfig[ConnectionT, DriverT], NoPoolAsyncConfig[ConnectionT, DriverT]]], NoPoolSyncConfig[ConnectionT, DriverT], NoPoolAsyncConfig[ConnectionT, DriverT]]",
+    ) -> "None": ...
     @overload
-    def get_pool(self, name: "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]") -> "type[PoolT]": ...  # pyright: ignore[reportInvalidTypeVarUse]
-
+    def get_pool(
+        self,
+        name: "Union[type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]], SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+    ) -> "type[PoolT]": ...
     @overload
-    def get_pool(self, name: "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]") -> "Awaitable[type[PoolT]]": ...  # pyright: ignore[reportInvalidTypeVarUse]
+    def get_pool(
+        self,
+        name: "Union[type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]],AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+    ) -> "Awaitable[type[PoolT]]": ...
 
     def get_pool(
         self,
@@ -446,20 +389,32 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Union[type[PoolT], Awaitable[type[PoolT]], None]":
-        """Create and return a connection pool from the specified configuration.
+        """Get the connection pool for the specified configuration.
 
         Args:
-            name: The configuration type to use for creating the pool.
+            name: The configuration name or instance.
 
         Returns:
-            Either a pool instance, an awaitable that resolves to a pool instance, or None
-            if the configuration does not support connection pooling.
+            The connection pool, an awaitable yielding the pool, or None if not supported.
         """
-        config = self.get_config(name)
-        if config.support_connection_pooling:
+        config = (
+            name
+            if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig))
+            else self.get_config(name)
+        )
+        config_name = config.__class__.__name__
+
+        if config.supports_connection_pooling:
+            logger.debug("Getting pool for config: %s", config_name, extra={"config_type": config_name})
             return cast("Union[type[PoolT], Awaitable[type[PoolT]]]", config.create_pool())
+
+        logger.debug("Config %s does not support connection pooling", config_name)
         return None
 
     @overload
@@ -468,6 +423,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolSyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "None": ...
 
@@ -477,6 +434,8 @@ class SQLSpec:
         name: Union[
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Awaitable[None]": ...
 
@@ -487,553 +446,30 @@ class SQLSpec:
             "type[NoPoolAsyncConfig[ConnectionT, DriverT]]",
             "type[SyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
             "type[AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]]",
+            "NoPoolSyncConfig[ConnectionT, DriverT]",
+            "SyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
+            "NoPoolAsyncConfig[ConnectionT, DriverT]",
+            "AsyncDatabaseConfig[ConnectionT, PoolT, DriverT]",
         ],
     ) -> "Optional[Awaitable[None]]":
         """Close the connection pool for the specified configuration.
 
         Args:
-            name: The configuration type whose pool to close.
+            name: The configuration name or instance.
 
         Returns:
-            An awaitable if the configuration is async, otherwise None.
+            None, or an awaitable if closing an async pool.
         """
-        config = self.get_config(name)
-        if config.support_connection_pooling:
+        if isinstance(name, (NoPoolSyncConfig, NoPoolAsyncConfig, SyncDatabaseConfig, AsyncDatabaseConfig)):
+            config = name
+            config_name = config.__class__.__name__
+        else:
+            config = self.get_config(name)
+            config_name = self._get_config_name(name)
+
+        if config.supports_connection_pooling:
+            logger.debug("Closing pool for config: %s", config_name, extra={"config_type": config_name})
             return config.close_pool()
-        return None
-
-
-class CommonDriverAttributes(Generic[ConnectionT]):
-    """Common attributes and methods for driver adapters."""
-
-    dialect: str
-    """The SQL dialect supported by the underlying database driver (e.g., 'postgres', 'mysql')."""
-    connection: ConnectionT
-    """The connection to the underlying database."""
-    __supports_arrow__: ClassVar[bool] = False
-    """Indicates if the driver supports Apache Arrow operations."""
-
-    def _connection(self, connection: "Optional[ConnectionT]" = None) -> "ConnectionT":
-        return connection if connection is not None else self.connection
-
-    @staticmethod
-    def check_not_found(item_or_none: Optional[T] = None) -> T:
-        """Raise :exc:`sqlspec.exceptions.NotFoundError` if ``item_or_none`` is ``None``.
-
-        Args:
-            item_or_none: Item to be tested for existence.
-
-        Raises:
-            NotFoundError: If ``item_or_none`` is ``None``
-
-        Returns:
-            The item, if it exists.
-        """
-        if item_or_none is None:
-            msg = "No result found when one was expected"
-            raise NotFoundError(msg)
-        return item_or_none
-
-    def _process_sql_params(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        **kwargs: Any,
-    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
-        """Process SQL query and parameters using SQLStatement for validation and formatting.
-
-        Args:
-            sql: The SQL query string.
-            parameters: Parameters for the query.
-            *filters: Statement filters to apply.
-            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
-
-        Returns:
-            A tuple containing the processed SQL query and parameters.
-        """
-        # Instantiate SQLStatement with parameters and kwargs for internal merging
-        stmt = SQLStatement(sql=sql, parameters=parameters, kwargs=kwargs or None)
-
-        # Apply all statement filters
-        for filter_obj in filters:
-            stmt = stmt.apply_filter(filter_obj)
-
-        # Process uses the merged parameters internally
-        processed = stmt.process()
-        return processed[0], processed[1]  # Return only the SQL and parameters, discard the third element
-
-
-class SyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generic[ConnectionT]):
-    connection: "ConnectionT"
-
-    def __init__(self, connection: "ConnectionT", **kwargs: Any) -> None:
-        self.connection = connection
-
-    @overload
-    @abstractmethod
-    def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Sequence[dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "Sequence[ModelDTOT]": ...
-
-    @abstractmethod
-    def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-        **kwargs: Any,
-    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]": ...
-
-    @overload
-    @abstractmethod
-    def select_one(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "dict[str, Any]": ...
-
-    @overload
-    @abstractmethod
-    def select_one(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "ModelDTOT": ...
-
-    @abstractmethod
-    def select_one(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-        **kwargs: Any,
-    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    def select_one_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Optional[dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    def select_one_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "Optional[ModelDTOT]": ...
-
-    @abstractmethod
-    def select_one_or_none(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-        **kwargs: Any,
-    ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]": ...
-
-    @overload
-    @abstractmethod
-    def select_value(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Any": ...
-
-    @overload
-    @abstractmethod
-    def select_value(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[T]",
-        **kwargs: Any,
-    ) -> "T": ...
-
-    @abstractmethod
-    def select_value(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[T]] = None,
-        **kwargs: Any,
-    ) -> "Union[T, Any]": ...
-
-    @overload
-    @abstractmethod
-    def select_value_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Optional[Any]": ...
-
-    @overload
-    @abstractmethod
-    def select_value_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[T]",
-        **kwargs: Any,
-    ) -> "Optional[T]": ...
-
-    @abstractmethod
-    def select_value_or_none(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[T]] = None,
-        **kwargs: Any,
-    ) -> "Optional[Union[T, Any]]": ...
-
-    @abstractmethod
-    def insert_update_delete(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        **kwargs: Any,
-    ) -> int: ...
-
-    @overload
-    @abstractmethod
-    def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "dict[str, Any]": ...
-
-    @overload
-    @abstractmethod
-    def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "ModelDTOT": ...
-
-    @abstractmethod
-    def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        *filters: "StatementFilter",
-        connection: Optional[ConnectionT] = None,
-        schema_type: Optional[type[ModelDTOT]] = None,
-        **kwargs: Any,
-    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
-
-    @abstractmethod
-    def execute_script(
-        self,
-        sql: str,
-        parameters: Optional[StatementParameterType] = None,
-        connection: Optional[ConnectionT] = None,
-        **kwargs: Any,
-    ) -> str: ...
-
-
-class AsyncDriverAdapterProtocol(CommonDriverAttributes[ConnectionT], ABC, Generic[ConnectionT]):
-    connection: "ConnectionT"
-
-    def __init__(self, connection: "ConnectionT") -> None:
-        self.connection = connection
-
-    @overload
-    @abstractmethod
-    async def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Sequence[dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    async def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "Sequence[ModelDTOT]": ...
-
-    @abstractmethod
-    async def select(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]": ...
-
-    @overload
-    @abstractmethod
-    async def select_one(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "dict[str, Any]": ...
-
-    @overload
-    @abstractmethod
-    async def select_one(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "ModelDTOT": ...
-
-    @abstractmethod
-    async def select_one(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    async def select_one_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Optional[dict[str, Any]]": ...
-
-    @overload
-    @abstractmethod
-    async def select_one_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "Optional[ModelDTOT]": ...
-
-    @abstractmethod
-    async def select_one_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]": ...
-
-    @overload
-    @abstractmethod
-    async def select_value(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Any": ...
-
-    @overload
-    @abstractmethod
-    async def select_value(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[T]",
-        **kwargs: Any,
-    ) -> "T": ...
-
-    @abstractmethod
-    async def select_value(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[T]]" = None,
-        **kwargs: Any,
-    ) -> "Union[T, Any]": ...
-
-    @overload
-    @abstractmethod
-    async def select_value_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "Optional[Any]": ...
-
-    @overload
-    @abstractmethod
-    async def select_value_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[T]",
-        **kwargs: Any,
-    ) -> "Optional[T]": ...
-
-    @abstractmethod
-    async def select_value_or_none(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[T]]" = None,
-        **kwargs: Any,
-    ) -> "Optional[Union[T, Any]]": ...
 
-    @abstractmethod
-    async def insert_update_delete(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        **kwargs: Any,
-    ) -> int: ...
-
-    @overload
-    @abstractmethod
-    async def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: None = None,
-        **kwargs: Any,
-    ) -> "dict[str, Any]": ...
-
-    @overload
-    @abstractmethod
-    async def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "type[ModelDTOT]",
-        **kwargs: Any,
-    ) -> "ModelDTOT": ...
-
-    @abstractmethod
-    async def insert_update_delete_returning(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        *filters: "StatementFilter",
-        connection: "Optional[ConnectionT]" = None,
-        schema_type: "Optional[type[ModelDTOT]]" = None,
-        **kwargs: Any,
-    ) -> "Union[ModelDTOT, dict[str, Any]]": ...
-
-    @abstractmethod
-    async def execute_script(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        connection: "Optional[ConnectionT]" = None,
-        **kwargs: Any,
-    ) -> str: ...
-
-
-DriverAdapterProtocol = Union[SyncDriverAdapterProtocol[ConnectionT], AsyncDriverAdapterProtocol[ConnectionT]]
+        logger.debug("Config %s does not support connection pooling - nothing to close", config_name)
+        return None