asyncpg-typed 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

asyncpg_typed/__init__.py

@@ -4,9 +4,9 @@ Type-safe queries for asyncpg.
 :see: https://github.com/hunyadi/asyncpg_typed
 """
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 __author__ = "Levente Hunyadi"
-__copyright__ = "Copyright 2025, Levente Hunyadi"
+__copyright__ = "Copyright 2025-2026, Levente Hunyadi"
 __license__ = "MIT"
 __maintainer__ = "Levente Hunyadi"
 __status__ = "Production"
@@ -16,12 +16,14 @@ import sys
 import typing
 from abc import abstractmethod
 from collections.abc import Callable, Iterable, Sequence
+from dataclasses import dataclass
 from datetime import date, datetime, time, timedelta
 from decimal import Decimal
 from functools import reduce
 from io import StringIO
+from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network
 from types import UnionType
-from typing import Any, Protocol, TypeAlias, TypeVar, Union, get_args, get_origin, overload
+from typing import Any, Protocol, TypeAlias, TypeGuard, TypeVar, Union, get_args, get_origin, overload
 from uuid import UUID
 
 import asyncpg
@@ -38,9 +40,32 @@ RequiredJsonType = bool | int | float | str | dict[str, "JsonType"] | list["Json
 
 TargetType: TypeAlias = type[Any] | UnionType
 
+Connection: TypeAlias = asyncpg.Connection | asyncpg.pool.PoolConnectionProxy
+
+
+class CountMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a different number of parameters or columns than declared in Python."
+
+
+class TypeMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a PostgreSQL type incompatible with the declared Python type."
+
+
+class NameMismatchError(TypeError):
+    "Raised when the name of a result-set column differs from what is declared in Python."
+
+
+class EnumMismatchError(TypeError):
+    "Raised when a prepared statement takes or returns a PostgreSQL enum type whose permitted set of values differs from what is declared in Python."
+
+
+class NoneTypeError(TypeError):
+    "Raised when a column marked as required contains a `NULL` value."
+
+
 if sys.version_info >= (3, 11):
 
-    def is_enum_type(typ: object) -> bool:
+    def is_enum_type(typ: Any) -> TypeGuard[type[enum.Enum]]:
         """
         `True` if the specified type is an enumeration type.
         """
@@ -49,7 +74,7 @@ if sys.version_info >= (3, 11):
 
 else:
 
-    def is_enum_type(typ: object) -> bool:
+    def is_enum_type(typ: Any) -> TypeGuard[type[enum.Enum]]:
         """
         `True` if the specified type is an enumeration type.
         """
@@ -91,6 +116,14 @@ def is_json_type(tp: Any) -> bool:
     return tp in [JsonType, RequiredJsonType]
 
 
+def is_inet_type(tp: Any) -> bool:
+    """
+    `True` if the type represents an IP address or network.
+    """
+
+    return tp in [IPv4Address, IPv6Address, IPv4Network, IPv6Network]
+
+
 def make_union_type(tpl: list[Any]) -> UnionType:
     """
     Creates a `UnionType` (a.k.a. `A | B | C`) dynamically at run time.
@@ -119,25 +152,54 @@ def get_required_type(tp: Any) -> Any:
         return type(None)
 
 
-_json_converter: Callable[[str], JsonType]
-if typing.TYPE_CHECKING:
+def _standard_json_decoder() -> Callable[[str], JsonType]:
     import json
 
     _json_decoder = json.JSONDecoder()
-    _json_converter = _json_decoder.decode
-else:
-    try:
-        import orjson
+    return _json_decoder.decode
+
+
+def _json_decoder() -> Callable[[str], JsonType]:
+    if typing.TYPE_CHECKING:
+        return _standard_json_decoder()
+    else:
+        try:
+            import orjson
+
+            return orjson.loads
+        except ModuleNotFoundError:
+            return _standard_json_decoder()
 
-        _json_converter = orjson.loads
-    except ModuleNotFoundError:
-        import json
 
