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

sqlspec/adapters/oracledb/driver.py

@@ -1,14 +1,22 @@
+import logging
 from contextlib import asynccontextmanager, contextmanager
 from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
 from oracledb import AsyncConnection, AsyncCursor, Connection, Cursor
 
 from sqlspec.base import AsyncDriverAdapterProtocol, SyncDriverAdapterProtocol
-from sqlspec.mixins import AsyncArrowBulkOperationsMixin, SQLTranslatorMixin, SyncArrowBulkOperationsMixin
+from sqlspec.filters import StatementFilter
+from sqlspec.mixins import (
+    AsyncArrowBulkOperationsMixin,
+    ResultConverter,
+    SQLTranslatorMixin,
+    SyncArrowBulkOperationsMixin,
+)
+from sqlspec.statement import SQLStatement
 from sqlspec.typing import ArrowTable, StatementParameterType, T
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator, Generator, Sequence
+    from collections.abc import AsyncGenerator, Generator, Mapping, Sequence
 
     from sqlspec.typing import ModelDTOT
 
@@ -17,16 +25,70 @@ __all__ = ("OracleAsyncConnection", "OracleAsyncDriver", "OracleSyncConnection",
 OracleSyncConnection = Connection
 OracleAsyncConnection = AsyncConnection
 
+logger = logging.getLogger("sqlspec")
+
+
+class OracleDriverBase:
+    """Base class for Oracle drivers with common functionality."""
+
+    dialect: str = "oracle"
+
+    def _process_sql_params(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
+        **kwargs: Any,
+    ) -> "tuple[str, Optional[Union[tuple[Any, ...], dict[str, Any]]]]":
+        """Process SQL and parameters using SQLStatement with dialect support.
+
+        Args:
+            sql: The SQL statement to process.
+            parameters: The parameters to bind to the statement.
+            *filters: Statement filters to apply.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            A tuple of (sql, parameters) ready for execution.
+        """
+        data_params_for_statement: Optional[Union[Mapping[str, Any], Sequence[Any]]] = None
+        combined_filters_list: list[StatementFilter] = list(filters)
+
+        if parameters is not None:
+            if isinstance(parameters, StatementFilter):
+                combined_filters_list.insert(0, parameters)
+            else:
+                data_params_for_statement = parameters
+        if data_params_for_statement is not None and not isinstance(data_params_for_statement, (list, tuple, dict)):
+            data_params_for_statement = (data_params_for_statement,)
+
+        if isinstance(data_params_for_statement, dict) and not data_params_for_statement and not kwargs:
+            return sql, None
+
+        statement = SQLStatement(sql, data_params_for_statement, kwargs=kwargs, dialect=self.dialect)
+        for filter_obj in combined_filters_list:
+            statement = statement.apply_filter(filter_obj)
+
+        processed_sql, processed_params, _ = statement.process()
+        if processed_params is None:
+            return processed_sql, None
+        if isinstance(processed_params, dict):
+            return processed_sql, processed_params
+        if isinstance(processed_params, (list, tuple)):
+            return processed_sql, tuple(processed_params)
+        return processed_sql, (processed_params,)  # type: ignore[unreachable]
+
 
 class OracleSyncDriver(
+    OracleDriverBase,
     SyncArrowBulkOperationsMixin["OracleSyncConnection"],
     SQLTranslatorMixin["OracleSyncConnection"],
     SyncDriverAdapterProtocol["OracleSyncConnection"],
+    ResultConverter,
 ):
     """Oracle Sync Driver Adapter."""
 
     connection: "OracleSyncConnection"
-    dialect: str = "oracle"
 
     def __init__(self, connection: "OracleSyncConnection") -> None:
         self.connection = connection
@@ -46,8 +108,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -57,8 +118,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -67,8 +127,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -78,6 +137,7 @@ class OracleSyncDriver(
         Args:
             sql: The SQL query string.
             parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
             connection: Optional connection override.
             schema_type: Optional schema class for the result.
             **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
@@ -86,27 +146,23 @@ class OracleSyncDriver(
             List of row data as either model instances or dictionaries.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             results = cursor.fetchall()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
             if not results:
                 return []
-            # Get column names
+            # Get column names from description
             column_names = [col[0] for col in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
 
-            if schema_type:
-                return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore
-
-            return [dict(zip(column_names, row)) for row in results]  # pyright: ignore
+            return self.to_schema([dict(zip(column_names, row)) for row in results], schema_type=schema_type)
 
     @overload
     def select_one(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -116,8 +172,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -126,8 +181,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -137,6 +191,7 @@ class OracleSyncDriver(
         Args:
             sql: The SQL query string.
             parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
             connection: Optional connection override.
             schema_type: Optional schema class for the result.
             **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
@@ -145,7 +200,7 @@ class OracleSyncDriver(
             The first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -155,18 +210,14 @@ class OracleSyncDriver(
             # Get column names
             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))))  # pyright: ignore[reportUnknownArgumentType]
-            # Always return dictionaries
-            return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            return self.to_schema(dict(zip(column_names, result)), schema_type=schema_type)
 
     @overload
     def select_one_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -176,8 +227,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -186,42 +236,44 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
-        """Fetch one row from the database.
+        """Fetch one row from the database or return None if no rows found.
+
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional schema class for the result.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            The first row of the query results.
+            The first row of the query results, or None if no results found.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
             if result is None:
                 return None
 
             # Get column names
             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))))  # pyright: ignore[reportUnknownArgumentType]
