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

sqlspec/adapters/psycopg/driver.py

@@ -1,4 +1,5 @@
 import logging
+import re
 from contextlib import asynccontextmanager, contextmanager
 from typing import TYPE_CHECKING, Any, Optional, Union, cast, overload
 
@@ -6,12 +7,14 @@ from psycopg import AsyncConnection, Connection
 from psycopg.rows import dict_row
 
 from sqlspec.base import AsyncDriverAdapterProtocol, SyncDriverAdapterProtocol
-from sqlspec.exceptions import SQLParsingError
-from sqlspec.mixins import SQLTranslatorMixin
-from sqlspec.statement import PARAM_REGEX, SQLStatement
+from sqlspec.exceptions import ParameterStyleMismatchError
+from sqlspec.filters import StatementFilter
+from sqlspec.mixins import ResultConverter, SQLTranslatorMixin
+from sqlspec.statement import SQLStatement
+from sqlspec.typing import is_dict
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator, Generator, Sequence
+    from collections.abc import AsyncGenerator, Generator, Mapping, Sequence
 
     from sqlspec.typing import ModelDTOT, StatementParameterType, T
 
@@ -19,130 +22,96 @@ logger = logging.getLogger("sqlspec")
 
 __all__ = ("PsycopgAsyncConnection", "PsycopgAsyncDriver", "PsycopgSyncConnection", "PsycopgSyncDriver")
 
+
+NAMED_PARAMS_PATTERN = re.compile(r"(?<!:):([a-zA-Z0-9_]+)")
+# Pattern matches %(name)s format while trying to avoid matches in string literals and comments
+PSYCOPG_PARAMS_PATTERN = re.compile(r"(?<!'|\"|\w)%\(([a-zA-Z0-9_]+)\)s(?!'|\")")
+
 PsycopgSyncConnection = Connection
 PsycopgAsyncConnection = AsyncConnection
 
 
 class PsycopgDriverBase:
