oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/queries/q.py

@@ -0,0 +1,250 @@
+"""Q-expressions for complex boolean filter logic (AND/OR/NOT).
+
+Q objects allow building complex WHERE clauses that cannot be expressed
+with simple keyword arguments. They support boolean operators &, |, ~.
+
+Basic Usage:
+    Q(age__gte=18)          → age >= 18
+    Q(name="Alice")         → name = 'Alice'
+    Q(status__in=["a","b"]) → status IN ('a', 'b')
+
+FK Traversal:
+    Q(user__age__gte=18)    → JOIN user, WHERE user.age >= 18
+    Q(author__name="Bob")   → JOIN author, WHERE author.name = 'Bob'
+
+Combining with AND:
+    Q(age__gte=18) & Q(status="active")
+    → age >= 18 AND status = 'active'
+
+Combining with OR:
+    Q(role="admin") | Q(role="moderator")
+    → role = 'admin' OR role = 'moderator'
+
+Negation with NOT:
+    ~Q(status="banned")
+    → NOT (status = 'banned')
+
+Complex Nesting:
+    Q(age__gte=18) & (Q(status="active") | Q(premium=True))
+    → age >= 18 AND (status = 'active' OR premium = true)
+
+Implementation:
+    Q stores either:
+    - _kwargs: dict of field lookups (leaf node)
+    - _op + _children: boolean operation with child Q objects
+
+    to_filter_node(model_class, query) recursively converts Q tree to FilterNode
+    IR format that Rust understands. If query is provided and FK paths are used,
+    JOINs are automatically added to the query.
+
+Usage in Queries:
+    User.objects.filter(Q(age__gte=18) | Q(premium=True))
+    User.objects.filter(Q(status="active"), name__startswith="A")  # mixed
+    User.objects.exclude(Q(role="bot") | Q(status="banned"))
+    Post.objects.filter(user__age__gte=18)  # FK traversal with auto-JOIN
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from oxyde.core.ir import FilterNode, filter_and, filter_not, filter_or
+from oxyde.models.lookups import _build_lookup_conditions, _resolve_lookup
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+class Q:
+    """
+    Q-expression for building complex filter conditions with AND/OR/NOT logic.
+
+    Usage:
+        Q(age__gte=18) & Q(status="active")
+        Q(age__gte=18) | Q(premium=True)
+        ~Q(status="banned")
+        Q(age__gte=18) & (Q(status="active") | Q(status="premium"))
+    """
+
+    _node: FilterNode | None
+    _kwargs: dict[str, Any]
+    _op: str | None
+    _children: list[Q]
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        """
+        Create a Q expression from conditions.
+
+        Args:
+            **kwargs: Field lookups (e.g., age__gte=18, name__contains="John")
+        """
+        self._op = None
+        self._children = []
+
+        if args and not kwargs:
+            # Q(condition_node) - wrap existing FilterNode
+            if len(args) == 1 and isinstance(args[0], dict):
+                self._node = args[0]
+                self._kwargs = {}
+            else:
+                raise ValueError(
+                    "Q() with positional args must receive a single FilterNode dict"
+                )
+        elif not args and kwargs:
+            # Q(age=18, status="active") - build from kwargs
+            self._node = None
+            self._kwargs = kwargs
+        elif not args and not kwargs:
+            # Q() - empty, will be filtered out
+            self._node = None
+            self._kwargs = {}
+        else:
+            raise ValueError(
+                "Q() accepts either positional FilterNode or keyword lookups, not both"
+            )
+
+    def _ensure_node(
+        self,
+        model_class: type[Model] | None = None,
+        query: Any = None,
+    ) -> FilterNode | None:
+        """Convert kwargs to FilterNode if needed.
+
+        Args:
+            model_class: Model class for field resolution
+            query: Optional query object for adding JOINs when FK paths are used
+        """
+        if self._node is not None:
+            return self._node
+        if not self._kwargs:
+            return None
+
+        if model_class is None:
+            raise ValueError(
+                "Q expression with kwargs requires model_class to resolve fields"
+            )
+
+        conditions: list[FilterNode] = []
+
+        for key, value in self._kwargs.items():
+            # e.g. "name__icontains", or "user__age__gte" through FK relations
+            resolved, lookup = _resolve_lookup(model_class, key)
+            column_meta = resolved.column_meta
+
+            qualified_column = None
+            if resolved.joins:
+                join_path = "__".join(name for name, _ in resolved.joins)
+                # Add JOINs to query if provided
+                if query is not None:
+                    query._add_join_path(join_path)
+                # Qualified column name "alias.column": the alias is the join
+                # path with __ replaced by _
+                alias = "_".join(name for name, _ in resolved.joins)
+                qualified_column = f"{alias}.{column_meta.db_column}"
+
+            field_conditions = _build_lookup_conditions(
+                resolved.final_model,
+                resolved.final_field,
+                lookup,
+                value,
+                column_meta,
+            )
+            if qualified_column is not None:
+                for cond in field_conditions:
+                    cond.column = qualified_column
+            conditions.extend([c.to_ir() for c in field_conditions])
+
+        if not conditions:
+            return None
+        if len(conditions) == 1:
+            return conditions[0]
+        return filter_and(*conditions)
+
+    def __and__(self, other: Q) -> Q:
+        """Combine with AND logic: Q(...) & Q(...)"""
+        if not isinstance(other, Q):
+            raise TypeError(f"Cannot AND Q with {type(other)}")
+        result = Q()
+        result._op = "and"
+        result._children = [self, other]
+        return result
+
+    def __or__(self, other: Q) -> Q:
+        """Combine with OR logic: Q(...) | Q(...)"""
+        if not isinstance(other, Q):
+            raise TypeError(f"Cannot OR Q with {type(other)}")
+        result = Q()
+        result._op = "or"
+        result._children = [self, other]
+        return result
+
+    def __invert__(self) -> Q:
+        """Negate with NOT logic: ~Q(...)"""
+        result = Q()
+        result._op = "not"
+        result._children = [self]
+        return result
+
+    def to_filter_node(
+        self,
+        model_class: type[Model],
+        query: Any = None,
+    ) -> FilterNode | None:
+        """
+        Convert Q expression to FilterNode for IR.
+
+        Args:
+            model_class: Model class for field resolution
+            query: Optional query object for adding JOINs when FK paths are used
+
+        Returns:
+            FilterNode dict or None if empty
+        """
+        # Check if this is a combined Q with operations
+        op = getattr(self, "_op", None)
+        children = getattr(self, "_children", None)
+
+        if op and children:
+            # Recursively resolve children
+            child_nodes: list[FilterNode] = []
+            for child in children:
+                node = child.to_filter_node(model_class, query)
+                if node is not None:
+                    child_nodes.append(node)
+
+            if not child_nodes:
+                return None
+
+            if op == "and":
+                if len(child_nodes) == 1:
+                    return child_nodes[0]
+                return filter_and(*child_nodes)
+            elif op == "or":
+                if len(child_nodes) < 2:
+                    # OR requires at least 2 conditions, return single or None
+                    return child_nodes[0] if child_nodes else None
+                return filter_or(*child_nodes)
+            elif op == "not":
+                if not child_nodes:
+                    return None
+                return filter_not(child_nodes[0])
+
+        # Leaf Q expression
+        return self._ensure_node(model_class, query)
+
+    def __repr__(self) -> str:
+        op = getattr(self, "_op", None)
+        if op:
+            children = getattr(self, "_children", [])
+            if op == "not":
+                return f"~{children[0]!r}"
+            else:
+                sep = f" {op.upper()} "
+                return f"({sep.join(repr(c) for c in children)})"
+        elif self._node:
+            return f"Q({self._node})"
+        else:
+            return f"Q({', '.join(f'{k}={v!r}' for k, v in self._kwargs.items())})"
+
+
+__all__ = ["Q"]

oxyde/queries/raw.py

@@ -0,0 +1,114 @@
+"""Raw SQL execution with automatic connection resolution.
+
+This module provides execute_raw() - a function for executing arbitrary SQL
+while respecting the same connection resolution logic as Model.objects.
+
+Connection Resolution:
+    1. Explicit client parameter (AsyncDatabase or AsyncTransaction)
+    2. Active transaction (if inside atomic())
+    3. Named connection (using="alias")
+    4. Default connection ("default")
+
+Example:
+    from oxyde import execute_raw
+
+    # Simple query (uses default connection)
+    users = await execute_raw("SELECT * FROM users WHERE age > $1", [18])
+
+    # Inside transaction - automatically uses same transaction
+    async with transaction.atomic():
+        await User.objects.create(name="Alice")
+        await execute_raw("INSERT INTO audit_log VALUES ($1, $2)", [1, "created"])
+
+    # Specific connection
+    stats = await execute_raw("SELECT ...", using="analytics")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from oxyde._msgpack import msgpack
+from oxyde.queries.base import _resolve_execution_client
+
+if TYPE_CHECKING:
+    from oxyde.queries.base import SupportsExecute
+
+
+async def execute_raw(
+    sql: str,
+    params: list[Any] | None = None,
+    *,
+    using: str | None = None,
+    client: SupportsExecute | None = None,
+) -> list[dict[str, Any]]:
+    """
+    Execute raw SQL query.
+
+    Uses the same connection resolution as Model.objects:
+    - Active transaction (if inside atomic())
+    - Named connection (using="alias")
+    - Default connection
+
+    Args:
+        sql: SQL with PostgreSQL placeholders ($1, $2, ...)
+        params: Query parameters (use these to prevent SQL injection!)
+        using: Connection alias (default: "default")
+        client: Explicit client (AsyncDatabase or AsyncTransaction)
+
+    Returns:
+        List of dicts for SELECT queries.
+        Empty list for INSERT/UPDATE/DELETE without RETURNING.
+
+    Raises:
+        RuntimeError: If no connection is available.
+        ManagerError: If both 'using' and 'client' are provided.
+
+    Example:
+        # Simple SELECT
+        users = await execute_raw("SELECT * FROM users WHERE age > $1", [18])
+
+        # Inside transaction (automatically uses same tx)
+        async with transaction.atomic():
+            await User.objects.create(name="Alice")
+            await execute_raw(
+                "INSERT INTO audit_log (user_id, action) VALUES ($1, $2)",
+                [1, "created"]
+            )
+
+        # PostgreSQL-specific features
+        results = await execute_raw(
+            "SELECT * FROM products WHERE metadata @> $1::jsonb",
+            ['{"featured": true}']
+        )
+
+        # Different connection
+        stats = await execute_raw("SELECT ...", using="analytics")
+
+    Warning:
+        Always use parameterized queries! Never interpolate user input:
+
+        # GOOD
+        await execute_raw("SELECT * FROM users WHERE email = $1", [email])
+
+        # BAD - SQL injection risk!
+        await execute_raw(f"SELECT * FROM users WHERE email = '{email}'")
+    """
+    execution_client = await _resolve_execution_client(using, client)
+
+    ir = {
+        "proto": 1,
+        "op": "raw",
+        "table": "",
+        "sql": sql,
+        "params": params or [],
+    }
+
+    result_bytes = await execution_client.execute(ir)
+
+    # Columnar format from Rust: (columns, rows) -> list[dict]
+    columns, rows = msgpack.unpackb(result_bytes, raw=False)
+    return [dict(zip(columns, row)) for row in rows]
+
+
+__all__ = ["execute_raw"]