-            # Always return dictionaries
-            return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            return self.to_schema(dict(zip(column_names, result)), schema_type=schema_type)
 
     @overload
     def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -231,8 +283,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -241,19 +292,26 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Union[T, Any]":
         """Fetch a single value from the database.
 
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional type to convert the result to.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value of the first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -269,8 +327,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -280,8 +337,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -290,24 +346,30 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
-        """Fetch a single value from the database.
+        """Fetch a single value or None if not found.
+
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional type to convert the result to.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value of the first row of the query results, or None if no results found.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
             if result is None:
                 return None
 
@@ -319,30 +381,35 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         **kwargs: Any,
     ) -> int:
-        """Insert, update, or delete data from the database.
+        """Execute an insert, update, or delete statement.
+
+        Args:
+            sql: The SQL statement to execute.
+            parameters: The parameters for the statement (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            Row count affected by the operation.
+            The number of rows affected by the statement.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
-            return cursor.rowcount  # pyright: ignore[reportUnknownMemberType]
+            return cursor.rowcount  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
 
     @overload
     def insert_update_delete_returning(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -352,8 +419,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -362,8 +428,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -374,7 +439,7 @@ class OracleSyncDriver(
             The first row of results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -395,15 +460,19 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
         connection: "Optional[OracleSyncConnection]" = None,
         **kwargs: Any,
     ) -> str:
-        """Execute a script.
+        """Execute a SQL script.
+
+        Args:
+            sql: The SQL script to execute.
+            parameters: The parameters for the script (dict, tuple, list, or None).
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            Status message for the operation.
+            A success message.
         """
         connection = self._connection(connection)
         sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
@@ -416,8 +485,7 @@ class OracleSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         **kwargs: Any,
     ) -> "ArrowTable":  # pyright: ignore[reportUnknownVariableType]
@@ -428,20 +496,32 @@ class OracleSyncDriver(
         """
 
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
         results = connection.fetch_df_all(sql, parameters)
         return cast("ArrowTable", ArrowTable.from_arrays(arrays=results.column_arrays(), names=results.column_names()))  # pyright: ignore
 
+    def _connection(self, connection: "Optional[OracleSyncConnection]" = None) -> "OracleSyncConnection":
+        """Get the connection to use for the operation.
+
+        Args:
+            connection: Optional connection to use.
+
+        Returns:
+            The connection to use.
+        """
+        return connection or self.connection
+
 
 class OracleAsyncDriver(
+    OracleDriverBase,
     AsyncArrowBulkOperationsMixin["OracleAsyncConnection"],
     SQLTranslatorMixin["OracleAsyncConnection"],
     AsyncDriverAdapterProtocol["OracleAsyncConnection"],
+    ResultConverter,
 ):
     """Oracle Async Driver Adapter."""
 
     connection: "OracleAsyncConnection"
-    dialect: str = "oracle"
 
     def __init__(self, connection: "OracleAsyncConnection") -> None:
         self.connection = connection
@@ -461,8 +541,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -472,8 +551,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -482,40 +560,43 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch data from the database.
 
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional schema class for the result.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
             List of row data as either model instances or dictionaries.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             results = await cursor.fetchall()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
             if not results:
                 return []
-            # Get column names
+            # Get column names from description
             column_names = [col[0] for col in cursor.description or []]  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
 
-            if schema_type:
-                return [cast("ModelDTOT", schema_type(**dict(zip(column_names, row)))) for row in results]  # pyright: ignore
-
-            return [dict(zip(column_names, row)) for row in results]  # pyright: ignore
+            return self.to_schema([dict(zip(column_names, row)) for row in results], schema_type=schema_type)
 
     @overload
     async def select_one(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -525,8 +606,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -535,39 +615,41 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Union[ModelDTOT, dict[str, Any]]":
         """Fetch one row from the database.
 
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional schema class for the result.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
             The first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = await cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
             result = self.check_not_found(result)  # pyright: ignore[reportUnknownArgumentType]
-            # Get column names
             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))))  # pyright: ignore[reportUnknownArgumentType]