-        _json_decoder = json.JSONDecoder()
-        _json_converter = _json_decoder.decode
+JSON_DECODER = _json_decoder()
 
 
-def get_converter_for(tp: Any) -> Callable[[Any], Any]:
+def _standard_json_encoder() -> Callable[[JsonType], str]:
+    import json
+
+    _json_encoder = json.JSONEncoder(ensure_ascii=False, separators=(",", ":"), allow_nan=False)
+    return _json_encoder.encode
+
+
+def _json_encoder() -> Callable[[JsonType], str]:
+    if typing.TYPE_CHECKING:
+        return _standard_json_encoder()
+    else:
+        try:
+            import orjson
+
+            def _wrap(value: JsonType) -> str:
+                return orjson.dumps(value).decode()
+
+            return _wrap
+        except ModuleNotFoundError:
+            return _standard_json_encoder()
+
+
+JSON_ENCODER = _json_encoder()
+
+
+def get_output_converter_for(tp: Any) -> Callable[[Any], Any]:
     """
     Returns a callable that takes a wire type and returns a target type.
 
@@ -147,101 +209,268 @@ def get_converter_for(tp: Any) -> Callable[[Any], Any]:
 
     if is_json_type(tp):
         # asyncpg returns fields of type `json` and `jsonb` as `str`, which must be de-serialized
-        return _json_converter
+        return JSON_DECODER
     else:
         # target data types that require conversion must have a single-argument `__init__` that takes an object of the source type
         return tp
 
 
+def get_input_converter_for(tp: Any) -> Callable[[Any], Any]:
+    """
+    Returns a callable that takes a source type and returns a wire type.
+
+    A source type is one of the types supported by the library.
+    A wire type is one of the types returned by asyncpg.
+    """
+
+    if is_json_type(tp):
+        # asyncpg expects fields of type `json` and `jsonb` as `str`, which must be serialized
+        return JSON_ENCODER
+    else:
+        # source data types that require conversion must have a single-argument `__init__` that takes an object of the source type
+        return tp
+
+
 # maps PostgreSQL internal type names to compatible Python types
-_name_to_type: dict[str, tuple[Any, ...]] = {
+_NAME_TO_TYPE: dict[str, tuple[Any, ...]] = {
+    # boolean type
     "bool": (bool,),
+    # numeric types
     "int2": (int,),
     "int4": (int,),
     "int8": (int,),
     "float4": (float,),
     "float8": (float,),
     "numeric": (Decimal,),
+    # date and time types
     "date": (date,),
     "time": (time,),
     "timetz": (time,),
     "timestamp": (datetime,),
     "timestamptz": (datetime,),
     "interval": (timedelta,),
+    # character sequence types
     "bpchar": (str,),
     "varchar": (str,),
     "text": (str,),
+    # binary sequence types
     "bytea": (bytes,),
+    # unique identifier type
+    "uuid": (UUID,),
+    # address types
+    "cidr": (IPv4Network, IPv6Network, IPv4Network | IPv6Network),
+    "inet": (IPv4Network, IPv6Network, IPv4Network | IPv6Network, IPv4Address, IPv6Address, IPv4Address | IPv6Address),
+    "macaddr": (str,),
+    "macaddr8": (str,),
+    # JSON type
     "json": (str, RequiredJsonType),
     "jsonb": (str, RequiredJsonType),
-    "uuid": (UUID,),
+    # XML type
     "xml": (str,),
+    # geometric types
+    "point": (asyncpg.Point,),
+    "line": (asyncpg.Line,),
+    "lseg": (asyncpg.LineSegment,),
+    "box": (asyncpg.Box,),
+    "path": (asyncpg.Path,),
+    "polygon": (asyncpg.Polygon,),
+    "circle": (asyncpg.Circle,),
+    # range types
+    "int4range": (asyncpg.Range[int],),
+    "int4multirange": (list[asyncpg.Range[int]],),
+    "int8range": (asyncpg.Range[int],),
+    "int8multirange": (list[asyncpg.Range[int]],),
+    "numrange": (asyncpg.Range[Decimal],),
+    "nummultirange": (list[asyncpg.Range[Decimal]],),
+    "tsrange": (asyncpg.Range[datetime],),
+    "tsmultirange": (list[asyncpg.Range[datetime]],),
+    "tstzrange": (asyncpg.Range[datetime],),
+    "tstzmultirange": (list[asyncpg.Range[datetime]],),
+    "daterange": (asyncpg.Range[date],),
+    "datemultirange": (list[asyncpg.Range[date]],),
 }
 
 
-def check_data_type(schema: str, name: str, data_type: TargetType) -> bool:
+def type_to_str(tp: Any) -> str:
+    "Emits a friendly name for a type."
+
+    if isinstance(tp, type):
+        return tp.__name__
+    else:
+        return str(tp)
+
+
+class _TypeVerifier:
     """
     Verifies if the Python target type can represent the PostgreSQL source type.
     """
 
-    if schema == "pg_catalog":
-        if is_enum_type(data_type):
-            return name in ["bpchar", "varchar", "text"]
+    _connection: Connection
 
-        expected_types = _name_to_type.get(name)
-        return expected_types is not None and data_type in expected_types
-    else:
-        if is_standard_type(data_type):
-            return False
+    def __init__(self, connection: Connection) -> None:
+        self._connection = connection
+
+    async def _check_enum_type(self, pg_name: str, pg_type: asyncpg.Type, data_type: type[enum.Enum]) -> None:
+        """
+        Verifies if a Python enumeration type matches a PostgreSQL enumeration type.
+        """
+
+        for e in data_type:
+            if not isinstance(e.value, str):
+                raise TypeMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` with `str` values; got: `{type_to_str(type(e.value))}` for enum field `{e.name}`")
+
+        py_values = set(e.value for e in data_type)
 
-        # user-defined type registered with `conn.set_type_codec()`
-        return True
+        rows = await self._connection.fetch("SELECT enumlabel FROM pg_enum WHERE enumtypid = $1 ORDER BY enumsortorder;", pg_type.oid)
+        db_values = set(row[0] for row in rows)
 
+        db_extra = db_values - py_values
+        if db_extra:
+            raise EnumMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` to match values of PostgreSQL enum type `{pg_type.name}` for {pg_name}; missing value(s): {', '.join(f'`{val}`' for val in db_extra)})")
 
-class _SQLPlaceholder:
+        py_extra = py_values - db_values
+        if py_extra:
+            raise EnumMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` to match values of PostgreSQL enum type `{pg_type.name}` for {pg_name}; got extra value(s): {', '.join(f'`{val}`' for val in py_extra)})")
+
+    async def check_data_type(self, pg_name: str, pg_type: asyncpg.Type, data_type: TargetType) -> None:
+        """
+        Verifies if the Python target type can represent the PostgreSQL source type.
+        """
+
+        if pg_type.schema == "pg_catalog":  # well-known PostgreSQL types
+            if is_enum_type(data_type):
+                if pg_type.name not in ["bpchar", "varchar", "text"]:
+                    raise TypeMismatchError(f"expected: Python enum type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` instead of `char`, `varchar` or `text`")
+            elif pg_type.kind == "array" and get_origin(data_type) is list:
+                if not pg_type.name.endswith("[]"):
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` instead of array")
+
+                expected_types = _NAME_TO_TYPE.get(pg_type.name[:-2])
+                if expected_types is None:
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: unrecognized PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+                elif get_args(data_type)[0] not in expected_types:
+                    if len(expected_types) == 1:
+                        target = f"the Python type `{type_to_str(expected_types[0])}`"
+                    else:
+                        target = f"one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
+                    raise TypeMismatchError(f"expected: Python list type `{type_to_str(data_type)}` for {pg_name}; got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` whose elements convert to {target}")
+            else:
+                expected_types = _NAME_TO_TYPE.get(pg_type.name)
+                if expected_types is None:
+                    raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: unrecognized PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+                elif data_type not in expected_types:
+                    if len(expected_types) == 1:
+                        target = f"the Python type `{type_to_str(expected_types[0])}`"
+                    else:
+                        target = f"one of the Python types {', '.join(f'`{type_to_str(tp)}`' for tp in expected_types)}"
+                    raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: incompatible PostgreSQL type `{pg_type.kind}` of `{pg_type.name}` which converts to {target}")
+        elif pg_type.kind == "composite":  # PostgreSQL composite types
+            # user-defined composite types registered with `conn.set_type_codec()` typically using `format="tuple"`
+            pass
+        else:  # custom PostgreSQL types
+            if is_enum_type(data_type):
+                await self._check_enum_type(pg_name, pg_type, data_type)
+            elif is_standard_type(data_type):
+                raise TypeMismatchError(f"expected: Python type `{type_to_str(data_type)}` for {pg_name}; got: PostgreSQL type `{pg_type.kind}` of `{pg_type.name}`")
+            else:
+                # user-defined types registered with `conn.set_type_codec()`
+                pass
+
+
+@dataclass(frozen=True)
+class _Placeholder:
     ordinal: int
     data_type: TargetType
 
-    def __init__(self, ordinal: int, data_type: TargetType) -> None:
-        self.ordinal = ordinal
-        self.data_type = data_type
-
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.ordinal}, {self.data_type!r})"
 
 
+class _ResultsetWrapper:
+    "Wraps result-set rows into a tuple or named tuple."
+
+    init: Callable[..., tuple[Any, ...]] | None
+    iterable: Callable[[Iterable[Any]], tuple[Any, ...]]
+
+    def __init__(self, init: Callable[..., tuple[Any, ...]] | None, iterable: Callable[[Iterable[Any]], tuple[Any, ...]]) -> None:
+        """
+        Initializes a result-set wrapper.
+
+        :param init: Initializer function that takes as many arguments as columns in the result-set.
+        :param iterable: Initializer function that takes an iterable over columns of a result-set row.
+        """
+
+        self.init = init
+        self.iterable = iterable
+
+
 class _SQLObject:
     """
     Associates input and output type information with a SQL statement.
     """
 
-    parameter_data_types: tuple[_SQLPlaceholder, ...]
-    resultset_data_types: tuple[TargetType, ...]
-    required: int
-    cast: int
-    converters: tuple[Callable[[Any], Any], ...]
+    _parameter_data_types: tuple[_Placeholder, ...]
+    _resultset_data_types: tuple[TargetType, ...]
+    _resultset_column_names: tuple[str, ...] | None
+    _resultset_wrapper: _ResultsetWrapper
+    _parameter_cast: int
+    _parameter_converters: tuple[Callable[[Any], Any], ...]
+    _required: int
+    _resultset_cast: int
+    _resultset_converters: tuple[Callable[[Any], Any], ...]
+
+    @property
+    def parameter_data_types(self) -> tuple[_Placeholder, ...]:
+        "Expected inbound parameter data types."
+
+        return self._parameter_data_types
+
+    @property
+    def resultset_data_types(self) -> tuple[TargetType, ...]:
+        "Expected column data types in the result-set."
+
+        return self._resultset_data_types
+
+    @property
+    def resultset_column_names(self) -> tuple[str, ...] | None:
+        "Expected column names in the result-set."
+
+        return self._resultset_column_names
 
     def __init__(
         self,
-        input_data_types: tuple[TargetType, ...],
-        output_data_types: tuple[TargetType, ...],
+        *,
+        args: tuple[TargetType, ...],
+        resultset: tuple[TargetType, ...],
+        names: tuple[str, ...] | None,
+        wrapper: _ResultsetWrapper,
     ) -> None:
-        self.parameter_data_types = tuple(_SQLPlaceholder(ordinal, get_required_type(arg)) for ordinal, arg in enumerate(input_data_types, start=1))
-        self.resultset_data_types = tuple(get_required_type(data_type) for data_type in output_data_types)
+        self._parameter_data_types = tuple(_Placeholder(ordinal, get_required_type(arg)) for ordinal, arg in enumerate(args, start=1))
+        self._resultset_data_types = tuple(get_required_type(data_type) for data_type in resultset)
+        self._resultset_column_names = names
+        self._resultset_wrapper = wrapper
+
+        # create a bit-field of types that require cast or serialization (1: apply conversion; 0: forward value as-is)
+        parameter_cast = 0
+        for index, placeholder in enumerate(self._parameter_data_types):
+            parameter_cast |= is_json_type(placeholder.data_type) << index
+        self._parameter_cast = parameter_cast
+
+        self._parameter_converters = tuple(get_input_converter_for(placeholder.data_type) for placeholder in self._parameter_data_types)
 
         # create a bit-field of required types (1: required; 0: optional)
         required = 0
-        for index, data_type in enumerate(output_data_types):
+        for index, data_type in enumerate(resultset):
             required |= (not is_optional_type(data_type)) << index
-        self.required = required
+        self._required = required
 
-        # create a bit-field of types that require cast or serialization (1: apply conversion; 0: forward value as-is)
-        cast = 0
-        for index, data_type in enumerate(self.resultset_data_types):
-            cast |= (is_enum_type(data_type) or is_json_type(data_type)) << index
-        self.cast = cast
+        # create a bit-field of types that require cast or de-serialization (1: apply conversion; 0: forward value as-is)
+        resultset_cast = 0
+        for index, data_type in enumerate(self._resultset_data_types):
+            resultset_cast |= (is_enum_type(data_type) or is_json_type(data_type) or is_inet_type(data_type)) << index
+        self._resultset_cast = resultset_cast
 
-        self.converters = tuple(get_converter_for(data_type) for data_type in self.resultset_data_types)
+        self._resultset_converters = tuple(get_output_converter_for(data_type) for data_type in self._resultset_data_types)
 
     def _raise_required_is_none(self, row: tuple[Any, ...], row_index: int | None = None) -> None:
         """
