sqlspec 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

sqlspec/adapters/duckdb/__init__.py

@@ -1,7 +1,8 @@
 from sqlspec.adapters.duckdb.config import DuckDBConfig
-from sqlspec.adapters.duckdb.driver import DuckDBDriver
+from sqlspec.adapters.duckdb.driver import DuckDBConnection, DuckDBDriver
 
 __all__ = (
     "DuckDBConfig",
+    "DuckDBConnection",
     "DuckDBDriver",
 )

sqlspec/adapters/duckdb/config.py

@@ -2,10 +2,9 @@ from contextlib import contextmanager
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Callable, Optional, Union, cast
 
-from duckdb import DuckDBPyConnection
 from typing_extensions import Literal, NotRequired, TypedDict
 
-from sqlspec.adapters.duckdb.driver import DuckDBDriver
+from sqlspec.adapters.duckdb.driver import DuckDBConnection, DuckDBDriver
 from sqlspec.base import NoPoolSyncConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import Empty, EmptyType, dataclass_to_dict
@@ -69,7 +68,7 @@ class SecretConfig(TypedDict):
 
 
 @dataclass
-class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
+class DuckDBConfig(NoPoolSyncConfig["DuckDBConnection", "DuckDBDriver"]):
     """Configuration for DuckDB database connections.
 
     This class provides configuration options for DuckDB database connections, wrapping all parameters
@@ -96,10 +95,10 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
     """A dictionary of secrets to store in the connection for later retrieval."""
     auto_update_extensions: "bool" = False
     """Whether to automatically update on connection creation"""
-    on_connection_create: "Optional[Callable[[DuckDBPyConnection], Optional[DuckDBPyConnection]]]" = None
+    on_connection_create: "Optional[Callable[[DuckDBConnection], Optional[DuckDBConnection]]]" = None
     """A callable to be called after the connection is created."""
-    connection_type: "type[DuckDBPyConnection]" = field(init=False, default_factory=lambda: DuckDBPyConnection)
-    """The type of connection to create. Defaults to DuckDBPyConnection."""
+    connection_type: "type[DuckDBConnection]" = field(init=False, default_factory=lambda: DuckDBConnection)
+    """The type of connection to create. Defaults to DuckDBConnection."""
     driver_type: "type[DuckDBDriver]" = field(init=False, default_factory=lambda: DuckDBDriver)  # type: ignore[type-abstract,unused-ignore]
     """The type of driver to use. Defaults to DuckDBDriver."""
     pool_instance: "None" = field(init=False, default=None)
@@ -139,7 +138,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
             raise ImproperConfigurationError(msg) from e
         self.extensions.extend(config_exts)
 
-    def _configure_connection(self, connection: "DuckDBPyConnection") -> None:
+    def _configure_connection(self, connection: "DuckDBConnection") -> None:
         """Configure the connection.
 
         Args:
@@ -148,7 +147,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
         for key, value in cast("dict[str,Any]", self.config).items():
             connection.execute(f"SET {key}='{value}'")
 
-    def _configure_extensions(self, connection: "DuckDBPyConnection") -> None:
+    def _configure_extensions(self, connection: "DuckDBConnection") -> None:
         """Configure extensions for the connection.
 
         Args:
@@ -165,7 +164,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
             connection.execute("update extensions")
 
     @staticmethod
-    def _secret_exists(connection: "DuckDBPyConnection", name: "str") -> bool:
+    def _secret_exists(connection: "DuckDBConnection", name: "str") -> bool:
         """Check if a secret exists in the connection.
 
         Args:
@@ -179,7 +178,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
         return results is not None
 
     @classmethod
-    def _is_community_extension(cls, connection: "DuckDBPyConnection", name: "str") -> bool:
+    def _is_community_extension(cls, connection: "DuckDBConnection", name: "str") -> bool:
         """Check if an extension is a community extension.
 
         Args:
@@ -195,7 +194,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
         return results is None
 
     @classmethod
-    def _extension_installed(cls, connection: "DuckDBPyConnection", name: "str") -> bool:
+    def _extension_installed(cls, connection: "DuckDBConnection", name: "str") -> bool:
         """Check if a extension exists in the connection.
 
         Args:
