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

sqlspec/adapters/oracledb/driver.py

@@ -1,15 +1,23 @@
+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.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 sqlspec.filters import StatementFilter
     from sqlspec.typing import ModelDTOT
 
 __all__ = ("OracleAsyncConnection", "OracleAsyncDriver", "OracleSyncConnection", "OracleSyncDriver")
@@ -17,16 +25,64 @@ __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.
+        """
+        # Special case: Oracle treats empty dicts as None
+        if isinstance(parameters, dict) and not parameters and not kwargs:
+            return sql, None
+
+        # Create a SQLStatement with appropriate dialect
+        statement = SQLStatement(sql, parameters, kwargs=kwargs, dialect=self.dialect)
+
+        # Apply any filters
+        for filter_obj in filters:
+            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
@@ -47,7 +103,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -58,7 +114,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -68,7 +124,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -78,6 +134,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,7 +143,7 @@ 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]
@@ -95,10 +152,7 @@ class OracleSyncDriver(
             # Get column names
             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(
@@ -106,7 +160,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -117,7 +171,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -127,7 +181,7 @@ class OracleSyncDriver(
         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,10 +210,7 @@ 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(
@@ -166,7 +218,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -177,7 +229,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -187,33 +239,37 @@ class OracleSyncDriver(
         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(
@@ -221,7 +277,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -232,7 +288,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -242,18 +298,26 @@ class OracleSyncDriver(
         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]
@@ -270,7 +334,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -281,7 +345,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -291,23 +355,30 @@ class OracleSyncDriver(
         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
 
@@ -320,21 +391,28 @@ class OracleSyncDriver(
         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(
@@ -342,7 +420,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -353,7 +431,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -363,7 +441,7 @@ class OracleSyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -374,7 +452,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]
@@ -396,14 +474,20 @@ class OracleSyncDriver(
         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).
+            *filters: Statement filters to apply.
+            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)
@@ -432,16 +516,28 @@ class OracleSyncDriver(
         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
@@ -462,7 +558,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -473,7 +569,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -483,7 +579,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -494,7 +590,7 @@ class OracleAsyncDriver(
             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]
@@ -515,7 +611,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -526,7 +622,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -536,7 +632,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -547,7 +643,7 @@ class OracleAsyncDriver(
             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]
@@ -567,7 +663,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -578,7 +674,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -588,7 +684,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -599,7 +695,7 @@ class OracleAsyncDriver(
             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]
@@ -622,7 +718,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -633,7 +729,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -643,23 +739,31 @@ class OracleAsyncDriver(
         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]
             result = await cursor.fetchone()  # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
-            result = self.check_not_found(result)  # pyright: ignore[reportUnknownArgumentType]
+            result = self.check_not_found(result)
 
             if schema_type is None:
                 return result[0]  # pyright: ignore[reportUnknownArgumentType]
@@ -671,7 +775,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -682,7 +786,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -692,23 +796,30 @@ class OracleAsyncDriver(
         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
 
@@ -721,17 +832,24 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = 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)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -743,7 +861,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -754,7 +872,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -764,7 +882,7 @@ class OracleAsyncDriver(
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
         /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[OracleAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -775,7 +893,7 @@ class OracleAsyncDriver(
             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)
 
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)  # pyright: ignore[reportUnknownMemberType]
@@ -797,14 +915,19 @@ class OracleAsyncDriver(
         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)
@@ -838,3 +961,14 @@ class OracleAsyncDriver(
         sql, parameters = self._process_sql_params(sql, parameters, **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