snake-orm 0.1.0b1__py3-none-any.whl

snakeorm/sql/insert.py

@@ -0,0 +1,149 @@
+"""Emission of parametrised INSERTs (single row, bulk, upsert): `INSERT INTO ... (cols) VALUES (...)`.
+
+They delegate to the dialect the quoting, the placeholders, the conflict clause and `RETURNING`,
+which returns ALL the columns so as to recover whatever the server puts there (autoincrement PK,
+DEFAULT, triggers). Values go into `params`; never interpolated.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.core.exceptions import SnakeEmitError
+from snakeorm.dialects.capabilities import EmptyInsertStyle
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.sql.refs import qualified
+
+
+def emit_insert(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    values: Mapping[str, object],
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `INSERT INTO ... VALUES ...` with RETURNING where applicable.
+
+    With no values the row is all defaults, and there each engine writes something different:
+    `DEFAULT VALUES` is the standard and MySQL does NOT have it —it wants `() VALUES ()`—, so the
+    shape is decided by `dialect.syntax`. A PK-only table is legitimate and must be insertable on all
+    three.
+    """
+    if not values:
+        table_ref = qualified(table.schema, table.name, dialect)
+        empty_row = (
+            "DEFAULT VALUES"
+            if dialect.syntax.empty_insert_style is EmptyInsertStyle.DEFAULT_VALUES
+            else "() VALUES ()"
+        )
+        return f"INSERT INTO {table_ref} {empty_row}{_returning(table, dialect)}", ()
+
+    columns = list(values)
+    params: list[object] = []
+    row_sql = _emit_row(columns, values, dialect, params)
+    sql = f"{_insert_head(table, dialect, columns)} VALUES {row_sql}"
+    return f"{sql}{_returning(table, dialect)}", tuple(params)
+
+
+def emit_insert_many(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    rows: Sequence[Mapping[str, object]],
+) -> tuple[str, tuple[object, ...]]:
+    """Emits a single `INSERT ... VALUES (...), (...), ...` for several rows.
+
+    One single INSERT (not executemany) so that `RETURNING` recovers every row in one go. They must
+    all have the same columns in the same order, or `SnakeEmitError`. The chunking lives in the
+    session.
+    """
+    if not rows:
+        raise SnakeEmitError("A bulk INSERT needs at least one row")
+    columns = list(rows[0])
+    if not columns:
+        raise SnakeEmitError("An INSERT needs at least one column with a value")
+    expected = set(columns)
+    for row in rows:
+        if set(row) != expected:
+            raise SnakeEmitError(
+                "Every row of a bulk INSERT must have the same columns; "
+                f"{sorted(expected)} were expected."
+            )
+
+    params: list[object] = []
+    tuples = ", ".join(_emit_row(columns, row, dialect, params) for row in rows)
+    sql = f"{_insert_head(table, dialect, columns)} VALUES {tuples}"
+    return f"{sql}{_returning(table, dialect)}", tuple(params)
+
+
+def emit_upsert(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    values: Mapping[str, object],
+    *,
+    conflict_columns: Sequence[str],
+    update_columns: Sequence[str] = (),
+) -> tuple[str, tuple[object, ...]]:
+    """Emits an INSERT idempotent under conflict: `INSERT ... <conflict clause> [RETURNING]`.
+
+    The clause (`ON CONFLICT`) is supplied by the dialect. Without `update_columns` it does not touch
+    the existing row. An empty `conflict_columns` is an error. Checking upsert support is the
+    session's business.
+    """
+    if not conflict_columns:
+        raise SnakeEmitError(
+            "An upsert needs at least one conflict column (on_conflict)"
+        )
+    if not values:
+        # Here it does NOT fall back to `DEFAULT VALUES`: SQLite forbids combining it with `ON
+        # CONFLICT`, and an upsert with no values makes no sense (the conflict would be on the
+        # autogenerated PK, which never collides).
+        raise SnakeEmitError(
+            "An upsert needs at least one value to insert: conflict resolution is meaningless "
+            "for a row without columns (the conflict would be on the autogenerated PK, which "
+            "never collides). Use `add` if you only want to insert."
+        )
+
+    conflict = dialect.on_conflict_clause(conflict_columns, update_columns)
+    columns = list(values)
+    params: list[object] = []
+    row_sql = _emit_row(columns, values, dialect, params)
+    sql = f"{_insert_head(table, dialect, columns)} VALUES {row_sql} {conflict}"
+    return f"{sql}{_returning(table, dialect)}", tuple(params)
+
+
+def _insert_head(
+    table: SnakeTableInfo, dialect: SnakeDialect, columns: Sequence[str]
+) -> str:
+    """`INSERT INTO <schema.table> (<quoted cols>)`: header shared by the three emitters."""
+    quoted_columns = ", ".join(dialect.quote_ident(column) for column in columns)
+    table_ref = qualified(table.schema, table.name, dialect)
+    return f"INSERT INTO {table_ref} ({quoted_columns})"
+
+
+def _emit_row(
+    columns: Sequence[str],
+    values: Mapping[str, object],
+    dialect: SnakeDialect,
+    params: list[object],
+) -> str:
+    """`(ph, ph, ...)` for one row: every value enters `params` and numbers its placeholder.
+
+    It walks `columns` (not `values`) to fix the order shared by every row; the numbering runs
+    continuously across rows (which matters on positional dialects, `$1`, `$2`).
+    """
+    placeholders: list[str] = []
+    for column in columns:
+        params.append(values[column])
+        placeholders.append(dialect.placeholder(len(params)))
+    return f"({', '.join(placeholders)})"
+
+
+def _returning(table: SnakeTableInfo, dialect: SnakeDialect) -> str:
+    """` RETURNING <every column>` if the engine supports it, otherwise empty.
+
+    ALL of them (not just the PK): it recovers whatever the server puts there (autoincrement,
+    DEFAULT).
+    """
+    if not dialect.supports_returning:
+        return ""
+    columns = ", ".join(dialect.quote_ident(column.name) for column in table.columns)
+    return f" RETURNING {columns}"

snakeorm/sql/joins.py

@@ -0,0 +1,158 @@
+"""JOIN planning for deep navigation: relationship paths → aliases + JOIN clauses.
+
+A path is `("rel1", ..., "column")`. It assigns an alias to the root (t0) and to every unique prefix
+(t1...), one JOIN per prefix, ordered from parent to child; shared prefixes reuse an alias. It lives
+in `sql/` because it emits SQL; each relationship's target is resolved by an injected
+`resolve_target`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.sql.resolver import SnakeRelationshipResolver
+from snakeorm.core.exceptions import (
+    SnakeRegistryError,
+    SnakeUnknownRelationship,
+    SnakeUnsupportedFeature,
+)
+from snakeorm.metadata import (
+    SnakeRelationshipKind,
+    SnakeRelationshipInfo,
+    SnakeTableInfo,
+)
+from snakeorm.sql.refs import qualified
+
+
+class JoinPlan:
+    """Resolves a set of relationship paths against the graph → aliases + JOIN clauses."""
+
+    def __init__(
+        self,
+        root: SnakeTableInfo,
+        paths: Iterable[tuple[str, ...]],
+        dialect: SnakeDialect,
+        resolver: SnakeRelationshipResolver,
+        relationship_paths: Iterable[tuple[str, ...]] = (),
+        explicit_joins: Iterable[tuple[tuple[str, ...], bool]] = (),
+    ) -> None:
+        self._dialect = dialect
+        self._resolver = resolver
+        self._alias: dict[tuple[str, ...], str] = {(): "t0"}
+        self._table: dict[tuple[str, ...], SnakeTableInfo] = {(): root}
+        self._joins: list[str] = []
+
+        # FILTER/order prefixes: paths ending in a column → INNER JOIN.
+        filter_prefixes: set[tuple[str, ...]] = set()
+        for path in paths:
+            steps = path[:-1]  # the last element is the column, not a relationship
+            for length in range(1, len(steps) + 1):
+                filter_prefixes.add(steps[:length])
+        # INCLUDE prefixes: these are relationships to load → LEFT JOIN (does not lose rows with a
+        # null FK).
+        include_prefixes: set[tuple[str, ...]] = set()
+        for path in relationship_paths:
+            for length in range(1, len(path) + 1):
+                include_prefixes.add(path[:length])
+        # EXPLICIT JOINs (`.join()`): a to-many IS allowed (it multiplies rows on purpose) and its
+        # `how` overrides the inference. It is the ONLY route by which a to-many gets joined.
+        explicit: dict[tuple[str, ...], bool] = dict(explicit_joins)
+        # Sort by length (parent before child) and then lexicographically (deterministic).
+        every = filter_prefixes | include_prefixes | set(explicit)
+        for prefix in sorted(every, key=lambda p: (len(p), p)):
+            if prefix in explicit:
+                # The explicit `how` wins; the to-many is allowed (it is what was asked for).
+                self._add_join(prefix, left=explicit[prefix], allow_to_many=True)
+                continue
+            # LEFT only if it is a pure include; if it is also filtered, INNER (the filter already
+            # demands a match).
+            left = prefix in include_prefixes and prefix not in filter_prefixes
+            self._add_join(prefix, left=left)
+
+    @property
+    def root_alias(self) -> str:
+        """Alias of the query's root table."""
+        return "t0"
+
+    @property
+    def has_joins(self) -> bool:
+        """Tells whether the plan generated any JOIN (there is relationship navigation)."""
+        return bool(self._joins)
+
+    @property
+    def joins(self) -> tuple[str, ...]:
+        """The JOIN clauses in parent-to-child order."""
+        return tuple(self._joins)
+
+    def alias_for(self, prefix: tuple[str, ...]) -> str:
+        """Alias of the table reached by a relationship prefix (`()` = root)."""
+        return self._alias[prefix]
+
+    def table_for(self, prefix: tuple[str, ...]) -> SnakeTableInfo:
+        """Table reached by a relationship prefix (`()` = root). For the SELECT of includes."""
+        return self._table[prefix]
+
+    def _add_join(
+        self, prefix: tuple[str, ...], left: bool = False, allow_to_many: bool = False
+    ) -> None:
+        """Registers the prefix's JOIN leaning on its parent (already present thanks to the order).
+
+        A to-many is only joined with `allow_to_many` (an explicit `.join()`): in any other case
+        duplicating rows would be a silent bug, so it is rejected.
+        """
+        parent = prefix[:-1]
+        relationship = self._relationship(self._table[parent], prefix[-1])
+        if relationship.kind is SnakeRelationshipKind.TO_MANY and not allow_to_many:
+            # A to-many would duplicate rows and its ON would go the other way round (the FK lives
+            # in the child). The type net already forbids it; this is the runtime one.
+            raise SnakeUnsupportedFeature(
+                f"'{prefix[-1]}' is a to-many relationship and changes the number of rows. "
+                f"Use <Model>.{prefix[-1]}.any(...) to filter by existence, "
+                f"or .join(...) if you want the child rows."
+            )
+        # Through the RELATIONSHIP, not through its class name. `.target` is the class name, and
+        # the qualified name the linker computed —`relationship.target_table`— sits on this very
+        # object; asking by name went through the index `register()` overwrites in silence, so two
+        # apps with their own `Customer` in one process produced a JOIN onto the wrong table. Valid
+        # SQL, real rows, no warning. `resolve_relationship` already preferred the qualified name
+        # and its docstring already said it existed "so that fixing the wrong target is ONE change
+        # and not twelve copies" — twelve places used it and these six did not.
+        target, _ = self._resolver.resolve_relationship(relationship)
+        if target is None:
+            raise SnakeRegistryError(
+                f"The target '{relationship.target}' of relationship "
+                f"'{prefix[-1]}' is not registered."
+            )
+        alias = f"t{len(self._alias)}"
+        self._alias[prefix] = alias
+        self._table[prefix] = target
+
+        quote = self._dialect.quote_ident
+        parent_alias = self._alias[parent]
+        if relationship.kind is SnakeRelationshipKind.TO_MANY:
+            # In a to-many the FK lives in the CHILD, so the ON is written the other way round:
+            # `child.fk = parent.pk`. Its pairs are (child_column, parent_column), precisely so the
+            # direction is not flipped.
+            on = " AND ".join(
+                f"{alias}.{quote(child_col)} = {parent_alias}.{quote(parent_col)}"
+                for child_col, parent_col in relationship.foreign_key.pairs
+            )
+        else:
+            on = " AND ".join(
+                f"{parent_alias}.{quote(local)} = {alias}.{quote(remote)}"
+                for local, remote in relationship.foreign_key.pairs
+            )
+        table_ref = qualified(target.schema, target.name, self._dialect)
+        keyword = "LEFT JOIN" if left else "JOIN"
+        self._joins.append(f"{keyword} {table_ref} AS {alias} ON {on}")
+
+    @staticmethod
+    def _relationship(table: SnakeTableInfo, name: str) -> SnakeRelationshipInfo:
+        """Looks the relationship up by name on the table; fails clearly if it does not exist."""
+        for relationship in table.relationships:
+            if relationship.name == name:
+                return relationship
+        raise SnakeUnknownRelationship(
+            f"'{table.name}' does not have a relationship named '{name}'."
+        )

snakeorm/sql/pk_subquery.py

@@ -0,0 +1,54 @@
+"""Rewriting a bulk write with a deep WHERE into `pk IN (subquery)`.
+
+An UPDATE/DELETE whose filter navigates a relationship does not fit in a flat WHERE. Instead of
+`... FROM` (Postgres jargon, not portable), it is rewritten into a subquery that projects the PK
+using the `JoinPlan` of the deep paths. A composite PK uses a row constructor `(a, b) IN (...)`.
+"""
+
+from __future__ import annotations
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.expressions import SnakeCondition
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.sql.condition import emit_condition_into
+from snakeorm.sql.joins import JoinPlan
+from snakeorm.sql.refs import qualified
+from snakeorm.sql.value import Correlation, ExistsAliases
+
+
+def emit_pk_subquery(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    plan: JoinPlan,
+    where: SnakeCondition,
+    params: list[object],
+) -> str:
+    """Emits `SELECT t0."pk"... FROM <table> AS t0 [JOINs] WHERE <deep cond>` (the PK ONLY).
+
+    Reuses the `JoinPlan` and `emit_condition_into` with alias qualification. The WHERE params are
+    accumulated (numbering continues from the UPDATE's SET, positional).
+    """
+    quote = dialect.quote_ident
+    root_alias = plan.root_alias
+    pk_columns = ", ".join(
+        f"{root_alias}.{quote(column.name)}" for column in table.primary_key.columns
+    )
+    table_ref = f"{qualified(table.schema, table.name, dialect)} AS {root_alias}"
+    sql = f"SELECT {pk_columns} FROM {table_ref}"
+    if plan.has_joins:
+        sql = f"{sql} {' '.join(plan.joins)}"
+    correlate = Correlation(parent_ref=root_alias, aliases=ExistsAliases())
+    where_sql = emit_condition_into(where, dialect, params, plan.alias_for, correlate)
+    return f"{sql} WHERE {where_sql}"
+
+
+def emit_pk_in(table: SnakeTableInfo, dialect: SnakeDialect, subquery: str) -> str:
+    """Emits `<pk> IN (subquery)` over the base table (NO alias).
+
+    Simple PK → `"id" IN (...)`; composite → row constructor `("a","b") IN (...)`. Unqualified: the
+    outer UPDATE/DELETE operates on the base table, which carries no alias.
+    """
+    quote = dialect.quote_ident
+    columns = [quote(column.name) for column in table.primary_key.columns]
+    left = columns[0] if len(columns) == 1 else f"({', '.join(columns)})"
+    return f"{left} IN ({subquery})"