-    dialect: str
+    dialect: str = "postgres"
 
     def _process_sql_params(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
+        *filters: "StatementFilter",
         **kwargs: Any,
     ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
-        """Process SQL and parameters, converting :name -> %(name)s if needed."""
-        stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
-        processed_sql, processed_params = stmt.process()
+        """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.
+
+        Raises:
+            ParameterStyleMismatchError: If the parameter style is mismatched.
+
+        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,)
+        statement = SQLStatement(sql, data_params_for_statement, kwargs=kwargs, dialect=self.dialect)
 
-        if isinstance(processed_params, dict):
-            parameter_dict = processed_params
-            processed_sql_parts: list[str] = []
-            last_end = 0
-            found_params_regex: list[str] = []
+        # Apply all statement filters
+        for filter_obj in combined_filters_list:
+            statement = statement.apply_filter(filter_obj)
 
-            for match in PARAM_REGEX.finditer(processed_sql):
-                if match.group("dquote") or match.group("squote") or match.group("comment"):
-                    continue
+        processed_sql, processed_params, _ = statement.process()
 
-                if match.group("var_name"):
-                    var_name = match.group("var_name")
-                    found_params_regex.append(var_name)
-                    start = match.start("var_name") - 1
-                    end = match.end("var_name")
+        if is_dict(processed_params):
+            named_params = NAMED_PARAMS_PATTERN.findall(processed_sql)
 
-                    if var_name not in parameter_dict:
-                        msg = (
-                            f"Named parameter ':{var_name}' found in SQL but missing from processed parameters. "
-                            f"Processed SQL: {processed_sql}"
-                        )
-                        raise SQLParsingError(msg)
+            if not named_params:
+                if PSYCOPG_PARAMS_PATTERN.search(processed_sql):
+                    return processed_sql, processed_params
 
-                    processed_sql_parts.extend((processed_sql[last_end:start], f"%({var_name})s"))
-                    last_end = end
+                if processed_params:
+                    msg = "psycopg: Dictionary parameters provided, but no named placeholders found in SQL."
+                    raise ParameterStyleMismatchError(msg)
+                return processed_sql, None
 
-            processed_sql_parts.append(processed_sql[last_end:])
-            final_sql = "".join(processed_sql_parts)
+            # Convert named parameters to psycopg's preferred format
+            return NAMED_PARAMS_PATTERN.sub("%s", processed_sql), tuple(processed_params[name] for name in named_params)
 
-            if not found_params_regex and parameter_dict:
-                logger.warning(
-                    "Dict params provided (%s), but no :name placeholders found. SQL: %s",
-                    list(parameter_dict.keys()),
-                    processed_sql,
-                )
-                return processed_sql, parameter_dict
+        # For sequence parameters, ensure they're a tuple
+        if isinstance(processed_params, (list, tuple)):
+            return processed_sql, tuple(processed_params)
 
-            return final_sql, parameter_dict
+        # For scalar parameter or None
+        if processed_params is not None:
+            return processed_sql, (processed_params,)
 
-        return processed_sql, processed_params
+        return processed_sql, None
 
 
 class PsycopgSyncDriver(
     PsycopgDriverBase,
     SQLTranslatorMixin["PsycopgSyncConnection"],
     SyncDriverAdapterProtocol["PsycopgSyncConnection"],
+    ResultConverter,
 ):
     """Psycopg Sync Driver Adapter."""
 
     connection: "PsycopgSyncConnection"
-    dialect: str = "postgres"
 
     def __init__(self, connection: "PsycopgSyncConnection") -> None:
         self.connection = connection
 
-    def _process_sql_params(
-        self,
-        sql: str,
-        parameters: "Optional[StatementParameterType]" = None,
-        /,
-        **kwargs: Any,
-    ) -> "tuple[str, Optional[Union[tuple[Any, ...], list[Any], dict[str, Any]]]]":
-        stmt = SQLStatement(sql=sql, parameters=parameters, dialect=self.dialect, kwargs=kwargs or None)
-        processed_sql, processed_params = stmt.process()
-
-        if isinstance(processed_params, dict):
-            parameter_dict = processed_params
-            processed_sql_parts: list[str] = []
-            last_end = 0
-            found_params_regex: list[str] = []
-
-            for match in PARAM_REGEX.finditer(processed_sql):
-                if match.group("dquote") or match.group("squote") or match.group("comment"):
-                    continue
-
-                if match.group("var_name"):
-                    var_name = match.group("var_name")
-                    found_params_regex.append(var_name)
-                    start = match.start("var_name") - 1
-                    end = match.end("var_name")
-
-                    if var_name not in parameter_dict:
-                        msg = (
-                            f"Named parameter ':{var_name}' found in SQL but missing from processed parameters. "
-                            f"Processed SQL: {processed_sql}"
-                        )
-                        raise SQLParsingError(msg)
-
-                    processed_sql_parts.extend((processed_sql[last_end:start], f"%({var_name})s"))
-                    last_end = end
-
-            processed_sql_parts.append(processed_sql[last_end:])
-            final_sql = "".join(processed_sql_parts)
-
-            if not found_params_regex and parameter_dict:
-                logger.warning(
-                    "Dict params provided (%s), but no :name placeholders found. SQL: %s",
-                    list(parameter_dict.keys()),
-                    processed_sql,
-                )
-                return processed_sql, parameter_dict
-
-            return final_sql, parameter_dict
-
-        return processed_sql, processed_params
-
     @staticmethod
     @contextmanager
     def _with_cursor(connection: "PsycopgSyncConnection") -> "Generator[Any, None, None]":
@@ -158,8 +127,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -169,8 +137,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -179,8 +146,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         schema_type: "Optional[type[ModelDTOT]]" = None,
         connection: "Optional[PsycopgSyncConnection]" = None,
         **kwargs: Any,
@@ -191,24 +157,21 @@ class PsycopgSyncDriver(
             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)
             results = cursor.fetchall()
             if not results:
                 return []
 
-            if schema_type is not None:
-                return [cast("ModelDTOT", schema_type(**row)) for row in results]  # pyright: ignore[reportUnknownArgumentType]
-            return [cast("dict[str,Any]", row) for row in results]  # pyright: ignore[reportUnknownArgumentType]
+            return self.to_schema(cast("Sequence[dict[str, Any]]", results), schema_type=schema_type)
 
     @overload
     def select_one(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -218,8 +181,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -228,8 +190,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -240,22 +201,19 @@ class PsycopgSyncDriver(
             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)
-            row = cursor.fetchone()
-            row = self.check_not_found(row)
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**cast("dict[str,Any]", row)))
-            return cast("dict[str,Any]", row)
+            result = cursor.fetchone()
+            result = self.check_not_found(result)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     @overload
     def select_one_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -265,8 +223,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -275,8 +232,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -284,26 +240,23 @@ class PsycopgSyncDriver(
         """Fetch one row from the database.
 
         Returns:
-            The first row of the query results.
+            The first row of the query results, or None if no 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)
-            row = cursor.fetchone()
-            if row is None:
+            result = cursor.fetchone()
+            if result is None:
                 return None
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**cast("dict[str,Any]", row)))
-            return cast("dict[str,Any]", row)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     @overload
     def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -313,8 +266,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -323,8 +275,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -332,27 +283,26 @@ class PsycopgSyncDriver(
         """Fetch a single value from the database.
 
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value from 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)
-            row = cursor.fetchone()
-            row = self.check_not_found(row)
-            val = next(iter(row.values())) if row else None
-            val = self.check_not_found(val)
-            if schema_type is not None:
-                return schema_type(val)  # type: ignore[call-arg]
-            return val
+            result = cursor.fetchone()
+            result = self.check_not_found(result)
+
+            value = next(iter(result.values()))  # Get the first value from the row
+            if schema_type is None:
+                return value
+            return schema_type(value)  # type: ignore[call-arg]
 
     @overload
     def select_value_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -362,8 +312,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -372,8 +321,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -384,35 +332,33 @@ class PsycopgSyncDriver(
             The first value from the first row of results, or None if no 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)
-            row = cursor.fetchone()
-            if row is None:
-                return None
-            val = next(iter(row.values())) if row else None
-            if val is None:
+            result = cursor.fetchone()
+            if result is None:
                 return None
-            if schema_type is not None:
-                return schema_type(val)  # type: ignore[call-arg]
-            return val
+
+            value = next(iter(result.values()))  # Get the first value from the row
+            if schema_type is None:
+                return value
+            return schema_type(value)  # type: ignore[call-arg]
 
     def insert_update_delete(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         **kwargs: Any,
     ) -> int:
-        """Execute an INSERT, UPDATE, or DELETE query and return the number of affected rows.
+        """Insert, update, or delete data from the database.
 
         Returns:
-            The number of rows affected by the operation.
+            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)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)
             return getattr(cursor, "rowcount", -1)  # pyright: ignore[reportUnknownMemberType]
@@ -422,8 +368,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -433,8 +378,7 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -443,36 +387,28 @@ class PsycopgSyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgSyncConnection]" = 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.
+    ) -> "Union[ModelDTOT, dict[str, Any]]":
+        """Insert, update, or delete data with RETURNING clause.
 
         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)
         with self._with_cursor(connection) as cursor:
             cursor.execute(sql, parameters)
             result = cursor.fetchone()