@@ -211,7 +210,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
         return results is not None
 
     @classmethod
-    def _extension_loaded(cls, connection: "DuckDBPyConnection", name: "str") -> bool:
+    def _extension_loaded(cls, connection: "DuckDBConnection", name: "str") -> bool:
         """Check if a extension is loaded in the connection.
 
         Args:
@@ -229,7 +228,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
     @classmethod
     def _configure_secrets(
         cls,
-        connection: "DuckDBPyConnection",
+        connection: "DuckDBConnection",
         secrets: "Sequence[SecretConfig]",
     ) -> None:
         """Configure persistent secrets for the connection.
@@ -258,7 +257,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
             raise ImproperConfigurationError(msg) from e
 
     @classmethod
-    def _configure_extension(cls, connection: "DuckDBPyConnection", extension: "ExtensionConfig") -> None:
+    def _configure_extension(cls, connection: "DuckDBConnection", extension: "ExtensionConfig") -> None:
         """Configure a single extension for the connection.
 
         Args:
@@ -320,6 +319,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
                 "auto_update_extensions",
                 "driver_type",
                 "connection_type",
+                "connection_instance",
             },
             convert_nested=False,
         )
@@ -327,7 +327,7 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
             config["database"] = ":memory:"
         return config
 
-    def create_connection(self) -> "DuckDBPyConnection":
+    def create_connection(self) -> "DuckDBConnection":
         """Create and return a new database connection with configured extensions.
 
         Returns:
@@ -349,11 +349,10 @@ class DuckDBConfig(NoPoolSyncConfig["DuckDBPyConnection", "DuckDBDriver"]):
         except Exception as e:
             msg = f"Could not configure the DuckDB connection. Error: {e!s}"
             raise ImproperConfigurationError(msg) from e
-        else:
-            return connection
+        return connection
 
     @contextmanager