@@ -249,12 +478,12 @@ class _SQLObject:
         """
 
         for col_index in range(len(row)):
-            if (self.required >> col_index & 1) and row[col_index] is None:
+            if (self._required >> col_index & 1) and row[col_index] is None:
                 if row_index is not None:
                     row_col_spec = f"row #{row_index} and column #{col_index}"
                 else:
                     row_col_spec = f"column #{col_index}"
-                raise TypeError(f"expected: {self.resultset_data_types[col_index]} in {row_col_spec}; got: NULL")
+                raise NoneTypeError(f"expected: {self._resultset_data_types[col_index]} in {row_col_spec}; got: NULL")
 
     def check_rows(self, rows: list[tuple[Any, ...]]) -> None:
         """
@@ -264,7 +493,7 @@ class _SQLObject:
         if not rows:
             return
 
-        required = self.required
+        required = self._required
         if not required:
             return
 
@@ -317,7 +546,7 @@ class _SQLObject:
         Verifies if declared types match actual value types in a single row.
         """
 
-        required = self.required
+        required = self._required
         if not required:
             return
 
@@ -356,13 +585,187 @@ class _SQLObject:
             case _:
                 self._raise_required_is_none(row)
 
+    def check_column(self, column: list[Any]) -> None:
+        """
+        Verifies if the declared type matches the actual value type of a single-column resultset.
+        """
+
+        if self._required:
+            for i, value in enumerate(column):
+                if value is None:
+                    raise NoneTypeError(f"expected: {self._resultset_data_types[0]} in row #{i}; got: NULL")
+
     def check_value(self, value: Any) -> None:
         """
         Verifies if the declared type matches the actual value type.
         """
 
-        if self.required and value is None:
-            raise TypeError(f"expected: {self.resultset_data_types[0]}; got: NULL")
+        if self._required and value is None:
+            raise NoneTypeError(f"expected: {self._resultset_data_types[0]}; got: NULL")
+
+    def convert_arg_lists(self, arg_lists: Iterable[Sequence[Any]]) -> Iterable[Sequence[Any]]:
+        """
+        Converts a list of Python query argument tuples to a list of PostgreSQL parameter tuples.
+        """
+
+        cast = self._parameter_cast
+        if cast:
+            converters = self._parameter_converters
+            yield from (tuple((converters[i](value) if (value := arg[i]) is not None and cast >> i & 1 else value) for i in range(len(arg))) for arg in arg_lists)
+        else:
+            yield from arg_lists
+
+    def convert_arg_list(self, arg_list: Sequence[Any]) -> Sequence[Any]:
+        """
+        Converts Python query arguments to PostgreSQL parameters.
+        """
+
+        cast = self._parameter_cast
+        if cast:
+            converters = self._parameter_converters
+            return tuple((converters[i](value) if (value := arg_list[i]) is not None and cast >> i & 1 else value) for i in range(len(arg_list)))
+        else:
+            return tuple(value for value in arg_list)
+
+    def convert_rows(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
+        """
+        Converts columns in the PostgreSQL result-set to their corresponding Python target types.
+
+        :param rows: List of rows returned by PostgreSQL.
+        :returns: List of tuples with each tuple element having the configured Python target type.
+        """
+
+        if not rows:
+            return []
+
+        init_wrapper = self._resultset_wrapper.init
+        iterable_wrapper = self._resultset_wrapper.iterable
+        cast = self._resultset_cast
+        if not cast:
+            return [iterable_wrapper(row.values()) for row in rows]
+
+        columns = len(rows[0])
+        match columns:
+            case 1:
+                converter = self._resultset_converters[0]
+                if init_wrapper is not None:
+                    return [init_wrapper(converter(value) if (value := row[0]) is not None else value) for row in rows]
+                else:
+                    return [(converter(value) if (value := row[0]) is not None else value,) for row in rows]
+            case 2:
+                conv_a, conv_b = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                        )
+                        for row in rows
+                    ]
+            case 3:
+                conv_a, conv_b, conv_c = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                cast_c = cast >> 2 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                        )
+                        for row in rows
+                    ]
+            case 4:
+                conv_a, conv_b, conv_c, conv_d = self._resultset_converters
+                cast_a = cast >> 0 & 1
+                cast_b = cast >> 1 & 1
+                cast_c = cast >> 2 & 1
+                cast_d = cast >> 3 & 1
+                if init_wrapper is not None:
+                    return [
+                        init_wrapper(
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                            conv_d(value) if (value := row[3]) is not None and cast_d else value,
+                        )
+                        for row in rows
+                    ]
+                else:
+                    return [
+                        (
+                            conv_a(value) if (value := row[0]) is not None and cast_a else value,
+                            conv_b(value) if (value := row[1]) is not None and cast_b else value,
+                            conv_c(value) if (value := row[2]) is not None and cast_c else value,
+                            conv_d(value) if (value := row[3]) is not None and cast_d else value,
+                        )
+                        for row in rows
+                    ]
+            case _:
+                converters = self._resultset_converters
+                return [iterable_wrapper((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(columns)) for row in rows]
+
+    def convert_row(self, row: asyncpg.Record) -> tuple[Any, ...]:
+        """
+        Converts columns in the PostgreSQL result-set to their corresponding Python target types.
+
+        :param row: A single row returned by PostgreSQL.
+        :returns: A tuple with each tuple element having the configured Python target type.
+        """
+
+        wrapper = self._resultset_wrapper.iterable
+        cast = self._resultset_cast
+        if cast:
+            converters = self._resultset_converters
+            columns = len(row)
+            return wrapper((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(columns))
+        else:
+            return wrapper(row.values())
+
+    def convert_column(self, rows: list[asyncpg.Record]) -> list[Any]:
+        """
+        Converts a single column in the PostgreSQL result-set to its corresponding Python target type.
+
+        :param rows: List of rows returned by PostgreSQL.
+        :returns: List of values having the configured Python target type.
+        """
+
+        cast = self._resultset_cast
+        if cast:
+            converter = self._resultset_converters[0]
+            return [(converter(value) if (value := row[0]) is not None else value) for row in rows]
+        else:
+            return [row[0] for row in rows]
+
+    def convert_value(self, value: Any) -> Any:
+        """
+        Converts a single PostgreSQL value to its corresponding Python target type.
+
+        :param value: A single value returned by PostgreSQL.
+        :returns: A converted value having the configured Python target type.
+        """
+
+        return self._resultset_converters[0](value) if value is not None and self._resultset_cast else value
 
     @abstractmethod
     def query(self) -> str:
@@ -388,8 +791,8 @@ if sys.version_info >= (3, 14):
         A SQL query specified with the Python t-string syntax.
         """
 
-        strings: tuple[str, ...]
-        placeholders: tuple[_SQLPlaceholder, ...]
+        _strings: tuple[str, ...]
+        _placeholders: tuple[_Placeholder, ...]
 
         def __init__(
             self,
@@ -397,8 +800,10 @@ if sys.version_info >= (3, 14):
             *,
             args: tuple[TargetType, ...],
             resultset: tuple[TargetType, ...],
+            names: tuple[str, ...] | None,
+            wrapper: _ResultsetWrapper,
         ) -> None:
-            super().__init__(args, resultset)
+            super().__init__(args=args, resultset=resultset, names=names, wrapper=wrapper)
 
             for ip in template.interpolations:
                 if ip.conversion is not None:
@@ -408,26 +813,26 @@ if sys.version_info >= (3, 14):
                 if not isinstance(ip.value, int):
                     raise TypeError(f"interpolation `{ip.expression}` expected to evaluate to an integer")
 
-            self.strings = template.strings
+            self._strings = template.strings
 
             if len(self.parameter_data_types) > 0:
 
-                def _to_placeholder(ip: Interpolation) -> _SQLPlaceholder:
+                def _to_placeholder(ip: Interpolation) -> _Placeholder:
                     ordinal = int(ip.value)
                     if not (0 < ordinal <= len(self.parameter_data_types)):
                         raise IndexError(f"interpolation `{ip.expression}` is an ordinal out of range; expected: 0 < value <= {len(self.parameter_data_types)}")
                     return self.parameter_data_types[int(ip.value) - 1]
 
-                self.placeholders = tuple(_to_placeholder(ip) for ip in template.interpolations)
+                self._placeholders = tuple(_to_placeholder(ip) for ip in template.interpolations)
             else:
-                self.placeholders = ()
+                self._placeholders = ()
 
         def query(self) -> str:
             buf = StringIO()
-            for s, p in zip(self.strings[:-1], self.placeholders, strict=True):
+            for s, p in zip(self._strings[:-1], self._placeholders, strict=True):
                 buf.write(s)
                 buf.write(f"${p.ordinal}")
-            buf.write(self.strings[-1])
+            buf.write(self._strings[-1])
             return buf.getvalue()
 
 else:
@@ -439,7 +844,7 @@ class _SQLString(_SQLObject):
     A SQL query specified as a plain string (e.g. f-string).
     """
 
-    sql: str
+    _sql: str
 
     def __init__(
         self,
@@ -447,12 +852,14 @@ class _SQLString(_SQLObject):
         *,
         args: tuple[TargetType, ...],
         resultset: tuple[TargetType, ...],
+        names: tuple[str, ...] | None,
+        wrapper: _ResultsetWrapper,
     ) -> None:
-        super().__init__(args, resultset)
-        self.sql = sql
+        super().__init__(args=args, resultset=resultset, names=names, wrapper=wrapper)
+        self._sql = sql
 
     def query(self) -> str:
-        return self.sql
+        return self._sql
 
 
 class _SQL(Protocol):
@@ -461,80 +868,90 @@ class _SQL(Protocol):
     """
 
 