-
-            if result is None:
-                return None
-
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**result))  # pyright: ignore[reportUnknownArgumentType]
-            return cast("dict[str, Any]", result)  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            result = self.check_not_found(result)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     def execute_script(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
         connection: "Optional[PsycopgSyncConnection]" = None,
         **kwargs: Any,
     ) -> str:
@@ -492,11 +428,11 @@ class PsycopgAsyncDriver(
     PsycopgDriverBase,
     SQLTranslatorMixin["PsycopgAsyncConnection"],
     AsyncDriverAdapterProtocol["PsycopgAsyncConnection"],
+    ResultConverter,
 ):
     """Psycopg Async Driver Adapter."""
 
     connection: "PsycopgAsyncConnection"
-    dialect: str = "postgres"
 
     def __init__(self, connection: "PsycopgAsyncConnection") -> None:
         self.connection = connection
@@ -516,8 +452,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -527,8 +462,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -537,10 +471,9 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
-        connection: "Optional[PsycopgAsyncConnection]" = None,
+        *filters: "StatementFilter",
         schema_type: "Optional[type[ModelDTOT]]" = None,
+        connection: "Optional[PsycopgAsyncConnection]" = None,
         **kwargs: Any,
     ) -> "Sequence[Union[ModelDTOT, dict[str, Any]]]":
         """Fetch data from the database.
@@ -549,25 +482,21 @@ class PsycopgAsyncDriver(
             List of row data as either model instances or dictionaries.
         """
         connection = self._connection(connection)
-        sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
-        results: list[Union[ModelDTOT, dict[str, Any]]] = []
-
+        sql, parameters = self._process_sql_params(sql, parameters, *filters, **kwargs)
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)
             results = await cursor.fetchall()
             if not results:
                 return []
-            if schema_type is not None:
-                return [cast("ModelDTOT", schema_type(**cast("dict[str,Any]", row))) for row in results]  # pyright: ignore[reportUnknownArgumentType]
-            return [cast("dict[str,Any]", row) for row in results]  # pyright: ignore[reportUnknownArgumentType]
+
+            return self.to_schema(cast("Sequence[dict[str, Any]]", results), schema_type=schema_type)
 
     @overload
     async def select_one(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -577,8 +506,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -587,8 +515,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "Optional[type[ModelDTOT]]" = None,
         **kwargs: Any,
@@ -599,23 +526,19 @@ class PsycopgAsyncDriver(
             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)
-            row = await cursor.fetchone()
-            row = self.check_not_found(row)
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**cast("dict[str,Any]", row)))
-            return cast("dict[str,Any]", row)
+            result = await cursor.fetchone()
+            result = self.check_not_found(result)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     @overload
     async def select_one_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -625,8 +548,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -635,8 +557,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         schema_type: "Optional[type[ModelDTOT]]" = None,
         connection: "Optional[PsycopgAsyncConnection]" = None,
         **kwargs: Any,