-    def provide_connection(self, *args: Any, **kwargs: Any) -> "Generator[DuckDBPyConnection, None, None]":
+    def provide_connection(self, *args: Any, **kwargs: Any) -> "Generator[DuckDBConnection, None, None]":
         """Create and provide a database connection.
 
         Yields:

sqlspec/adapters/duckdb/driver.py

@@ -1,37 +1,45 @@
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, Any, Optional, Union, cast
+from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
-from sqlspec.base import SyncArrowBulkOperationsMixin, SyncDriverAdapterProtocol, T
+from duckdb import DuckDBPyConnection
+
+from sqlspec.base import SyncDriverAdapterProtocol
+from sqlspec.mixins import SQLTranslatorMixin, SyncArrowBulkOperationsMixin
+from sqlspec.typing import ArrowTable, StatementParameterType
 
 if TYPE_CHECKING:
-    from collections.abc import Generator
+    from collections.abc import Generator, Sequence
 
-    from duckdb import DuckDBPyConnection
+    from sqlspec.typing import ArrowTable, ModelDTOT, StatementParameterType, T
 
-    from sqlspec.typing import ArrowTable, ModelDTOT, StatementParameterType
+__all__ = ("DuckDBConnection", "DuckDBDriver")
 
-__all__ = ("DuckDBDriver",)
+DuckDBConnection = DuckDBPyConnection
 
 
-class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDriverAdapterProtocol["DuckDBPyConnection"]):
+class DuckDBDriver(
+    SyncArrowBulkOperationsMixin["DuckDBConnection"],
+    SQLTranslatorMixin["DuckDBConnection"],
+    SyncDriverAdapterProtocol["DuckDBConnection"],
+):
     """DuckDB Sync Driver Adapter."""
 
-    connection: "DuckDBPyConnection"
+    connection: "DuckDBConnection"
     use_cursor: bool = True
     dialect: str = "duckdb"
 
-    def __init__(self, connection: "DuckDBPyConnection", use_cursor: bool = True) -> None:
+    def __init__(self, connection: "DuckDBConnection", use_cursor: bool = True) -> None:
         self.connection = connection
         self.use_cursor = use_cursor
 
     # --- Helper Methods --- #
-    def _cursor(self, connection: "DuckDBPyConnection") -> "DuckDBPyConnection":
+    def _cursor(self, connection: "DuckDBConnection") -> "DuckDBConnection":
         if self.use_cursor:
             return connection.cursor()
         return connection
 
     @contextmanager
-    def _with_cursor(self, connection: "DuckDBPyConnection") -> "Generator[DuckDBPyConnection, None, None]":
+    def _with_cursor(self, connection: "DuckDBConnection") -> "Generator[DuckDBConnection, None, None]":
         if self.use_cursor:
             cursor = self._cursor(connection)
             try:
@@ -42,17 +50,38 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
             yield connection
 
     # --- Public API Methods --- #
-
+    @overload
     def select(
         self,
         sql: str,
-        parameters: Optional["StatementParameterType"] = None,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Sequence[dict[str, Any]]": ...
+    @overload
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Sequence[ModelDTOT]": ...
+    def select(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
-    ) -> "list[Union[ModelDTOT, dict[str, Any]]]":
+    ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
         connection = self._connection(connection)
         sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
@@ -67,13 +96,35 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
                 return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore[reportUnknownArgumentType]
             return [dict(zip(column_names, row)) for row in results]  # pyright: ignore[reportUnknownArgumentType]
 
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def select_one(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
     def select_one(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: Optional["DuckDBConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]":
@@ -90,13 +141,35 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
             # Always return dictionaries
             return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
 
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[dict[str, Any]]": ...
+    @overload
+    def select_one_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "Optional[ModelDTOT]": ...
     def select_one_or_none(
         self,
         sql: str,
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: Optional["DuckDBConnection"] = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
@@ -113,13 +186,35 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
                 return cast("ModelDTOT", schema_type(**dict(zip(column_names, result))))  # pyright: ignore[reportUnknownArgumentType]
             return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
 
+    @overload
     def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: "Optional[DuckDBPyConnection]" = None,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Any": ...
+    @overload
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "T": ...
+    def select_value(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Union[T, Any]":
@@ -133,13 +228,35 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
                 return result[0]  # pyright: ignore
             return schema_type(result[0])  # type: ignore[call-arg]
 
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+    @overload
+    def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
     def select_value_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: "Optional[DuckDBPyConnection]" = None,
+        connection: "Optional[DuckDBConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
@@ -160,7 +277,7 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: Optional["DuckDBConnection"] = None,
         **kwargs: Any,
     ) -> int:
         connection = self._connection(connection)
@@ -169,23 +286,44 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             return getattr(cursor, "rowcount", -1)  # pyright: ignore[reportUnknownMemberType]
 
+    @overload
     def insert_update_delete_returning(
         self,
         sql: str,
-        parameters: Optional["StatementParameterType"] = None,
+        parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "dict[str, Any]": ...
+    @overload
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
+        schema_type: "type[ModelDTOT]",
+        **kwargs: Any,
+    ) -> "ModelDTOT": ...
+    def insert_update_delete_returning(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        /,
+        *,
+        connection: "Optional[DuckDBConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
-    ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
+    ) -> "Union[ModelDTOT, dict[str, Any]]":
         connection = self._connection(connection)
         sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-            if not result:
-                return None  # pyright: ignore[reportUnknownArgumentType]
+            result = self.check_not_found(result)  # pyright: ignore
             column_names = [col[0] for col in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
             if schema_type is not None:
                 return cast("ModelDTOT", schema_type(**dict(zip(column_names, result[0]))))  # pyright: ignore[reportUnknownArgumentType]
@@ -198,7 +336,7 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
         parameters: Optional["StatementParameterType"] = None,
         /,
         *,
-        connection: Optional["DuckDBPyConnection"] = None,
+        connection: Optional["DuckDBConnection"] = None,
         **kwargs: Any,
     ) -> str:
         connection = self._connection(connection)
@@ -215,7 +353,7 @@ class DuckDBDriver(SyncArrowBulkOperationsMixin["DuckDBPyConnection"], SyncDrive
         parameters: "Optional[StatementParameterType]" = None,
         /,
         *,
-        connection: "Optional[DuckDBPyConnection]" = None,
+        connection: "Optional[DuckDBConnection]" = None,
         **kwargs: Any,
     ) -> "ArrowTable":
         connection = self._connection(connection)

sqlspec/adapters/oracledb/__init__.py

@@ -4,13 +4,20 @@ from sqlspec.adapters.oracledb.config import (
     OracleSyncConfig,
     OracleSyncPoolConfig,
 )
-from sqlspec.adapters.oracledb.driver import OracleAsyncDriver, OracleSyncDriver
+from sqlspec.adapters.oracledb.driver import (
+    OracleAsyncConnection,
+    OracleAsyncDriver,
+    OracleSyncConnection,
+    OracleSyncDriver,
+)
 
 __all__ = (
     "OracleAsyncConfig",
+    "OracleAsyncConnection",
     "OracleAsyncDriver",
     "OracleAsyncPoolConfig",
     "OracleSyncConfig",
+    "OracleSyncConnection",
     "OracleSyncDriver",
     "OracleSyncPoolConfig",
 )

sqlspec/adapters/oracledb/config/_asyncio.py

@@ -3,10 +3,9 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Optional, cast
 
 from oracledb import create_pool_async as oracledb_create_pool  # pyright: ignore[reportUnknownVariableType]
-from oracledb.connection import AsyncConnection
 
 from sqlspec.adapters.oracledb.config._common import OracleGenericPoolConfig
-from sqlspec.adapters.oracledb.driver import OracleAsyncDriver
+from sqlspec.adapters.oracledb.driver import OracleAsyncConnection, OracleAsyncDriver
 from sqlspec.base import AsyncDatabaseConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import dataclass_to_dict
@@ -24,12 +23,12 @@ __all__ = (
 
 
 @dataclass
-class OracleAsyncPoolConfig(OracleGenericPoolConfig["AsyncConnection", "AsyncConnectionPool"]):
+class OracleAsyncPoolConfig(OracleGenericPoolConfig["OracleAsyncConnection", "AsyncConnectionPool"]):
     """Async Oracle Pool Config"""
 
 
 @dataclass
-class OracleAsyncConfig(AsyncDatabaseConfig["AsyncConnection", "AsyncConnectionPool", "OracleAsyncDriver"]):
+class OracleAsyncConfig(AsyncDatabaseConfig["OracleAsyncConnection", "AsyncConnectionPool", "OracleAsyncDriver"]):
     """Oracle Async database Configuration.
 
     This class provides the base configuration for Oracle database connections, extending