-            # Always return dictionaries
-            return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            return self.to_schema(dict(zip(column_names, result)), schema_type=schema_type)
 
     @overload
     async def select_one_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -577,8 +659,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -587,42 +668,41 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[ModelDTOT, dict[str, Any]]]":
-        """Fetch one row from the database.
+        """Fetch one row from the database or return None if no rows found.
+
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional schema class for the result.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            The first row of the query results.
+            The first row of the query results, or None if no results found.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = await cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
             if result is None:
                 return None
-
-            # Get column names
             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))))  # pyright: ignore[reportUnknownArgumentType]
-            # Always return dictionaries
-            return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            return self.to_schema(dict(zip(column_names, result)), schema_type=schema_type)
 
     @overload
     async def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -632,8 +712,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -642,19 +721,26 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Union[T, Any]":
         """Fetch a single value from the database.
 
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional type to convert the result to.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value of the first row of the query results.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -670,8 +756,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -681,8 +766,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -691,24 +775,30 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[T, Any]]":
-        """Fetch a single value from the database.
+        """Fetch a single value or None if not found.
+
+        Args:
+            sql: The SQL query string.
+            parameters: The parameters for the query (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional type to convert the result to.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value of the first row of the query results, or None if no results found.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = await cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
             if result is None:
                 return None
 
@@ -720,30 +810,35 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         **kwargs: Any,
     ) -> int:
         """Insert, update, or delete data from the database.
 
+        Args:
+            sql: The SQL statement to execute.
+            parameters: The parameters for the statement (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
             Row count affected by the operation.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
-            return cursor.rowcount  # pyright: ignore[reportUnknownMemberType]
+            return cursor.rowcount  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
 
     @overload
     async def insert_update_delete_returning(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -753,8 +848,7 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -763,24 +857,30 @@ class OracleAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
     ) -> "Optional[Union[dict[str, Any], ModelDTOT]]":
         """Insert, update, or delete data from the database and return result.
 
+        Args:
+            sql: The SQL statement with RETURNING clause.
+            parameters: The parameters for the statement (dict, tuple, list, or None).
+            *filters: Statement filters to apply.
+            connection: Optional connection override.
+            schema_type: Optional schema class for the result.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
+
         Returns:
-            The first row of results.
+            The returned row data, as either a model instance or dictionary.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             result = await cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-
             if result is None:
                 return None
 
@@ -789,22 +889,25 @@ class OracleAsyncDriver(
 
             if schema_type is not None:
                 return cast("ModelDTOT", schema_type(**dict(zip(column_names, result))))  # pyright: ignore[reportUnknownArgumentType]
-            # Always return dictionaries
             return dict(zip(column_names, result))  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
 
     async def execute_script(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
         connection: "Optional[OracleAsyncConnection]" = None,
         **kwargs: Any,
     ) -> str:
-        """Execute a script.
+        """Execute a SQL script.
+
+        Args:
+            sql: The SQL script to execute.
+            parameters: The parameters for the script (dict, tuple, list, or None).
+            connection: Optional connection override.
+            **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
         Returns:
-            Status message for the operation.
+            A success message.
         """
         connection = self._connection(connection)
         sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
@@ -813,12 +916,11 @@ class OracleAsyncDriver(
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
             return str(cursor.rowcount)  # pyright: ignore[reportUnknownMemberType]
 
-    async def select_arrow(  # pyright: ignore[reportUnknownParameterType]
+    async def select_arrow(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         **kwargs: Any,
     ) -> "ArrowTable":  # pyright: ignore[reportUnknownVariableType]
@@ -827,6 +929,7 @@ class OracleAsyncDriver(
         Args:
             sql: The SQL query string.
             parameters: Parameters for the query.
+            filters: Statement filters to apply.
             connection: Optional connection override.
             **kwargs: Additional keyword arguments to merge with parameters if parameters is a dict.
 
@@ -835,6 +938,17 @@ class OracleAsyncDriver(
         """
 
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
         results = await connection.fetch_df_all(sql, parameters)
         return ArrowTable.from_arrays(arrays=results.column_arrays(), names=results.column_names())  # pyright: ignore
+
+    def _connection(self, connection: "Optional[OracleAsyncConnection]" = None) -> "OracleAsyncConnection":
+        """Get the connection to use for the operation.
+
+        Args:
+            connection: Optional connection to use.
+
+        Returns:
+            The connection to use.
+        """
+        return connection or self.connection