-Connection: TypeAlias = asyncpg.Connection | asyncpg.pool.PoolConnectionProxy
-
-
 class _SQLImpl(_SQL):
     """
     Forwards input data to an `asyncpg.PreparedStatement`, and validates output data (if necessary).
     """
 
-    sql: _SQLObject
+    _sql: _SQLObject
 
     def __init__(self, sql: _SQLObject) -> None:
-        self.sql = sql
+        self._sql = sql
 
     def __str__(self) -> str:
-        return str(self.sql)
+        return str(self._sql)
 
     def __repr__(self) -> str:
-        return repr(self.sql)
+        return repr(self._sql)
 
     async def _prepare(self, connection: Connection) -> PreparedStatement:
-        stmt = await connection.prepare(self.sql.query())
-
-        for attr, data_type in zip(stmt.get_attributes(), self.sql.resultset_data_types, strict=True):
-            if not check_data_type(attr.type.schema, attr.type.name, data_type):
-                raise TypeError(f"expected: {data_type} in column `{attr.name}`; got: `{attr.type.kind}` of `{attr.type.name}`")
+        stmt = await connection.prepare(self._sql.query())
+
+        verifier = _TypeVerifier(connection)
+
+        input_count = len(self._sql.parameter_data_types)
+        parameter_count = len(stmt.get_parameters())
+        if parameter_count != input_count:
+            raise CountMismatchError(f"expected: PostgreSQL query to take {input_count} parameter(s); got: {parameter_count}")
+        for param, placeholder in zip(stmt.get_parameters(), self._sql.parameter_data_types, strict=True):
+            await verifier.check_data_type(f"parameter ${placeholder.ordinal}", param, placeholder.data_type)
+
+        output_count = len(self._sql.resultset_data_types)
+        column_count = len(stmt.get_attributes())
+        if column_count != output_count:
+            raise CountMismatchError(f"expected: PostgreSQL query to return {output_count} column(s) in result-set; got: {column_count}")
+        if self._sql.resultset_column_names is not None:
+            for index, attr, name in zip(range(output_count), stmt.get_attributes(), self._sql.resultset_column_names, strict=True):
+                if attr.name != name:
+                    raise NameMismatchError(f"expected: Python field name `{name}` to match PostgreSQL result-set column name `{attr.name}` for index #{index}")
+        for attr, data_type in zip(stmt.get_attributes(), self._sql.resultset_data_types, strict=True):
+            await verifier.check_data_type(f"column `{attr.name}`", attr.type, data_type)
 
         return stmt
 
     async def execute(self, connection: asyncpg.Connection, *args: Any) -> None:
-        await connection.execute(self.sql.query(), *args)
+        await connection.execute(self._sql.query(), *self._sql.convert_arg_list(args))
 
     async def executemany(self, connection: asyncpg.Connection, args: Iterable[Sequence[Any]]) -> None:
         stmt = await self._prepare(connection)
-        await stmt.executemany(args)
+        await stmt.executemany(self._sql.convert_arg_lists(args))
 
     def _cast_fetch(self, rows: list[asyncpg.Record]) -> list[tuple[Any, ...]]:
-        cast = self.sql.cast
-        if cast:
-            converters = self.sql.converters
-            resultset = [tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row))) for row in rows]
-        else:
-            resultset = [tuple(value for value in row) for row in rows]
-        self.sql.check_rows(resultset)
+        resultset = self._sql.convert_rows(rows)
+        self._sql.check_rows(resultset)
         return resultset
 
     async def fetch(self, connection: asyncpg.Connection, *args: Any) -> list[tuple[Any, ...]]:
         stmt = await self._prepare(connection)
-        rows = await stmt.fetch(*args)
+        rows = await stmt.fetch(*self._sql.convert_arg_list(args))
         return self._cast_fetch(rows)
 
     async def fetchmany(self, connection: asyncpg.Connection, args: Iterable[Sequence[Any]]) -> list[tuple[Any, ...]]:
         stmt = await self._prepare(connection)
-        rows = await stmt.fetchmany(args)
+        rows = await stmt.fetchmany(self._sql.convert_arg_lists(args))
         return self._cast_fetch(rows)
 
     async def fetchrow(self, connection: asyncpg.Connection, *args: Any) -> tuple[Any, ...] | None:
         stmt = await self._prepare(connection)
-        row = await stmt.fetchrow(*args)
+        row = await stmt.fetchrow(*self._sql.convert_arg_list(args))
         if row is None:
             return None