@@ -49,7 +48,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig["AsyncConnection", "AsyncConnectionP
 
     If set, the plugin will use the provided pool rather than instantiate one.
     """
-    connection_type: "type[AsyncConnection]" = field(init=False, default_factory=lambda: AsyncConnection)
+    connection_type: "type[OracleAsyncConnection]" = field(init=False, default_factory=lambda: OracleAsyncConnection)
     """Connection class to use.
 
     Defaults to :class:`AsyncConnection`.
@@ -111,7 +110,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig["AsyncConnection", "AsyncConnectionP
         msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
         raise ImproperConfigurationError(msg)
 
-    async def create_connection(self) -> "AsyncConnection":
+    async def create_connection(self) -> "OracleAsyncConnection":
         """Create and return a new oracledb async connection from the pool.
 
         Returns:
@@ -122,7 +121,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig["AsyncConnection", "AsyncConnectionP
         """
         try:
             pool = await self.provide_pool()
-            return cast("AsyncConnection", await pool.acquire())  # type: ignore[no-any-return,unused-ignore]
+            return cast("OracleAsyncConnection", await pool.acquire())  # type: ignore[no-any-return,unused-ignore]
         except Exception as e:
             msg = f"Could not configure the Oracle async connection. Error: {e!s}"
             raise ImproperConfigurationError(msg) from e
@@ -160,7 +159,7 @@ class OracleAsyncConfig(AsyncDatabaseConfig["AsyncConnection", "AsyncConnectionP
         return self.create_pool()
 
     @asynccontextmanager
-    async def provide_connection(self, *args: "Any", **kwargs: "Any") -> "AsyncGenerator[AsyncConnection, None]":
+    async def provide_connection(self, *args: "Any", **kwargs: "Any") -> "AsyncGenerator[OracleAsyncConnection, None]":
         """Create a connection instance.
 
         Yields:

sqlspec/adapters/oracledb/config/_sync.py

@@ -3,10 +3,9 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Optional
 
 from oracledb import create_pool as oracledb_create_pool  # pyright: ignore[reportUnknownVariableType]
-from oracledb.connection import Connection
 
 from sqlspec.adapters.oracledb.config._common import OracleGenericPoolConfig
-from sqlspec.adapters.oracledb.driver import OracleSyncDriver
+from sqlspec.adapters.oracledb.driver import OracleSyncConnection, OracleSyncDriver
 from sqlspec.base import SyncDatabaseConfig
 from sqlspec.exceptions import ImproperConfigurationError
 from sqlspec.typing import dataclass_to_dict
@@ -24,12 +23,12 @@ __all__ = (
 
 
 @dataclass
-class OracleSyncPoolConfig(OracleGenericPoolConfig["Connection", "ConnectionPool"]):
+class OracleSyncPoolConfig(OracleGenericPoolConfig["OracleSyncConnection", "ConnectionPool"]):
     """Sync Oracle Pool Config"""
 
 
 @dataclass
-class OracleSyncConfig(SyncDatabaseConfig["Connection", "ConnectionPool", "OracleSyncDriver"]):
+class OracleSyncConfig(SyncDatabaseConfig["OracleSyncConnection", "ConnectionPool", "OracleSyncDriver"]):
     """Oracle Sync database Configuration.
 
     This class provides the base configuration for Oracle database connections, extending
@@ -49,7 +48,7 @@ class OracleSyncConfig(SyncDatabaseConfig["Connection", "ConnectionPool", "Oracl
 
     If set, the plugin will use the provided pool rather than instantiate one.
     """
-    connection_type: "type[Connection]" = field(init=False, default_factory=lambda: Connection)  # pyright: ignore
+    connection_type: "type[OracleSyncConnection]" = field(init=False, default_factory=lambda: OracleSyncConnection)  # pyright: ignore
     """Connection class to use.
 
     Defaults to :class:`Connection`.
@@ -111,7 +110,7 @@ class OracleSyncConfig(SyncDatabaseConfig["Connection", "ConnectionPool", "Oracl
         msg = "'pool_config' methods can not be used when a 'pool_instance' is provided."
         raise ImproperConfigurationError(msg)
 
-    def create_connection(self) -> "Connection":
+    def create_connection(self) -> "OracleSyncConnection":
         """Create and return a new oracledb connection from the pool.
 
         Returns:
@@ -160,7 +159,7 @@ class OracleSyncConfig(SyncDatabaseConfig["Connection", "ConnectionPool", "Oracl
         return self.create_pool()
 
     @contextmanager
-    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[Connection, None, None]":
+    def provide_connection(self, *args: "Any", **kwargs: "Any") -> "Generator[OracleSyncConnection, None, None]":
         """Create a connection instance.
 
         Yields: