waxsql 1.0.0__py3-none-any.whl

waxsql/gen/cte.py

@@ -0,0 +1,367 @@
+"""CTE definition generator.
+
+Role: produces the body of one WITH-clause entry. Two public entry
+points — `gen_cte_def` for plain CTEs, `gen_recursive_cte_def` for
+the rigidly-shaped `WITH RECURSIVE` form.
+
+INVARIANT on recursive CTEs: the structure is non-negotiable —
+non-recursive "anchor" UNION ALL recursive "step", with the
+self-reference appearing only in the step. Any other shape (anchor
+on the right, no UNION, self-reference in the anchor) is a PG parse
+error. The two-arm builder pair below enforces the shape by
+construction; the printer just renders it.
+
+Single public entry point: `gen_cte_def(ctx, name)` builds one
+CteDef. The orchestration of multi-CTE WITH clauses lives in
+`gen/select.py` (`_gen_with_clause`), which calls `gen_cte_def` in
+a loop and registers each result in the parent scope before
+generating the next — that's what lets later CTEs reference earlier
+ones without forward references.
+
+A CTE body is a full SELECT generated via `gen_select` on a child
+context, with a few constraints:
+
+  * `descend_subquery(correlated=False)` — CTE bodies are
+    self-contained; they don't reference outer-query *columns*. They
+    DO see outer *CTEs* via lookup_cte's unconditional parent-chain
+    walk, but that's a separate visibility rule.
+
+  * `allow_with=False` (set by descend_subquery) — milestone 5
+    keeps WITHs top-level only; the CTE body can't have its own
+    nested WITH.
+
+  * Single-target output with explicit `c1` alias on the target —
+    same predictable-column-resolution pattern as derived tables.
+
+The lazy import of `gen_select` is the standard cycle-breaking
+trick: `gen_select` calls into `gen_cte_def` (via
+`_gen_with_clause`), and `gen_cte_def` calls `gen_select` for the
+inner body, so a top-level import at either end would close the
+loop. Lazy import inside the function keeps both modules importable
+in either order.
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+
+from ..ast import (
+    BinaryOp, ColumnRef, CteCycle, CteDef, CteRef, CteSearch, Expr,
+    FromItem, Literal, Select, SelectTarget, SetOp, TableRef,
+)
+from ..context import GenContext
+from ..types import BOOL, INT4, INT8, NUMERIC, PgType, TEXT, TIMESTAMPTZ
+from .expr import gen_expr
+
+
+# Probabilities for the optional SEARCH and CYCLE clauses on a
+# recursive CTE. Independent dice rolls — both can fire on the same
+# CTE, both can be skipped. Real-world recursive CTEs are usually
+# bare (no SEARCH/CYCLE); these probabilities are biased moderate-low.
+_P_RECURSIVE_SEARCH: float = 0.3
+_P_RECURSIVE_CYCLE: float = 0.3
+
+
+# Recursive CTE column type pool. Restricted to types where
+# arithmetic-style recursion is meaningful (counter increments,
+# string concatenation paths). The base/recursive arms must agree
+# on column type; this pool is what both arms produce.
+_RECURSIVE_COLUMN_TYPES: tuple[PgType, ...] = (
+    INT4, INT8, NUMERIC, TEXT,
+)
+
+
+def gen_cte_def(
+    ctx: GenContext,
+    name: str,
+) -> tuple[CteDef, list[tuple[str, PgType]]]:
+    """Generate one non-recursive CTE definition.
+
+    Returns a `(CteDef, columns)` tuple — the AST node for inclusion
+    in the WITH list, plus the column info for registration in the
+    enclosing scope (so subsequent CTEs and the main query body can
+    resolve `cte_name.col` references).
+
+    The body is a 1..N-target SELECT with explicit `cN` aliases.
+    The inner SELECT is generated by gen_select (which produces a
+    single target by design); we then synthesize additional targets
+    here when the column-count draw says so. Synthetic extra targets
+    are generated under the same scope as the gen_select body, so
+    they can reference the same FROM-clause columns.
+
+    The single-column case stays the most common shape because
+    max_cte_columns is small (3). Recursive CTEs are kept single-
+    column — see gen_recursive_cte_def for why.
+    """
+    # Lazy import — gen/select.py imports `_gen_with_clause` (which
+    # calls this function), creating an import cycle if we did the
+    # gen_select import at module top-level.
+    from .select import gen_select
+
+    # Descend into a fresh subquery context. correlated=False because
+    # CTE bodies don't reference outer-query columns; CTE-to-CTE
+    # references work through lookup_cte (unconditional parent walk),
+    # not through column visibility.
+    child_ctx = ctx.descend_subquery(correlated=False)
+    inner = gen_select(child_ctx)
+
+    # Decide on column count. The inner SELECT already produced one
+    # target; if we want more, generate them in the same child scope
+    # (so they see the same FROM-clause bindings). The +1 is because
+    # rng.randint is inclusive — we want 1..max with 1 being valid.
+    #
+    # SUBTLE: skip extras entirely when the inner is aggregate-mode
+    # (group_by non-empty). The existing target was generated under
+    # the GROUP BY constraint; adding plain column refs as extras
+    # would violate the "every non-aggregate target must be in GROUP
+    # BY" rule (PG: 42803). Detecting this and synthesizing matching
+    # grouped extras is doable but requires GROUP-BY-list awareness
+    # — out of scope for the polish item. Single-column aggregate
+    # CTEs remain valid; this just narrows multi-column to non-
+    # aggregate CTE bodies.
+    is_aggregate_mode = bool(inner.group_by)
+    n_extra = (
+        0 if is_aggregate_mode
+        else child_ctx.rng.randint(0, child_ctx.config.max_cte_columns - 1)
+    )
+    extra_exprs: list[Expr] = []
+    if n_extra > 0:
+        target_ctx = replace(child_ctx, allow_aggregates=False)
+        extra_types = [
+            child_ctx.rng.choice(_RECURSIVE_COLUMN_TYPES)
+            for _ in range(n_extra)
+        ]
+        extra_exprs = [gen_expr(target_ctx, t) for t in extra_types]
+
+    # Build the final aliased target list: original target as c1,
+    # extras as c2, c3, ...
+    all_exprs = [inner.targets[0].expr, *extra_exprs]
+    inner_aliased = replace(
+        inner,
+        targets=tuple(
+            SelectTarget(expr=e, alias=f"c{i + 1}")
+            for i, e in enumerate(all_exprs)
+        ),
+    )
+
+    columns = [(f"c{i + 1}", e.pg_type) for i, e in enumerate(all_exprs)]
+    return CteDef(name=name, select=inner_aliased), columns
+
+
+def gen_recursive_cte_def(
+    ctx: GenContext,
+    name: str,
+) -> tuple[CteDef, list[tuple[str, PgType]]]:
+    """Generate a recursive CTE: `name AS (base UNION ALL recursive)`.
+
+    Two arms in a SetOp wrapper:
+
+      * **Base arm**: ordinary single-target SELECT with a
+        deterministic column type from `_RECURSIVE_COLUMN_TYPES`.
+        No self-reference (the CTE doesn't exist yet from PG's
+        POV when the base arm is evaluated).
+
+      * **Recursive arm**: a SELECT whose FROM clause contains a
+        CteRef to `name`. This is the forced self-reference — without
+        it, the CTE wouldn't actually recurse (and PG would treat the
+        WITH as effectively non-recursive). The recursive arm's
+        target type matches the base arm's.
+
+    The CTE is registered in `ctx.scope` BEFORE the recursive arm is
+    generated, so the recursive arm's gen_expr / _make_from_item can
+    resolve the name. The caller (`_gen_with_clause`) must NOT
+    re-register; we return the same `(CteDef, columns)` shape as
+    `gen_cte_def` for consistency, but signal "already registered"
+    by virtue of the caller checking `cte_def.recursive`.
+    """
+    rng = ctx.rng
+    cfg = ctx.config
+
+    # Pick the column count and types. Both arms must produce N
+    # targets in the same positional order, with each cN matching
+    # in type — that's the structural invariant for `UNION ALL`
+    # between the arms.
+    n_cols = rng.randint(1, cfg.max_cte_columns)
+    target_types = tuple(
+        rng.choice(_RECURSIVE_COLUMN_TYPES) for _ in range(n_cols)
+    )
+    columns = [(f"c{i + 1}", t) for i, t in enumerate(target_types)]
+
+    # ---- Base arm -----------------------------------------------------
+    # No self-reference. Use a fresh subquery scope, generate FROM
+    # and N typed targets aliased c1..cN.
+    base_ctx = ctx.descend_subquery(correlated=False)
+    base = _build_recursive_arm_base(base_ctx, target_types)
+
+    # ---- Register CTE in OUTER scope BEFORE recursive arm ------------
+    # The recursive arm's _make_from_item (or gen_expr) must be able
+    # to find `name` via has_visible_ctes / lookup_cte.
+    # ORDERING DEPENDENCY: this registration MUST happen between the
+    # base-arm build and the recursive-arm build. Registering earlier
+    # would let the base arm see its own name (PG rejects this);
+    # registering later would mean the recursive arm has no name to
+    # reference and the WITH would silently degrade to non-recursive.
+    ctx.scope.add_cte(name, columns)
+
+    # ---- Recursive arm with forced self-reference --------------------
+    # Build a Select whose FROM clause includes a CteRef to `name`.
+    # Same mechanism as milestone 3's forced correlation predicate
+    # and milestone 4's LATERAL forcer: the structural enforcement
+    # of "this thing actually exercises the feature."
+    rec_ctx = ctx.descend_subquery(correlated=False)
+    rec = _build_recursive_arm_self_ref(rec_ctx, name, target_types)
+
+    body = SetOp(op="UNION", all=True, arms=(base, rec))
+
+    # Optional SEARCH and CYCLE clauses — independent dice rolls.
+    # Both reference c1 only (the first column), even when the CTE
+    # has multiple columns. PG accepts SEARCH/CYCLE on any subset of
+    # the CTE's exposed columns; sticking with c1 keeps the invariant
+    # simple and matches the most common real-world shape.
+    # The synthetic columns (search_seq / is_cycle / cycle_path) are
+    # deliberately NOT added to the CTE's exposed `columns` list:
+    # outer queries don't try to reference them by name, and
+    # registering them would require modeling PG's row-array type
+    # which isn't in our type system. PG happily defines them and
+    # ignores the lack of outer use.
+    search = None
+    if rng.random() < _P_RECURSIVE_SEARCH:
+        search = CteSearch(
+            breadth_first=rng.random() < 0.5,
+            by_columns=("c1",),
+            set_column="search_seq",
+        )
+    cycle = None
+    if rng.random() < _P_RECURSIVE_CYCLE:
+        cycle = CteCycle(
+            columns=("c1",),
+            cycle_mark_column="is_cycle",
+            path_column="cycle_path",
+        )
+
+    return CteDef(
+        name=name, select=body, recursive=True,
+        search=search, cycle=cycle,
+    ), columns
+
+
+def _build_recursive_arm_base(
+    ctx: GenContext,
+    target_types: tuple[PgType, ...],
+) -> Select:
+    """Build the base arm of a recursive CTE — a non-self-referencing
+    SELECT with N targets of the requested types, aliased c1..cN."""
+    from .select import _gen_from_clause
+
+    from_ = _gen_from_clause(ctx)
+
+    # Generate one target per requested type. allow_aggregates=False
+    # because the base arm is a non-aggregate SELECT (matching the
+    # recursive arm's shape; aggregate-recursive bodies have weird
+    # interactions with the recursion termination semantics).
+    expr_ctx = replace(ctx, allow_aggregates=False)
+    targets = tuple(
+        SelectTarget(expr=gen_expr(expr_ctx, t), alias=f"c{i + 1}")
+        for i, t in enumerate(target_types)
+    )
+
+    return Select(targets=targets, from_=from_)
+
+
+def _build_recursive_arm_self_ref(
+    ctx: GenContext,
+    cte_name: str,
+    target_types: tuple[PgType, ...],
+) -> Select:
+    """Build the recursive arm — a SELECT whose FROM contains a
+    CteRef to `cte_name` (forcing actual self-reference). Each of
+    the N targets is a column ref to the corresponding self.cN
+    (so the recursive types match the base types by construction).
+
+    Optionally adds a base table to the FROM as well — `WITH
+    RECURSIVE r AS (... UNION ALL SELECT r.c1, r.c2 FROM r, base
+    WHERE ...)` is the canonical recursive shape (CTE + driver
+    table joined to walk a relation).
+
+    The termination WHERE predicate uses self.c1 only — works for
+    any column type that has `<` in our catalog, and limiting on
+    one column is sufficient to bound recursion depth.
+    """
+    rng = ctx.rng
+
+    # CteRef to self — give it a fresh tN alias from the shared
+    # alias_counter. Register all N columns so the target expressions
+    # below can reference any of them.
+    # CONSTRAINT: the recursive arm is the ONLY place a CteRef to
+    # `cte_name` may appear inside this WITH entry. The base arm
+    # would treat the name as undefined (it's registered after the
+    # base arm builds); the outer query treats it as a normal CTE
+    # reference. PG enforces this same single-arm-recursive rule at
+    # parse time.
+    self_alias = f"t{ctx.alias_counter.take()}"
+    self_ref = CteRef(cte_name=cte_name, alias=self_alias)
+    self_columns = [
+        (f"c{i + 1}", t) for i, t in enumerate(target_types)
+    ]
+    ctx.scope.add_derived(self_alias, self_columns)
+
+    # Optionally add a base-table FROM item alongside the CteRef
+    # — the canonical recursive pattern is `r JOIN base ON r.x =
+    # base.parent` for graph walks. Comma-join with one base table.
+    from_items: list[FromItem] = [self_ref]
+    if rng.random() < 0.7:
+        base_table = rng.choice(ctx.schema.tables)
+        base_alias = f"t{ctx.alias_counter.take()}"
+        ctx.scope.add_table(base_alias, base_table)
+        from_items.append(TableRef(base_table.name, base_alias))
+
+    # Targets: each cN references self.cN. This guarantees positional
+    # type-match between the two arms, which is what UNION ALL
+    # requires. Adding arithmetic ("advance" patterns like `r.c1 + 1`)
+    # is more realistic but more bookkeeping; deferred.
+    targets = tuple(
+        SelectTarget(
+            expr=ColumnRef(t, self_alias, f"c{i + 1}"),
+            alias=f"c{i + 1}",
+        )
+        for i, t in enumerate(target_types)
+    )
+
+    # Termination predicate on self.c1. Bounding any one column is
+    # sufficient to terminate the recursion in our generator (since
+    # recursive arms just project self-columns; without this the WITH
+    # would be an infinite empty loop in PG's planner model).
+    where: Expr = BinaryOp(
+        BOOL, "<",
+        ColumnRef(target_types[0], self_alias, "c1"),
+        _typed_terminator_literal(target_types[0]),
+    )
+
+    return Select(
+        targets=targets,
+        from_=tuple(from_items),
+        where=where,
+    )
+
+
+def _typed_terminator_literal(t: PgType) -> Literal:
+    """Return a Literal of `t` that's plausibly a recursion-terminator
+    bound. Numeric types get a "moderate" upper bound; text gets a
+    string. Used as the RHS of the recursive arm's WHERE predicate."""
+    if t in (INT4, INT8):
+        return Literal(t, 1000)
+    if t == NUMERIC:
+        return Literal(t, 1000.0)
+    if t == TEXT:
+        return Literal(t, "zzz")
+    if t == TIMESTAMPTZ:
+        return Literal(t, "2024-12-31 00:00:00+00")
+    # Defensive fallback: target_types[0] is drawn from
+    # _RECURSIVE_COLUMN_TYPES which is currently a strict subset of
+    # the cases above, so this branch is unreachable. Kept as a
+    # tripwire — if the pool ever expands, the WHERE predicate will
+    # become `c1 < NULL` (always FALSE / unknown), which terminates
+    # the recursion immediately rather than producing invalid SQL.
+    return Literal(t, None)
+
+
+__all__ = ["gen_cte_def", "gen_recursive_cte_def"]