oxyde/queries/select.py

@@ -0,0 +1,345 @@
+"""SELECT query builder with Django-style fluent interface.
+
+This module provides the Query class - the primary way to build SELECT queries
+in Oxyde. Query objects are immutable: each method returns a new Query instance.
+
+Architecture:
+    Query inherits from multiple mixins that provide different capabilities:
+        FilteringMixin: filter(), exclude()
+        PaginationMixin: limit(), offset(), order_by(), distinct(), values()
+        JoiningMixin: join(), prefetch()
+        AggregationMixin: annotate(), group_by(), having(), count(), sum()
+        ExecutionMixin: fetch_all(), fetch_models(), exists(), all()
+        MutationMixin: update(), delete(), increment()
+        DebugMixin: sql(), explain(), union()
+
+Immutability:
+    All methods return new Query instances via _clone(). The original is unchanged.
+
+    base = User.objects.filter(active=True)
+    admins = base.filter(role="admin")  # base is unchanged
+    users = base.filter(role="user")    # base is unchanged
+
+State Attributes:
+    _filter_tree: FilterNode tree for WHERE clause
+    _limit_value: LIMIT value
+    _offset_value: OFFSET value
+    _order_by_fields: List of (field, direction) tuples
+    _selected_fields: Explicit field list or None for all
+    _distinct: DISTINCT flag
+    _join_specs: JOIN descriptors
+    _annotations: Aggregate aliases {alias: Aggregate}
+    _group_by_fields: GROUP BY columns
+    _lock_type: "update" | "share" | None for row locking
+
+Execution:
+    to_ir() converts Query state to dict (Intermediate Representation).
+    IR is serialized to MessagePack and sent to Rust for SQL generation.
+
+    The IR includes column_types (ColumnTypeSpec dicts per column)
+    which enables type-aware decoding in Rust without expensive type_info() calls.
+
+Example:
+    query = (
+        User.objects
+        .filter(status="active")
+        .exclude(role="bot")
+        .order_by("-created_at")
+        .limit(10)
+    )
+    ir = query.to_ir()
+    # {"table": "user", "columns": [...], "col_types": {"id": "int", ...}, ...}
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from typing_extensions import Self
+
+from oxyde.core import ir
+from oxyde.models.utils import _unwrap_optional
+from oxyde.queries.base import _model_key
+from oxyde.queries.joins import _JoinDescriptor
+from oxyde.queries.mixins import (
+    AggregationMixin,
+    DebugMixin,
+    ExecutionMixin,
+    FilteringMixin,
+    JoiningMixin,
+    MutationMixin,
+    PaginationMixin,
+)
+
+if TYPE_CHECKING:
+    from oxyde.models.base import Model
+
+
+TModel = TypeVar("TModel", bound="Model")
+
+
+class Query(
+    FilteringMixin[TModel],
+    PaginationMixin[TModel],
+    JoiningMixin[TModel],
+    AggregationMixin[TModel],
+    ExecutionMixin[TModel],
+    MutationMixin[TModel],
+    DebugMixin[TModel],
+    Generic[TModel],
+):
+    """
+    Query builder for SELECT operations.
+
+    Combines all query capabilities through mixins:
+    - FilteringMixin: filter, exclude
+    - PaginationMixin: limit, offset, order_by, distinct, values, values_list
+    - JoiningMixin: join, prefetch
+    - AggregationMixin: annotate, group_by, having, count, sum, avg, max, min
+    - ExecutionMixin: fetch_all, fetch_one, fetch_models, exists, all
+    - MutationMixin: update, delete, increment
+    - DebugMixin: sql, query, explain, union, union_all
+    """
+
+    def __init__(self, model_class: type[TModel]):
+        self.model_class = model_class
+        # Filtering state
+        self._filter_tree: ir.FilterNode | None = None
+        # Pagination state
+        self._limit_value: int | None = None
+        self._offset_value: int | None = None
+        self._order_by_fields: list[tuple[str, str]] = []
+        self._selected_fields: list[str] | None = None
+        self._distinct: bool = False
+        self._result_mode: str | None = None
+        self._values_flat: bool = False
+        # Joining state
+        self._join_specs: list[_JoinDescriptor] = []
+        self._prefetch_paths: list[str] = []
+        # Aggregation state
+        self._annotations: dict[str, Any] = {}
+        self._group_by_fields: list[str] = []
+        self._having: ir.FilterNode | None = None
+        # Union state
+        self._union_query: Query | None = None
+        self._union_all: bool = False
+        # Locking state (FOR UPDATE / FOR SHARE)
+        self._lock_type: str | None = None
+        # Shortcut query flags (count / exists)
+        self._count: bool = False
+        self._exists: bool = False
+
+    def _clone(self) -> Self:
+        """Create a copy of this query."""
+        clone = self.__class__(self.model_class)
+        # Filtering
+        clone._filter_tree = self._filter_tree
+        # Pagination
+        clone._limit_value = self._limit_value
+        clone._offset_value = self._offset_value
+        clone._order_by_fields = list(self._order_by_fields)
+        clone._selected_fields = (
+            None if self._selected_fields is None else list(self._selected_fields)
+        )
+        clone._distinct = self._distinct
+        clone._result_mode = self._result_mode
+        clone._values_flat = self._values_flat
+        # Joining
+        clone._join_specs = list(self._join_specs)
+        clone._prefetch_paths = list(self._prefetch_paths)
+        # Aggregation
+        clone._annotations = dict(self._annotations)
+        clone._group_by_fields = list(self._group_by_fields)
+        clone._having = self._having
+        # Union
+        clone._union_query = self._union_query
+        clone._union_all = self._union_all
+        # Locking
+        clone._lock_type = self._lock_type
+        # Shortcut flags
+        clone._count = self._count
+        clone._exists = self._exists
+        return clone
+
+    def select(self, *fields: str) -> Self:
+        """Specify fields to select."""
+        if not fields:
+            raise ValueError("select() requires at least one column name")
+        clone = self._clone()
+        clone._selected_fields = list(fields)
+        return clone
+
+    def for_update(self) -> Self:
+        """Add FOR UPDATE lock to query.
+
+        Locks selected rows for update, preventing other transactions
+        from modifying them until the current transaction commits.
+
+
+        Returns:
+            Query with FOR UPDATE lock
+
+        Examples:
+            async with atomic():
+                user = await User.objects.filter(id=1).for_update().first()
+                user.balance -= 100
+                await user.save()
+        """
+        clone = self._clone()
+        clone._lock_type = "update"
+        return clone
+
+    def for_share(self) -> Self:
+        """Add FOR SHARE lock to query.
+
+        Locks selected rows for reading, preventing other transactions
+        from modifying them (but allowing reads) until the current
+        transaction commits.
+
+
+        Returns:
+            Query with FOR SHARE lock
+
+        Examples:
+            async with atomic():
+                users = await User.objects.filter(status="active").for_share().all()
+                # Other transactions can read but not modify these rows
+        """
+        clone = self._clone()
+        clone._lock_type = "share"
+        return clone
+
+    def _column_types_for_query(self) -> dict[str, dict] | None:
+        """Return base and joined column type specs keyed by SQL/result column names."""
+        base_types = self.model_class._db_meta.column_types or {}
+        column_types: dict[str, dict] = dict(base_types)
+
+        for descriptor in self._join_specs:
+            target_types = descriptor.target_model._db_meta.column_types or {}
+            for field, column in descriptor.columns:
+                spec = target_types.get(column)
+                if spec is None:
+                    continue
+                # Qualified column reference (filters on the joined table)
+                column_types[f"{descriptor.alias}.{column}"] = spec
+                # Result column: the SQL aliases joined columns by *field*
+                # name, which differs from the column when db_column is set
+                column_types[f"{descriptor.result_prefix}__{field}"] = spec
+
+        return column_types or None
+
+    def _column_db_types_for_query(self) -> dict[str, str] | None:
+        """Return base and joined db_type overrides keyed by SQL column
+        reference ("alias.column" for joined columns, as filters name them)."""
+        column_db_types = dict(self.model_class._db_meta.column_db_types or {})
+
+        for descriptor in self._join_specs:
+            target_db_types = descriptor.target_model._db_meta.column_db_types or {}
+            for _field, column in descriptor.columns:
+                db_type = target_db_types.get(column)
+                if db_type is not None:
+                    column_db_types[f"{descriptor.alias}.{column}"] = db_type
+
+        return column_db_types or None
+
+    def to_ir(self) -> dict[str, Any]:
+        """Convert query to IR format for Rust execution."""
+        from oxyde.models.base import Model
+
+        table_name = self.model_class.get_table_name()
+
+        # Get fields to select (exclude virtual relation fields and FK model fields)
+        if self._selected_fields is None:
+            fields = []
+            for field_name, field_info in self.model_class.model_fields.items():
+                # Skip virtual relation fields (db_reverse_fk, db_m2m)
+                if getattr(field_info, "db_reverse_fk", None) or getattr(
+                    field_info, "db_m2m", False
+                ):
+                    continue
+                # Skip FK model fields (user: User) - we select user_id instead
+                annotation = field_info.annotation
+                if annotation is not None:
+                    inner_type, _ = _unwrap_optional(annotation)
+                    if isinstance(inner_type, type) and issubclass(inner_type, Model):
+                        continue
+                fields.append(field_name)
+        else:
+            if not self._selected_fields:
+                raise ValueError("SELECT query must include at least one column")
+            fields = self._selected_fields
+
+        # Convert field names to db_columns for Rust (Rust operates on columns only)
+        db_columns = [self._column_for_field(f) for f in fields]
+        order_by = [
+            (field if field == "?" else self._column_for_field(field), direction)
+            for field, direction in self._order_by_fields
+        ]
+
+        # Build filter_tree
+        final_filter_tree = self._build_filter_tree()
+
+        # Convert annotations to aggregates IR format (supports multiple aggregates)
+        aggregates_ir = None
+        if self._annotations:
+            aggregates_ir = []
+            for alias, agg_obj in self._annotations.items():
+                if not hasattr(agg_obj, "to_ir"):
+                    raise TypeError(f"annotate() received non-expression: {agg_obj!r}")
+                agg_spec = agg_obj.to_ir()
+                func_name = agg_spec.get("func", "").lower()
+                agg_ir: dict[str, Any] = {
+                    "op": func_name,
+                    "field": agg_spec.get("field"),
+                    "alias": alias,
+                }
+                if agg_spec.get("distinct"):
+                    agg_ir["distinct"] = True
+                aggregates_ir.append(agg_ir)
+
+        # Convert group_by fields to column names
+        group_by_columns = None
+        if self._group_by_fields:
+            group_by_columns = [
+                self._column_for_field(field) for field in self._group_by_fields
+            ]
+
+        # Use cached col_types from model metadata plus joined column aliases.
+        column_types = self._column_types_for_query()
+
+        # Pass pk_column only for JOIN queries (needed for deduplication)
+        pk_column = None
+        if self._join_specs:
+            pk_column = self.model_class._db_meta.pk_column
+
+        # Build union IR recursively
+        union_ir = None
+        if self._union_query is not None:
+            union_ir = self._union_query.to_ir()
+
+        return ir.build_select_ir(
+            table=table_name,
+            columns=db_columns,
+            column_types=column_types,
+            column_db_types=self._column_db_types_for_query(),
+            model=_model_key(self.model_class),
+            column_mappings=None,
+            filter_tree=final_filter_tree,
+            distinct=self._distinct or None,
+            limit=self._limit_value,
+            offset=self._offset_value,
+            order_by=order_by or None,
+            joins=self._join_specs_to_ir() or None,
+            group_by=group_by_columns,
+            having=self._having,
+            aggregates=aggregates_ir,
+            lock=self._lock_type,
+            pk_column=pk_column,
+            union_query=union_ir,
+            union_all=self._union_all or None,
+            count=self._count or None,
+            exists=self._exists or None,
+        )
+
+
+__all__ = ["Query"]