@@ -644,27 +565,23 @@ class PsycopgAsyncDriver(
         """Fetch one row from the database.
 
         Returns:
-            The first row of the query results.
+            The first row of the query results, or None if no 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)
-            row = await cursor.fetchone()
-            if row is None:
+            result = await cursor.fetchone()
+            if result is None:
                 return None
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**cast("dict[str,Any]", row)))
-            return cast("dict[str,Any]", row)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     @overload
     async def select_value(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -674,8 +591,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "type[T]",
         **kwargs: Any,
@@ -684,8 +600,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -693,27 +608,45 @@ class PsycopgAsyncDriver(
         """Fetch a single value from the database.
 
         Returns:
-            The first value from the first row of results, or None if no results.
+            The first value from 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)
-            row = await cursor.fetchone()
-            row = self.check_not_found(row)
-            val = next(iter(row.values())) if row else None
-            val = self.check_not_found(val)
-            if schema_type is not None:
-                return schema_type(val)  # type: ignore[call-arg]
-            return val
+            result = await cursor.fetchone()
+            result = self.check_not_found(result)
+
+            value = next(iter(result.values()))  # Get the first value from the row
+            if schema_type is None:
+                return value
+            return schema_type(value)  # type: ignore[call-arg]
 
+    @overload
+    async def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
+        connection: "Optional[PsycopgAsyncConnection]" = None,
+        schema_type: None = None,
+        **kwargs: Any,
+    ) -> "Optional[Any]": ...
+    @overload
     async def select_value_or_none(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
+        connection: "Optional[PsycopgAsyncConnection]" = None,
+        schema_type: "type[T]",
+        **kwargs: Any,
+    ) -> "Optional[T]": ...
+    async def select_value_or_none(
+        self,
+        sql: str,
+        parameters: "Optional[StatementParameterType]" = None,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "Optional[type[T]]" = None,
         **kwargs: Any,
@@ -724,52 +657,43 @@ class PsycopgAsyncDriver(
             The first value from the first row of results, or None if no 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)
-            row = await cursor.fetchone()
-            if row is None:
-                return None
-            val = next(iter(row.values())) if row else None
-            if val is None:
+            result = await cursor.fetchone()
+            if result is None:
                 return None
-            if schema_type is not None:
-                return schema_type(val)  # type: ignore[call-arg]
-            return val
+
+            value = next(iter(result.values()))  # Get the first value from the row
+            if schema_type is None:
+                return value
+            return schema_type(value)  # type: ignore[call-arg]
 
     async def insert_update_delete(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         **kwargs: Any,
     ) -> int:
-        """Execute an INSERT, UPDATE, or DELETE query and return the number of affected rows.
+        """Insert, update, or delete data from the database.
 
         Returns:
-            The number of rows affected by the operation.
+            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)
-            try:
-                rowcount = int(cursor.rowcount)
-            except (TypeError, ValueError):
-                rowcount = -1
-            return rowcount
+            return getattr(cursor, "rowcount", -1)  # pyright: ignore[reportUnknownMemberType]
 
     @overload
     async def insert_update_delete_returning(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: None = None,
         **kwargs: Any,
@@ -779,8 +703,7 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = None,
         schema_type: "type[ModelDTOT]",
         **kwargs: Any,
@@ -789,37 +712,28 @@ class PsycopgAsyncDriver(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
+        *filters: "StatementFilter",
         connection: "Optional[PsycopgAsyncConnection]" = 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.
+    ) -> "Union[ModelDTOT, dict[str, Any]]":
+        """Insert, update, or delete data with RETURNING clause.
 
         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)
             result = await cursor.fetchone()
-
-            if result is None:
-                return None
-
-            if schema_type is not None:
-                return cast("ModelDTOT", schema_type(**result))  # pyright: ignore[reportUnknownArgumentType]
-            return cast("dict[str, Any]", result)  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
+            result = self.check_not_found(result)
+            return self.to_schema(cast("dict[str, Any]", result), schema_type=schema_type)
 
     async def execute_script(
         self,
         sql: str,
         parameters: "Optional[StatementParameterType]" = None,
-        /,
-        *,
         connection: "Optional[PsycopgAsyncConnection]" = None,
         **kwargs: Any,
     ) -> str:
@@ -830,7 +744,6 @@ class PsycopgAsyncDriver(
         """
         connection = self._connection(connection)
         sql, parameters = self._process_sql_params(sql, parameters, **kwargs)
-
         async with self._with_cursor(connection) as cursor:
             await cursor.execute(sql, parameters)
             return str(cursor.statusmessage) if cursor.statusmessage is not None else "DONE"