waxsql/gen/data/__init__.py

@@ -0,0 +1,14 @@
+"""Internal package for the data generator.
+
+Public entry point is `waxsql.data.generate_data`. Submodules:
+- strategies: per-type value generators
+- columns:    column-name override registry (hook for future plausibility)
+- rows:       topological row materialization + FK resolution
+- emit:       COPY block formatting
+
+Role: every module in this package is internal. Callers should import
+through `waxsql.data` (or the top-level `waxsql.generate_data` re-export);
+the layout here may change without notice. The split exists so each
+concern (type-keyed values, name-keyed overrides, FK ordering, COPY
+encoding) lives in one file with one set of invariants.
+"""

waxsql/gen/data/columns.py

@@ -0,0 +1,48 @@
+"""Column-name override registry.
+
+This is a hook for the eventual 'column named email actually has emails'
+story. Today the registry is nearly empty and `strategy_for` falls
+through to the type strategy in nearly every case. The registry is a
+tuple (not a dict) because order matters — first match wins — and
+because tuple iteration is deterministic across Python versions.
+
+Role in the system: `strategy_for(col)` is the single per-column
+dispatch point used by `rows.generate_row`. Centralizing the lookup
+here means future semantic plausibility (emails, names, URLs, etc.)
+can grow inside this module without touching the row materializer or
+the type-strategy registry.
+"""
+from __future__ import annotations
+
+import re
+
+from waxsql.gen.data.strategies import Strategy, strategy_for_type
+from waxsql.schema import Column
+
+
+# Tuple of (compiled-pattern, strategy). First match wins. Empty today —
+# this is the seam for future semantic plausibility. Adding an entry
+# here doesn't require schema changes; the dispatch happens per column
+# at row-generation time.
+#
+# Why a tuple of (pattern, strategy) pairs and not a dict of name → strategy:
+# (1) ordering matters when patterns can overlap (e.g. `email_verified_at`
+# should match a timestamp pattern, not the email pattern), and tuple
+# iteration order is part of the source; (2) regex matching against
+# every column name avoids exact-name brittleness.
+_NAME_PATTERNS: tuple[tuple[re.Pattern, Strategy], ...] = ()
+
+
+def strategy_for(column: Column) -> Strategy:
+    """Return the strategy to use for `column`. Patterns are consulted
+    in order; the first one that matches the column name wins. Falls
+    through to `strategy_for_type(column.type)` when nothing matches.
+
+    Today this almost always falls through to the type strategy —
+    plausibility is type-driven, the name-override seam is intentionally
+    underused. The fallthrough is the common case, not an error path.
+    """
+    for pat, strat in _NAME_PATTERNS:
+        if pat.search(column.name):
+            return strat
+    return strategy_for_type(column.type)