snakeorm/sql/refs.py

@@ -0,0 +1,19 @@
+"""How a table is named in the SQL: `"schema"."table"` or just `"table"`.
+
+Centralised because twenty-five call sites build it. SQLite has no named schemas (a `"public"."x"`
+gives `unknown database "public"`), so qualifying per engine has to live in ONE place.
+"""
+
+from __future__ import annotations
+
+from snakeorm.dialects import SnakeDialect
+
+
+def qualified(schema: str, name: str, dialect: SnakeDialect) -> str:
+    """Table reference, qualified by schema ONLY if the engine has schemas.
+
+    On an engine without schemas, qualifying is not cosmetic: it is invalid SQL.
+    """
+    if dialect.supports_schemas:
+        return f"{dialect.quote_ident(schema)}.{dialect.quote_ident(name)}"
+    return dialect.quote_ident(name)

snakeorm/sql/resolver.py

@@ -0,0 +1,28 @@
+"""What the SQL emitter needs from a registry: resolving a relationship to its target.
+
+A Protocol and not `SnakeRegistry` itself, for the reason the whole `sql/` package exists: emitting
+must not depend on the thing that stores models, only on the one question it has to ask. It also
+keeps the tests honest — a double can answer this without standing up a registry, which is what lets
+the negative test re-run the OLD resolution and demand the wrong answer.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from snakeorm.metadata import SnakeRelationshipInfo, SnakeTableInfo
+
+
+class SnakeRelationshipResolver(Protocol):
+    """Answers WHERE a relationship points, unambiguously."""
+
+    def resolve_relationship(
+        self, relationship: SnakeRelationshipInfo
+    ) -> tuple[SnakeTableInfo | None, type | None]:
+        """The target's `(table, class)`, preferring the qualified name over the class name.
+
+        The class name is NOT unique —two apps can each declare a `Customer`— and the index keyed by
+        it is kept by whichever registered last. The qualified name is protected by the collision
+        guard, which is why it is the one that answers.
+        """
+        ...

snakeorm/sql/select.py

@@ -0,0 +1,175 @@
+"""Emission of a parametrised SELECT: orchestrates the grammar, delegates engine bits to the dialect.
+
+Params in a single list (WHERE before LIMIT/OFFSET) for continuous numbering. Without a `plan` →
+single-table, no alias (backwards compatible). With a `plan` → deep navigation: root aliased as t0,
+JOINs and qualified columns. The result is still the root (the JOINs only filter/order).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.core.exceptions import SnakeUnsupportedFeature
+from snakeorm.expressions import SnakeCondition, SnakeLock, SnakeOrder
+from snakeorm.metadata import SnakeColumnInfo, SnakeTableInfo
+from snakeorm.sql.condition import emit_condition_into
+from snakeorm.sql.joins import JoinPlan
+from snakeorm.sql.refs import qualified
+from snakeorm.sql.value import (
+    Correlation,
+    ExistsAliases,
+    Qualify,
+    emit_order_key,
+)
+
+
+def _correlation(
+    table: SnakeTableInfo, dialect: SnakeDialect, plan: JoinPlan | None
+) -> Correlation:
+    """Correlation context for the WHERE's subqueries (how to reference the root).
+
+    With JOINs the root has an alias (`t0`); without them, the table name (the FROM's implicit
+    correlation).
+    """
+    parent_ref = (
+        plan.root_alias if plan is not None else dialect.quote_ident(table.name)
+    )
+    return Correlation(parent_ref=parent_ref, aliases=ExistsAliases())
+
+
+def selected_columns(
+    table: SnakeTableInfo, columns: frozenset[str] | None
+) -> tuple[SnakeColumnInfo, ...]:
+    """The columns to project, in the TABLE's declaration order and never the caller's.
+
+    The order is not a detail: hydration walks the same declaration to build its plan, so a
+    projection sorted by what the user typed would line the row up against the wrong attributes. Two
+    orders is two chances to be wrong, and one of them is silent.
+
+    `None` means every column, which is what every path but `only()`/`defer()` passes.
+    """
+    if columns is None:
+        return table.columns
+    return tuple(column for column in table.columns if column.name in columns)
+
+
+def emit_select(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    where: SnakeCondition | None = None,
+    order_by: tuple[SnakeOrder, ...] = (),
+    limit: int | None = None,
+    offset: int | None = None,
+    plan: JoinPlan | None = None,
+    distinct: bool = False,
+    lock: SnakeLock | None = None,
+    columns: frozenset[str] | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits a parametrised `SELECT [DISTINCT] ... FROM ... [JOINs] [WHERE] [ORDER BY] [LIMIT/OFFSET]`.
+
+    `columns` is the subset `only()`/`defer()` asked for, or `None` for every column. The order is
+    the TABLE's, never the caller's: the hydration plan is built by walking the same declaration, so
+    two orders would be two chances to line the row up wrong.
+    """
+    params: list[object] = []
+    qualify: Qualify | None = plan.alias_for if plan is not None else None
+    root_alias = plan.root_alias if plan is not None else None
+
+    projected = selected_columns(table, columns)
+    columns_sql = ", ".join(
+        _column_ref(root_alias, column.name, dialect) for column in projected
+    )
+    table_ref = qualified(table.schema, table.name, dialect)
+    if root_alias is not None:
+        table_ref = f"{table_ref} AS {root_alias}"
+    keyword = "SELECT DISTINCT" if distinct else "SELECT"
+    sql = f"{keyword} {columns_sql} FROM {table_ref}"
+
+    if plan is not None and plan.has_joins:
+        sql = f"{sql} {' '.join(plan.joins)}"
+
+    if where is not None:
+        correlate = _correlation(table, dialect, plan)
+        sql = f"{sql} WHERE {emit_condition_into(where, dialect, params, qualify, correlate)}"
+
+    if order_by:
+        keys = ", ".join(
+            emit_order_key(key, dialect, params, qualify) for key in order_by
+        )
+        sql = f"{sql} ORDER BY {keys}"
+
+    clause = dialect.limit_offset(limit, offset, params)
+    if clause:
+        sql = f"{sql} {clause}"
+
+    # The lock goes AT THE END of the grammar, after LIMIT/OFFSET: it locks the rows the SELECT
+    # really returns, not the ones it looked at to get to them.
+    if lock is not None and not dialect.supports_row_locking:
+        # It is cut off at COMPILE time (before touching the DB) and the alternative is given,
+        # rather than emitting a `FOR UPDATE` the engine does not understand so that it blows up.
+        raise SnakeUnsupportedFeature(
+            "This engine does not support row locking (`SELECT ... FOR UPDATE`): SQLite locks the "
+            "whole file, not individual rows. Use an exclusive transaction on this engine, or "
+            "PostgreSQL if you need to reserve specific rows."
+        )
+    if lock is not None:
+        sql = f"{sql} {_LOCK_CLAUSES[lock]}"
+
+    return sql, tuple(params)
+
+
+# Lock clause per mode. `WAIT` is the plain `FOR UPDATE` (waiting is its default behaviour), so it
+# carries no suffix.
+_LOCK_CLAUSES: dict[SnakeLock, str] = {
+    SnakeLock.WAIT: "FOR UPDATE",
+    SnakeLock.NOWAIT: "FOR UPDATE NOWAIT",
+    SnakeLock.SKIP_LOCKED: "FOR UPDATE SKIP LOCKED",
+}
+
+
+def emit_select_with_includes(
+    dialect: SnakeDialect,
+    segments: Sequence[tuple[tuple[str, ...], SnakeTableInfo]],
+    plan: JoinPlan,
+    where: SnakeCondition | None = None,
+    order_by: tuple[SnakeOrder, ...] = (),
+    limit: int | None = None,
+    offset: int | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits the SELECT loading the root + included relationships (columns qualified by alias).
+
+    `segments` in order: root `((), table)` and then each relationship `(prefix, table)`. All their
+    columns enter in that order, so the session slices each row by segment and rebuilds the object.
+    """
+    params: list[object] = []
+    qualify: Qualify = plan.alias_for
+    root = segments[0][1]
+
+    columns = ", ".join(
+        f"{plan.alias_for(prefix)}.{dialect.quote_ident(column.name)}"
+        for prefix, segment_table in segments
+        for column in segment_table.columns
+    )
+    table_ref = qualified(root.schema, root.name, dialect)
+    sql = f"SELECT {columns} FROM {table_ref} AS {plan.root_alias}"
+    if plan.has_joins:
+        sql = f"{sql} {' '.join(plan.joins)}"
+    if where is not None:
+        correlate = _correlation(root, dialect, plan)
+        sql = f"{sql} WHERE {emit_condition_into(where, dialect, params, qualify, correlate)}"
+    if order_by:
+        keys = ", ".join(
+            emit_order_key(key, dialect, params, qualify) for key in order_by
+        )
+        sql = f"{sql} ORDER BY {keys}"
+    clause = dialect.limit_offset(limit, offset, params)
+    if clause:
+        sql = f"{sql} {clause}"
+    return sql, tuple(params)
+
+
+def _column_ref(root_alias: str | None, name: str, dialect: SnakeDialect) -> str:
+    """Quotes a column of the root table, with an alias if the query carries JOINs."""
+    column = dialect.quote_ident(name)
+    return f"{root_alias}.{column}" if root_alias is not None else column

snakeorm/sql/update.py

@@ -0,0 +1,82 @@
+"""Emission of a parametrised UPDATE: `UPDATE ... SET ... [WHERE ...]`.
+
+The SET consumes the first params; the WHERE continues the numbering over the same list
+(`emit_condition_into`). `where=None` affects the whole table: the guard-rail lives in query/session.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from snakeorm.dialects import SnakeDialect
+from snakeorm.core.exceptions import SnakeEmitError
+from snakeorm.expressions import SnakeCondition, SnakeValue
+from snakeorm.metadata import SnakeTableInfo
+from snakeorm.sql.condition import emit_condition_into
+from snakeorm.sql.joins import JoinPlan
+from snakeorm.sql.pk_subquery import emit_pk_in, emit_pk_subquery
+from snakeorm.sql.refs import qualified
+from snakeorm.sql.value import emit_operand, emit_value
+
+
+def _emit_set(
+    values: Mapping[str, object], dialect: SnakeDialect, params: list[object]
+) -> str:
+    """Emits the SET's `col = <value>` assignments, accumulating literals into `params`.
+
+    A `SnakeValue` (e.g. `views + 1`) is emitted as an unqualified expression; a literal, as a
+    placeholder. This is what enables `SET views = views + 1`.
+    """
+    assignments = []
+    for column, value in values.items():
+        if isinstance(value, SnakeValue):
+            rendered = emit_value(value, dialect, params, None)
+        else:
+            rendered = emit_operand(value, dialect, params)
+        assignments.append(f"{dialect.quote_ident(column)} = {rendered}")
+    return ", ".join(assignments)
+
+
+def emit_update(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    values: Mapping[str, object],
+    where: SnakeCondition | None = None,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `UPDATE ... SET ... [WHERE ...]` with params apart (SET first, then WHERE)."""
+    if not values:
+        raise SnakeEmitError("An UPDATE needs at least one column in the SET")
+
+    params: list[object] = []
+    set_sql = _emit_set(values, dialect, params)
+    table_ref = qualified(table.schema, table.name, dialect)
+    sql = f"UPDATE {table_ref} SET {set_sql}"
+
+    if where is not None:
+        where_sql = emit_condition_into(where, dialect, params)
+        sql = f"{sql} WHERE {where_sql}"
+
+    return sql, tuple(params)
+
+
+def emit_update_pk_in_subquery(
+    table: SnakeTableInfo,
+    dialect: SnakeDialect,
+    values: Mapping[str, object],
+    plan: JoinPlan,
+    where: SnakeCondition,
+) -> tuple[str, tuple[object, ...]]:
+    """Emits `UPDATE ... SET ... WHERE <pk> IN (SELECT <pk> FROM ... [JOINs] WHERE <deep cond>)`.
+
+    For a WHERE that navigates a relationship (avoids `UPDATE ... FROM`). The SET consumes the first
+    params and the subquery continues from there; the SET still targets the base table.
+    """
+    if not values:
+        raise SnakeEmitError("An UPDATE needs at least one column in the SET")
+
+    params: list[object] = []
+    set_sql = _emit_set(values, dialect, params)
+    table_ref = qualified(table.schema, table.name, dialect)
+    subquery = emit_pk_subquery(table, dialect, plan, where, params)
+    pk_in = emit_pk_in(table, dialect, subquery)
+    return f"UPDATE {table_ref} SET {set_sql} WHERE {pk_in}", tuple(params)