-        cast = self.sql.cast
-        if cast:
-            converters = self.sql.converters
-            resultset = tuple((converters[i](value) if (value := row[i]) is not None and cast >> i & 1 else value) for i in range(len(row)))
-        else:
-            resultset = tuple(value for value in row)
-        self.sql.check_row(resultset)
+        resultset = self._sql.convert_row(row)
+        self._sql.check_row(resultset)
         return resultset
 
+    async def fetchcol(self, connection: asyncpg.Connection, *args: Any) -> list[Any]:
+        stmt = await self._prepare(connection)
+        rows = await stmt.fetch(*self._sql.convert_arg_list(args))
+        column = self._sql.convert_column(rows)
+        self._sql.check_column(column)
+        return column
+
     async def fetchval(self, connection: asyncpg.Connection, *args: Any) -> Any:
         stmt = await self._prepare(connection)
-        value = await stmt.fetchval(*args)
-        result = self.sql.converters[0](value) if value is not None and self.sql.cast else value
-        self.sql.check_value(result)
+        value = await stmt.fetchval(*self._sql.convert_arg_list(args))
+        result = self._sql.convert_value(value)
+        self._sql.check_value(result)
         return result
 
 
@@ -547,9 +964,7 @@ R2 = TypeVar("R2")
 RX = TypeVarTuple("RX")
 
 
-### START OF AUTO-GENERATED BLOCK ###
-
-
+### START OF AUTO-GENERATED BLOCK FOR Protocol ###
 class SQL_P0(Protocol):
     @abstractmethod
     async def execute(self, connection: Connection) -> None: ...
@@ -561,6 +976,8 @@ class SQL_R1_P0(SQL_P0, Protocol[R1]):
     @abstractmethod
     async def fetchrow(self, connection: Connection) -> tuple[R1] | None: ...
     @abstractmethod
+    async def fetchcol(self, connection: Connection) -> list[R1]: ...
+    @abstractmethod
     async def fetchval(self, connection: Connection) -> R1: ...
 
 
@@ -586,6 +1003,8 @@ class SQL_R1_PX(SQL_PX[Unpack[PX]], Protocol[R1, Unpack[PX]]):
     @abstractmethod
     async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> tuple[R1] | None: ...
     @abstractmethod
+    async def fetchcol(self, connection: Connection, *args: Unpack[PX]) -> list[R1]: ...
+    @abstractmethod
     async def fetchval(self, connection: Connection, *args: Unpack[PX]) -> R1: ...
 
 
@@ -598,84 +1017,153 @@ class SQL_RX_PX(SQL_PX[Unpack[PX]], Protocol[RT, Unpack[PX]]):
     async def fetchrow(self, connection: Connection, *args: Unpack[PX]) -> RT | None: ...
 
 