waxsql/gen/data/emit.py

@@ -0,0 +1,247 @@
+"""COPY block formatting.
+
+PostgreSQL's text-format COPY uses tab as the column separator, `\\N`
+as the NULL sentinel, and backslash-escapes for tab, newline, carriage
+return, and backslash itself. This module owns all of that; strategies
+return native Python values and the emitter formats them.
+
+Role in the system: this is the bottom of the value-rendering stack.
+Everything above it (strategies, row materializer) traffics in native
+Python objects; nothing above this module knows anything about tab
+encoding, NULL sentinels, COPY framing, or PG array literal syntax.
+That separation lets the strategy registry stay trivially testable
+(no string round-trips needed to compare values).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import uuid
+from decimal import Decimal
+from collections.abc import Iterable, Sequence
+
+
+# PG text-format COPY: the literal two-character sequence `\N` (backslash-N)
+# in an unescaped position is the NULL marker. Raw string so the backslash
+# stays a backslash — not an escape introducer for Python.
+NULL_SENTINEL = r"\N"
+
+# COPY text-format escape rules. Order matters: backslash MUST come
+# first so we don't double-escape escapes we just inserted. If `\t`
+# came first, the subsequent backslash pass would turn the `\` in
+# `\t` into `\\`, producing `\\t` instead of the intended `\t`.
+_ESCAPES: tuple[tuple[str, str], ...] = (
+    ("\\", r"\\"),
+    ("\t", r"\t"),
+    ("\n", r"\n"),
+    ("\r", r"\r"),
+)
+
+
+def _escape_text(s: str) -> str:
+    # Linear pass through the ordered _ESCAPES table. str.replace is
+    # already optimized in CPython; rolling our own char-by-char loop
+    # would be slower and no clearer.
+    for raw, escaped in _ESCAPES:
+        s = s.replace(raw, escaped)
+    return s
+
+
+def encode_value(v: object) -> str:
+    """Encode a Python value for PG's text-format COPY.
+
+    Returns the COPY representation of `v`. NULL is represented by
+    `\\N`; bools as `t`/`f`; datetimes/dates as ISO-8601 (with `+00:00`
+    suffix for timestamptz); intervals as ISO-8601 duration; dicts as
+    compact JSON; lists as PG array literals.
+
+    Dispatch ORDER is load-bearing — see the bool-before-int note below
+    and the str-after-everything note for the array element path.
+    """
+    if v is None:
+        return NULL_SENTINEL
+    if isinstance(v, bool):
+        # bool MUST come before int — bool is a subclass of int in
+        # Python (isinstance(True, int) is True), so an earlier int
+        # branch would swallow booleans and emit them as "1"/"0".
+        return "t" if v else "f"
+    if isinstance(v, (int, float)):
+        return str(v)
+    if isinstance(v, Decimal):
+        # Decimal __str__ is canonical (no trailing zeros stripping, no
+        # scientific notation for reasonable values); PG numeric parses
+        # it directly.
+        return str(v)
+    if isinstance(v, uuid.UUID):
+        return str(v)
+    if isinstance(v, _dt.datetime):
+        # str() on tz-aware datetime gives "YYYY-MM-DD HH:MM:SS+HH:MM"
+        # which is what PG accepts for timestamptz literals.
+        # Note: the date branch below is reached only by naïve `date`
+        # values — datetime is a subclass of date, so this branch
+        # MUST come before the date branch.
+        return str(v)
+    if isinstance(v, _dt.date):
+        return v.isoformat()
+    if isinstance(v, _dt.timedelta):
+        # ISO-8601 duration: PnDTnS. Limited to days/seconds because
+        # timedelta doesn't carry month/year parts. PG accepts this.
+        # If we ever need year/month resolution we'll have to leave
+        # timedelta behind for a richer carrier type.
+        days = v.days
+        seconds = v.seconds
+        return f"P{days}DT{seconds}S"
+    if isinstance(v, dict):
+        # Compact JSON (no spaces) keeps COPY output narrow and matches
+        # what PG emits for jsonb on dump. separators kwarg is required;
+        # the default json.dumps inserts ", " and ": " padding.
+        #
+        # The result is then run through `_escape_text` because
+        # json.dumps emits backslash-escape sequences (`\t`, `\n`, `\"`,
+        # `\uXXXX`) for control chars, quotes, and non-ASCII. Those
+        # backslashes mean nothing to JSON's *reader* (it resolves
+        # them) but everything to COPY's *reader* (which uses
+        # backslash as its own escape introducer). Without
+        # re-escaping, a JSON value containing e.g. an embedded tab
+        # would arrive at PG with the `\` already consumed by COPY,
+        # leaving invalid JSON for jsonb_in. _escape_text doubles
+        # every `\` so COPY resolves them back to single `\` before
+        # handing the JSON to PG.
+        # allow_nan=False: inf/nan would serialize as Infinity/NaN, which
+        # jsonb_in rejects. Fail at generation time, not COPY-load time.
+        return _escape_text(json.dumps(v, separators=(",", ":"), allow_nan=False))
+    if isinstance(v, list):
+        # PG text-format array literal: `{elem,elem,...}`. Per-element
+        # formatting goes through `_array_element`, which knows the
+        # two-layer escape rules required for strings/dicts inside an
+        # array literal that itself sits inside a COPY cell.
+        return "{" + ",".join(_array_element(e) for e in v) + "}"
+    if isinstance(v, str):
+        return _escape_text(v)
+    raise TypeError(f"no COPY encoder for type {type(v).__name__}: {v!r}")
+
+
+def _array_element(v: object) -> str:
+    """Format a single element for inclusion in a PG array literal.
+
+    A PG array literal lives INSIDE a COPY cell, so two parsing
+    layers apply to its bytes:
+
+      1. PG's COPY row reader resolves row-format escapes first
+         (`\\\\`, `\\t`, `\\n`, `\\r`).
+      2. PG's array_in then parses the resolved cell text, with
+         its own escape grammar for quoted elements: `\\\\` resolves
+         to `\\`, `\\"` resolves to `"`. (Note: array_in does NOT
+         recognize `\\t`/`\\n`/`\\r` — anywhere it sees a literal
+         tab/newline/CR inside a quoted element, it just keeps
+         the character as part of the string.)
+
+    String and dict elements need BOTH escape passes; numeric/bool/
+    datetime elements need NEITHER (PG's array_in accepts them
+    unquoted via the element type's own input function). Lists
+    recurse for multidimensional arrays — they do NOT get quoted,
+    because PG's array literal supports `{{1,2},{3,4}}` directly.
+
+    None becomes the bare token `NULL` (case-insensitive), NOT the
+    row-level `\\N` sentinel — inside a `{...}` literal, `\\N`
+    is interpreted as the two-character string `\\N`, not SQL NULL.
+    """
+    if v is None:
+        # Bare unquoted token: PG's array_in treats this as SQL NULL.
+        # The row-level `\N` sentinel would be misread as the literal
+        # 2-char string, not NULL — a silent data corruption.
+        return "NULL"
+    if isinstance(v, list):
+        # Multidimensional array: emit the inner `{...}` literal
+        # WITHOUT quoting, so the outer array_in sees it as a
+        # sub-array, not a string element. Today `array_of(array_of(
+        # ...))` isn't constructible by the data generator, but the
+        # path is correct for the eventual extension.
+        return encode_value(v)
+    if isinstance(v, dict):
+        # Array-of-jsonb: each element is a JSON-encoded value
+        # wrapped as a quoted array-element. PG's array_in extracts
+        # the quoted content (resolving its escapes) and hands the
+        # resulting JSON text to jsonb_in for parsing. Two-layer
+        # escape handles backslashes from JSON's own escapes plus
+        # the quote-and-escape required by the array element format.
+        return _quote_array_element(json.dumps(v, separators=(",", ":"), allow_nan=False))
+    if isinstance(v, str):
+        return _quote_array_element(v)
+    # Scalar non-string types (int, float, bool, Decimal, UUID,
+    # datetime, date, timedelta): PG's array_in accepts these as
+    # unquoted tokens — quoting would actually be wrong here,
+    # because array_in would then call the element type's input
+    # function on a *string* form rather than the bare token.
+    return encode_value(v)
+
+
+def _quote_array_element(s: str) -> str:
+    """Quote-and-escape a string for use as a PG array literal element.
+
+    Encodes in REVERSE order of how PG's parsers resolve the bytes:
+    array_in's escapes are applied FIRST in our code (because they
+    resolve LAST when PG reads), then COPY's escapes are applied
+    LAST in our code (because they resolve FIRST when PG reads).
+
+    Concretely:
+
+      * Step 1 (array_in escapes): `\\\\` → `\\\\\\\\` (one backslash
+        becomes two), `"` → `\\"` (one quote becomes backslash-quote).
+        These are the only escapes array_in recognizes inside a
+        double-quoted element.
+
+      * Step 2 (COPY escapes via `_escape_text`): re-escapes every
+        backslash (so each `\\\\` from step 1 becomes `\\\\\\\\`,
+        and any pre-existing literal backslash gets doubled) AND
+        backslash-escapes tab/newline/CR characters in the source
+        (so they don't terminate the COPY cell prematurely on
+        reading; once resolved by COPY they become literal
+        whitespace inside the quoted element, which array_in
+        keeps verbatim).
+
+    Composition example: a source `\\` (one backslash) → step 1
+    → `\\\\` (two) → step 2 → `\\\\\\\\` (four) → wrapped in `"..."`.
+    PG resolution: COPY reads four backslashes → resolves to two
+    → array_in reads two backslashes → resolves to one. Round-trip
+    preserves the original character.
+    """
+    arr_escaped = s.replace("\\", "\\\\").replace('"', '\\"')
+    copy_escaped = _escape_text(arr_escaped)
+    return '"' + copy_escaped + '"'
+
+
+def emit_copy_block(
+    table_name: str,
+    columns: Sequence[str],
+    rows: Iterable[Sequence[object]],
+) -> str:
+    """Format one COPY block.
+
+    Output shape:
+        COPY "table" ("col1", "col2") FROM STDIN;
+        v11<TAB>v12
+        v21<TAB>v22
+        \\.
+
+    Identifiers are double-quoted to handle case-sensitivity and
+    reserved-word collisions uniformly. PG accepts quoted identifiers
+    that happen not to need quoting, so the extra punctuation is harmless.
+
+    The empty-rows case (no row tuples) is intentionally legal: it
+    produces `COPY ... FROM STDIN;\\n\\.\\n` — header immediately
+    followed by terminator. psql and psycopg both accept this; the
+    `waxsql gen --rows=0` flag relies on it.
+    """
+    col_list = ", ".join(f'"{c}"' for c in columns)
+    # Build via parts + join: O(n) regardless of row count, vs O(n^2)
+    # for repeated string += concatenation.
+    parts = [f'COPY "{table_name}" ({col_list}) FROM STDIN;\n']
+    for row in rows:
+        parts.append("\t".join(encode_value(v) for v in row))
+        parts.append("\n")
+    # PG COPY text-format end-of-data sentinel: a line containing only
+    # `\.` (the same literal sequence used in psql). Followed by a
+    # newline so concatenated blocks separate cleanly.
+    parts.append("\\.\n")
+    return "".join(parts)