-@overload
-def sql(stmt: SQLExpression) -> SQL_P0: ...
-@overload
-def sql(stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1]]) -> SQL_R1_P0[R1]: ...
-@overload
-def sql(stmt: SQLExpression, *, resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_P0[tuple[R1, R2, Unpack[RX]]]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, arg: type[P1], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1]]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
-@overload
-def sql(stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[tuple[R1, R2, Unpack[RX]]]) -> SQL_RX_PX[tuple[R1, R2, Unpack[RX]], P1, Unpack[PX]]: ...
-
-
-### END OF AUTO-GENERATED BLOCK ###
-
-
-def sql(
-    stmt: SQLExpression,
-    *,
-    args: type[Any] | None = None,
-    resultset: type[Any] | None = None,
-    arg: type[Any] | None = None,
-    result: type[Any] | None = None,
-) -> _SQL:
-    """
-    Creates a SQL statement with associated type information.
+### END OF AUTO-GENERATED BLOCK FOR Protocol ###
+
+RS = TypeVar("RS", bound=tuple[Any, ...])
 
-    :param stmt: SQL statement as a literal string or template.
-    :param args: Type signature for multiple input parameters (e.g. `tuple[bool, int, str]`).
-    :param resultset: Type signature for multiple resultset columns (e.g. `tuple[datetime, Decimal, str]`).
-    :param arg: Type signature for a single input parameter (e.g. `int`).
-    :param result: Type signature for a single result column (e.g. `UUID`).
+
+class SQLFactory:
+    """
+    Creates type-safe SQL queries.
     """
 
+    ### START OF AUTO-GENERATED BLOCK FOR sql ###
+    @overload
+    def sql(self, stmt: SQLExpression) -> SQL_P0: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, resultset: type[RS]) -> SQL_RX_P0[RS]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1]) -> SQL_PX[P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, arg: type[P1], resultset: type[RS]) -> SQL_RX_PX[RS, P1]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def sql(self, stmt: SQLExpression, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[RS]) -> SQL_RX_PX[RS, P1, Unpack[PX]]: ...
+
+    ### END OF AUTO-GENERATED BLOCK FOR sql ###
+
+    def sql(self, stmt: SQLExpression, *, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None) -> _SQL:
+        """
+        Creates a SQL statement with associated type information.
+
+        :param stmt: SQL statement as a literal string or template.
+        :param args: Type signature for multiple input parameters (e.g. `tuple[bool, int, str]`).
+        :param resultset: Type signature for multiple resultset columns (e.g. `tuple[datetime, Decimal, str]`).
+        :param arg: Type signature for a single input parameter (e.g. `int`).
+        :param result: Type signature for a single result column (e.g. `UUID`).
+        """
+
+        input_data_types, output_data_types, names, wrapper = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+
+        obj: _SQLObject
+        if sys.version_info >= (3, 14):
+            match stmt:
+                case Template():
+                    obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
+                case str():
+                    obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
+        else:
+            obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
+
+        return _SQLImpl(obj)
+
+    ### START OF AUTO-GENERATED BLOCK FOR unsafe_sql ###
+    @overload
+    def unsafe_sql(self, stmt: str) -> SQL_P0: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, result: type[R1]) -> SQL_R1_P0[R1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, resultset: type[RS]) -> SQL_RX_P0[RS]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1]) -> SQL_PX[P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], result: type[R1]) -> SQL_R1_PX[R1, P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, arg: type[P1], resultset: type[RS]) -> SQL_RX_PX[RS, P1]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]]) -> SQL_PX[P1, Unpack[PX]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], result: type[R1]) -> SQL_R1_PX[R1, P1, Unpack[PX]]: ...
+    @overload
+    def unsafe_sql(self, stmt: str, *, args: type[tuple[P1, Unpack[PX]]], resultset: type[RS]) -> SQL_RX_PX[RS, P1, Unpack[PX]]: ...
+
+    ### END OF AUTO-GENERATED BLOCK FOR unsafe_sql ###
+
+    def unsafe_sql(self, stmt: str, *, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None) -> _SQL:
+        """
+        Creates a SQL statement with associated type information from a string.
+
+        This offers an alternative to the function :func:`sql` when we want to prevent the type checker from enforcing
+        a string literal, e.g. when we want to embed a variable as the table name to dynamically create a SQL statement.
+
+        :param stmt: SQL statement as a string (or f-string).
+        :param args: Type signature for multiple input parameters (e.g. `tuple[bool, int, str]`).
+        :param resultset: Type signature for multiple resultset columns (e.g. `tuple[datetime, Decimal, str]`).
+        :param arg: Type signature for a single input parameter (e.g. `int`).
+        :param result: Type signature for a single result column (e.g. `UUID`).
+        """
+
+        input_data_types, output_data_types, names, wrapper = _sql_args_resultset(args=args, resultset=resultset, arg=arg, result=result)
+        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types, names=names, wrapper=wrapper)
+        return _SQLImpl(obj)
+
+
+def _sql_args_resultset(
+    *, args: type[Any] | None = None, resultset: type[Any] | None = None, arg: type[Any] | None = None, result: type[Any] | None = None
+) -> tuple[tuple[Any, ...], tuple[Any, ...], tuple[str, ...] | None, _ResultsetWrapper]:
+    "Parses an argument/resultset signature into input/output types."
+
     if args is not None and arg is not None:
         raise TypeError("expected: either `args` or `arg`; got: both")
     if resultset is not None and result is not None:
         raise TypeError("expected: either `resultset` or `result`; got: both")
 
     if args is not None:
-        if get_origin(args) is not tuple:
-            raise TypeError(f"expected: `type[tuple[T, ...]]` for `args`; got: {type(args)}")
-        input_data_types = get_args(args)
+        if hasattr(args, "_asdict") and hasattr(args, "_fields"):
+            # named tuple
+            input_data_types = tuple(tp for tp in args.__annotations__.values())
+        else:
+            # regular tuple
+            if get_origin(args) is not tuple:
+                raise TypeError(f"expected: `type[tuple[T, ...]]` for `args`; got: {args}")
+            input_data_types = get_args(args)
     elif arg is not None:
         input_data_types = (arg,)
     else:
         input_data_types = ()
 
     if resultset is not None:
-        if get_origin(resultset) is not tuple:
-            raise TypeError(f"expected: `type[tuple[T, ...]]` for `resultset`; got: {type(resultset)}")
-        output_data_types = get_args(resultset)
-    elif result is not None:
-        output_data_types = (result,)
+        if hasattr(resultset, "_asdict") and hasattr(resultset, "_fields") and hasattr(resultset, "_make"):
+            # named tuple
+            output_data_types = tuple(tp for tp in resultset.__annotations__.values())
+            names = tuple(f for f in resultset._fields)
+            wrapper = _ResultsetWrapper(resultset, resultset._make)
+        else:
+            # regular tuple
+            if get_origin(resultset) is not tuple:
+                raise TypeError(f"expected: `type[tuple[T, ...]]` for `resultset`; got: {resultset}")
+            output_data_types = get_args(resultset)
+            names = None
+            wrapper = _ResultsetWrapper(None, tuple)
     else:
-        output_data_types = ()
+        if result is not None:
+            output_data_types = (result,)
+        else:
+            output_data_types = ()
+        names = None
+        wrapper = _ResultsetWrapper(None, tuple)
 
-    if sys.version_info >= (3, 14):
-        obj: _SQLObject
-        match stmt:
-            case Template():
-                obj = _SQLTemplate(stmt, args=input_data_types, resultset=output_data_types)
-            case str():
-                obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
-    else:
-        obj = _SQLString(stmt, args=input_data_types, resultset=output_data_types)
+    return input_data_types, output_data_types, names, wrapper
+
+
+FACTORY: SQLFactory = SQLFactory()
 
-    return _SQLImpl(obj)
+sql = FACTORY.sql
+unsafe_sql = FACTORY.unsafe_sql