jade-sql 0.7.0 → 0.9.0

data/docs/building.md

@@ -1,7 +1,7 @@
 # Building SQL
 
 Generate a typed schema from your database, then build queries and
-mutations against it. To run what you build, see [running.md](running.md).
+writes against it. To run what you build, see [running.md](running.md).
 
 ## Generate `schema.jd` from `db/structure.sql`
 
@@ -31,12 +31,36 @@ Type map: `bigint`/`integer`/`smallint` → `Int`, `numeric`/`decimal` →
 `Decimal` (jade's stdlib exact decimal), `double precision`/`real` →
 `Float`, `varchar`/`text`/`char` → `String`, `boolean` → `Bool`,
 `jsonb`/`json` → `Decode.Value`, `date` → `Calendar.Date`, `timestamp` →
-`Clock.Instant`, `uuid` → `Uuid` (from `Sql.Uuid`). Unknown types fail
-loudly with the table+column name.
+`Clock.Instant`, `uuid` → `Uuid` (from `Sql.Uuid`), `citext`/`inet`/`cidr`/
+`macaddr` → `String`. Unknown types fail loudly with the table+column name.
+
+A `citext` column compares case-insensitively, and its Jade type does not say
+so — `Expr(String)` is what an ordinary `text` column gets too. That is the
+database's own opacity rather than something the schema drops: nothing in a
+query tells you either. It matters in one place. `where(c.email |> eq(input))`
+is case-insensitive, because Postgres does the comparing; the same comparison
+written in Jade over a fetched row is not. Compare in the query, or fold the
+case yourself once it has left.
 
 `numeric`/`decimal` map to the stdlib `Decimal` — an exact base-10 value
 (`coefficient * 10^exponent`), never `Float`, so no precision is lost.
 Genuine floating-point columns (`double precision`/`real`) map to `Float`.
+A `CREATE TYPE … AS ENUM` becomes a union, and its columns are typed by it:
+
+```jade
+-- CREATE TYPE visit_status AS ENUM ('scheduled', 'in_progress', 'done');
+
+type VisitStatus
+  = Scheduled
+  | InProgress
+  | Done
+```
+
+Nullary unions derive `Encodable` and `Decodable` with the variant name in
+snake_case, which is the label Postgres stores — so the codec is free and
+`eq(v.status, "schedulled")` stops compiling. Before this, an enum
+column failed generation outright with `Unknown SQL type`.
+
 `bytea` isn't mapped yet, though jade's `Bytes` is the natural target. See
 jade-lang's `Decimal` for the full API (`of`/`scaled`/`parse`, arithmetic,
 `round`, `to_i`/`to_float`).
@@ -45,18 +69,103 @@ For each table, the generator emits:
 
 ```jade
 struct PatientsCols      = { id: Expr(Int), name: Expr(String), ... }
-struct MaybePatientsCols = { id: Expr(Maybe(Int)), name: Expr(Maybe(String)), ... }
+struct PatientsLeftCols = { id: Expr(Maybe(Int)), name: Expr(Maybe(String)), ... }
 struct PatientsRow       = { id: Int, name: String, ... }
 
-def patients -> Table(PatientsCols, MaybePatientsCols)
+def patients -> Table(PatientsCols, PatientsLeftCols)
   table("patients", "patients", ..., ["id"])
 end
+
+def patients_pk -> Pk(PatientsCols, Int)
+  pk("pkey", ["id"], patients_pk_values)
+end
 ```
 
 Strict cols mirror NOT NULL constraints; the maybe version wraps every
 field in `Maybe` for left-join projections. The default alias is the
 table name; override per-call with `aliased` (see joins below).
 
+Every unique index becomes a name too, from both spellings: a table-level
+`UNIQUE (...)` and a standalone `CREATE UNIQUE INDEX`.
+
+```jade
+def users_email_key -> Unique(UsersCols)
+  unique("users_email_key", ["email"])
+end
+```
+
+`matching` builds the predicate for a read by that index, and the key type
+comes from the index, so a composite cannot be given in the wrong order:
+
+```jade
+where(matching(users_email_key, "ada@example.com"))
+# WHERE email = ?
+
+where(matching(users_tenant_email_key, (7, "ada@example.com")))
+# WHERE tenant_id = ? AND email = ?
+```
+
+Pair it with `Sql.Query.fetch_at_most_one`, which takes no row as an answer
+rather than an error. More than one is still `TooManyRows`: nothing is dropped
+to make the type fit, and the index is what makes that case unreachable.
+
+`UniqueViolation` carries the constraint name Postgres reports, so a write
+routes its own failure:
+
+```jade
+case err
+in UniqueViolation(i) then i == users_email_key.name ? EmailTaken : Other
+end
+```
+
+Rename the index, regenerate, and the call site stops compiling rather than
+quietly never matching again, which is what a string literal there would do. `Unique(c)` is phantom in the column struct, so
+an index cannot be used with a table it is not on.
+
+A partial index is skipped: it constrains only the rows its `WHERE` matches,
+so a conflict target built from it is not the one the database enforces.
+
+`patients_pk` names the table's primary key. `Pk(c, k)` is phantom in the
+column struct, so a key can only be used with the table it came from, and
+carries the key's own type — `Int` here, a tuple for a composite key,
+which a generated helper spreads across its columns in DDL order. A table
+with no `PRIMARY KEY` in `structure.sql` gets no `_pk` and is keyed by
+`NoKey`, which has no constructor you can reach — so `update` and `delete`
+are unavailable on it, and `update_all`/`delete_all` are how you write to it.
+
+Every foreign key in `structure.sql` becomes a field on the table's `on`
+record, from both ends — one constraint, two ways to read it:
+
+```jade
+p  <- from(patients)
+a  <- join(appointments, p |> patients.on.appointments)
+ph <- left_join(phones, p |> patients.on.phone)
+```
+
+`join` never sees the left side — it builds a query the bind chain composes —
+so the predicate it takes is a function of the joined table's columns alone.
+Each field on the `on` record takes the parent columns and returns exactly
+that, which is why the parent goes in by pipe and the child is left to `join`.
+
+The result is an ordinary predicate function, the same thing a hand-written
+`(ph) -> { ... }` is, so extra conditions compose:
+
+```jade
+ph <- left_join(phones, (ph) -> {
+  ph |> (p |> patients.on.phone) |> and(ph.deleted_at |> is_null)
+})
+```
+
+On a left join that distinction matters: the same condition in `where` would
+drop the parent row instead of nulling the child.
+
+An outgoing key is named after its column minus `_id`, an incoming one after
+the table it comes from, and a second key between the same pair keeps its
+column name to stay distinct. A nullable foreign key column is
+`Expr(Maybe(a))` while the key it points at is `Expr(a)`, so the generated
+predicate lifts whichever side is not nullable. A table with no foreign keys
+carries `NoJoins`.
+
 A column whose name is a Jade keyword (e.g. `type`) gets a trailing
 underscore in the struct field (`type_`) while the SQL column reference
 keeps the real name. For a table with such a column the generator also
@@ -64,7 +173,7 @@ emits a `<table>_row` projector that aliases every column to its field name
 (`SELECT … AS type_`), so reads round-trip without hand-written SQL:
 
 ```jade
-def entries -> Q(Selector(JournalEntriesRow))
+def entries -> Select(JournalEntriesRow)
   c <- from(journal_entries)
   journal_entries_row(c)
 end
@@ -78,8 +187,8 @@ makes a `COUNT(*)` land in a `visits` field).
 ## Build queries
 
 ```jade
-import Sql exposing (Selector, eq, to_expr)
-import Sql.Query exposing (Q, field, from, join, select, where)
+import Sql exposing (Selector, eq)
+import Sql.Query exposing (Query, field, from, join, select, where)
 import Schema exposing (patients, appointments)
 
 struct Visit = {
@@ -87,14 +196,14 @@ struct Visit = {
   reason: String
 }
 
-def scheduled_visits -> Q(Selector(Visit))
+def scheduled_visits -> Select(Visit)
   p <- from(patients)
-  a <- join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+  a <- join(appointments, (a) -> { p.id |> Expr.eq(a.patient_id) })
 
   select(Visit(_, _))
     |> field(p.name)
     |> field(a.reason)
-    |> where(a.status |> eq(to_expr("scheduled")))
+    |> where(a.status |> eq("scheduled"))
 end
 ```
 
@@ -107,20 +216,26 @@ Notes:
 
 ### Predicates
 
-`eq`, `gt`, `gte`, `lt`, `lte` compare two `Expr(a)` and yield `Expr(Bool)`;
-`is_null` / `is_not_null` take one; `and` joins two; `in_` matches a list.
-`now` is the DB clock (`now()`), for time comparisons:
+`eq`, `neq`, `gt`, `gte`, `lt`, `lte` compare a column against a value you
+hold and yield `Expr(Bool)`; `is_null` / `is_not_null` take one; `and` joins
+two; `any_of` matches a list. `db_now` is the database clock (`now()`), for
+time comparisons.
+
+To compare against something already built instead of a value, the same names
+live in `Sql.Expr`:
 
 ```jade
-import Sql exposing (column, gt, now, to_expr)
+import Sql exposing (db_now, gte)
+import Sql.Expr as Expr
 
-a.starts_at |> gte(to_expr(cutoff))          # a.starts_at >= ?
-column("s", "expires_at") |> gt(now)         # s.expires_at > now()
+a.starts_at |> gte(cutoff)             # a.starts_at >= ?
+a.starts_at |> Expr.gte(a.ends_at)     # a.starts_at >= a.ends_at
+s.expires_at |> Expr.gt(db_now)        # s.expires_at > now()
 ```
 
-`now` is `Expr(Instant)` — the *DB* transaction clock, not the app clock.
+`db_now` is `Expr(Instant)` — the *DB* transaction clock, not the app clock.
 It's the right tool for `WHERE` filters; for `created_at`/`updated_at` use
-`Sql.Mutation.timestamped` (below), which uses the app clock like Rails.
+`Sql.Write.timestamped` (below), which uses the app clock like Rails.
 
 ### Sorting and grouping
 
@@ -129,7 +244,7 @@ It's the right tool for `WHERE` filters; for `created_at`/`updated_at` use
 order — e.g. counting visits per patient, busiest first:
 
 ```jade
-import Sql exposing (column, count_all)
+import Sql exposing (count_all)
 import Sql.Query exposing (group, order, order_desc)
 
 struct VisitCount = {
@@ -137,23 +252,52 @@ struct VisitCount = {
   visits: Int
 }
 
-def visit_counts -> Q(Selector(VisitCount))
+def visit_counts -> Select(VisitCount)
   p <- from(patients)
-  a <- join(appointments, (a) -> { p.id |> eq(a.patient_id) })
+  a <- join(appointments, (a) -> { p.id |> Expr.eq(a.patient_id) })
 
   select(VisitCount(_, _))
     |> field(p.name)
     |> field(count_all)
-    |> group(column("p", "name"))
+    |> group(p.name)
     |> order_desc(count_all)
-    |> order(column("p", "name"))
+    |> order(p.name)
 end
 # ... GROUP BY p.name ORDER BY COUNT(*) DESC, p.name
 ```
 
-`HAVING` and `CASE` aren't built in yet — for filtering aggregates or
-conditional expressions, fall back to the raw-SQL escape hatch
-(`execute_*`). Basic aggregates (`SUM`, `COUNT`) and the
+`having(q, predicate)` filters on an aggregate, after `group` has collapsed
+the rows. `where` cannot: it runs before the grouping, so `count_all` has
+nothing to count yet.
+
+```jade
+select(Busy(_))
+  |> field(v.patient_id)
+  |> group(v.patient_id)
+  |> having(count_all |> gt(3))
+# ... GROUP BY v.patient_id HAVING COUNT(*) > ?
+```
+
+`distinct(q)` drops duplicate rows from the whole projected row, which is
+`SELECT DISTINCT` rather than Postgres' `DISTINCT ON`.
+
+`exists(q)` asks whether a related row is there, without joining to it and
+without projecting anything from it; `not(exists(q))` is the negative. The inner query may
+name the outer query's columns, which is what makes it correlated:
+
+```jade
+p <- from(patients)
+
+select(Name(_))
+  |> field(p.name)
+  |> where(exists(from(visits) |> filter((v) -> { v.patient_id |> Expr.eq(p.id) })))
+# ... WHERE EXISTS (SELECT 1 FROM visits v WHERE v.patient_id = p.id)
+```
+
+They take an unprojected `Query`, since `EXISTS` ignores the select list.
+
+`CASE` is not built in — for conditional expressions, fall back to the raw-SQL
+escape hatch (`execute_*`). Basic aggregates (`SUM`, `COUNT`) and the
 null-handling primitive (`coalesce`) are typed; see *Aggregates,
 COALESCE* below.
 
@@ -166,7 +310,7 @@ returned `List(Value)` is unaffected:
 ```jade
 import Sql.Query exposing(limit, offset)
 
-def page(n: Int) -> Q(Selector(Visit))
+def page(n: Int) -> Select(Visit)
   scheduled_visits
     |> limit(20)
     |> offset(n * 20)
@@ -182,7 +326,7 @@ The schema's default alias = table name. Override with `aliased`:
 
 ```jade
 p <- from(patients)
-c <- patients |> aliased("c") |> join((c) -> { p.id |> eq(c.parent_id) })
+c <- patients |> aliased("c") |> join((c) -> { p.id |> Expr.eq(c.parent_id) })
 ```
 
 ### Left joins with nullable views
@@ -191,20 +335,20 @@ c <- patients |> aliased("c") |> join((c) -> { p.id |> eq(c.parent_id) })
 
 ```jade
 p <- from(patients)
-a <- left_join(appointments, (a) -> { p.id |> eq(a.patient_id) })
-# `a` is MaybeAppointmentsCols; field types are Expr(Maybe(String)) etc.
+a <- left_join(appointments, (a) -> { p.id |> Expr.eq(a.patient_id) })
+# `a` is AppointmentsLeftCols; field types are Expr(Maybe(String)) etc.
 ```
 
 For predicates that lift a non-null column into the nullable side,
 `nullable`:
 
 ```jade
-p.id |> nullable |> eq(a.patient_id)  # Expr(Int) → Expr(Maybe(Int))
+p.id |> nullable |> Expr.eq(a.patient_id)  # Expr(Int) → Expr(Maybe(Int))
 ```
 
-### Phantom-type rewrap with `cast`
+### Phantom-type rewrap with `unsafe_cast`
 
-`cast(e: Expr(a)) -> Expr(b)` widens a column's phantom type — useful
+`unsafe_cast(e: Expr(a)) -> Expr(b)` widens a column's phantom type — useful
 for projecting a `VARCHAR` column into a typed enum field whose
 `Decodable(b)` instance does the actual parsing at row decode:
 
@@ -215,12 +359,12 @@ struct Appointment = { id: Int, status: Status, ... }
 # "scheduled" / "completed" into the variants.
 select(Appointment(_, _, ...))
   |> field(a.id)
-  |> field(a.status |> cast)   # Expr(String) → Expr(Status)
+  |> field(a.status |> unsafe_cast)   # Expr(String) → Expr(Status)
 ```
 
 Same shape as `nullable` — pure phantom-type rewrap, no runtime
 transformation. The runtime decoder (`Decodable(Status)`) is what
-actually converts the column value; `cast` just teaches the SQL
+actually converts the column value; `unsafe_cast` just teaches the SQL
 builder that the projection is intended. If `Decodable(b)` can't
 parse the column's actual values, the failure surfaces at row
 decode time, not at type check.
@@ -236,24 +380,78 @@ builder — params stitch in declaration order automatically.
 | `sum(Expr(Int)) -> Expr(Maybe(Int))`           | `SUM(e)`           | `NULL` on empty group → `Maybe`.       |
 | `count(Expr(a)) -> Expr(Int)`                  | `COUNT(e)`         | Counts non-null rows for the column.   |
 | `count_all -> Expr(Int)`                       | `COUNT(*)`         | Total row count.                       |
-| `coalesce(Expr(Maybe(a)), Expr(a)) -> Expr(a)` | `COALESCE(e, def)` | Drops the `Maybe` with a fallback.     |
+| `coalesce(Expr(Maybe(a)), a) -> Expr(a)`       | `COALESCE(e, ?)`   | Drops the `Maybe` with a fallback.     |
 | `neg(Expr(Int)) -> Expr(Int)`                  | `-(e)`             | Unary minus.                           |
 
 Worked example — count visits and the most recent visit number,
 coalesced to 0 when a patient has none:
 
 ```jade
-import Sql exposing (coalesce, column, count_all, sum, to_expr)
+import Sql exposing (coalesce, count_all, sum)
 
-select(Totals(_, _))
-  |> field(count_all)
-  |> field(coalesce(sum(column("a", "visit_no")), to_expr(0)))
-# SELECT COUNT(*), COALESCE(SUM(a.visit_no), ?)
+def totals -> Select(Totals)
+  a <- from(appointments)
+
+  select(Totals(_, _))
+    |> field(count_all)
+    |> field(coalesce(sum(a.visit_no), 0))
+end
+# SELECT COUNT(*), COALESCE(SUM(a.visit_no), ?) FROM appointments a
 ```
 
-For `CASE WHEN`, `HAVING`, and arithmetic, fall back to the raw-`Expr`
+For `CASE WHEN` and arithmetic, fall back to the raw-`Expr`
 escape hatch until they get a typed builder.
 
+### Subqueries
+
+`exists` asks whether a related row is there, `subquery` reads a single value
+out of one, and `in_subquery` matches a column against one a subquery selects.
+All three take an unprojected `Query`.
+
+Each is named for the SQL it renders. There is no `not_in`: `NOT IN` against a
+subquery yielding a NULL returns no rows at all, so `not(exists(q))` is the
+form to reach for.
+
+```jade
+import Sql.Query exposing (
+  from,
+  in_subquery,
+  limit,
+  order_desc,
+  subquery,
+  where,
+)
+
+def latest(p: PatientsCols) -> Query(VisitsCols)
+  v <- from(visits)
+
+  from(visits)
+    |> where(v.patient_id |> Expr.eq(p.id))
+    |> order_desc(v.seen_on)
+    |> limit(1)
+end
+
+select(Row(_, _))
+  |> field(p.id)
+  |> field(subquery(latest(p), .seen_on))
+# SELECT p.id, (SELECT v.seen_on FROM visits v WHERE v.patient_id = p.id
+#               ORDER BY v.seen_on DESC LIMIT 1) FROM patients p
+
+where(p.id |> in_subquery(from(visits), .patient_id))
+# WHERE p.id IN (SELECT v.patient_id FROM visits v)
+```
+
+A subquery starts with `from(t)`, the same as any other query, and carries the
+table's columns rather than a projection. Naming the table again is what makes
+the subquery stand on its own: one that borrowed the outer query's columns
+would render without a `FROM` and read the outer table instead, which is legal
+SQL asking a different question. Naming a table the chain already bound costs
+nothing, since a table is listed once however many times it is named. The
+column is picked by a function rather than projected, because
+`Select(a)` does not say how many columns it has, and a subquery in a value
+position may only have one. `subquery` returns `Expr(Maybe(a))`, since a
+subquery matching no rows is NULL.
+
 ### Postgres arrays
 
 Typed predicates on `text[]` / `int[]` / `uuid[]` columns. All bind
@@ -272,21 +470,28 @@ the other side of the operator. No `ARRAY[$1,...,$N]` expansion, no
 
 Example — filter appointments whose tag set overlaps any selected chip:
 
+A predicate written outside a bind chain has no accessors in scope, so take
+them as an argument and hand it to `filter`, which supplies them:
+
 ```jade
-import Sql exposing (array_overlaps, column)
+import Sql exposing (array_overlaps)
+import Sql.Query exposing (filter, from)
 
-def filter_by_tags(selected: List(String)) -> Expr(Bool)
-  array_overlaps(column("a", "tags"), selected)
+def tagged(selected: List(String)) -> (AppointmentsCols -> Expr(Bool))
+  (a) -> { array_overlaps(a.tags, selected) }
 end
+
+
+from(appointments) |> filter(tagged(["urgent", "followup"]))
 # WHERE a.tags && ?    (param: ["urgent","followup"])
 ```
 
 `array_length` uses `cardinality(col)` rather than Postgres'
 `array_length(col, 1)` because `cardinality` is non-null (returns 0
 on empty). Filter untagged rows with
-`array_length(column("a", "tags")) |> eq(to_expr(0))`.
+`array_length(a.tags) |> eq(0)`.
 
-Mutation ops for partial array updates:
+Write ops for partial array updates:
 
 | Function                                                            | SQL                          |
 |---------------------------------------------------------------------|------------------------------|
@@ -294,13 +499,19 @@ Mutation ops for partial array updates:
 | `array_remove(Expr(List(a)), a) -> Expr(List(a))`                   | `array_remove(col, ?)`       |
 | `array_concat(Expr(List(a)), Expr(List(a))) -> Expr(List(a))`       | `left ‖ right`               |
 
+`update_all`'s builder receives two records: the column accessors, for
+expressions over the row, and the assignment-side accessors, for the left of a
+`SET`. The second yields `Col`, which carries the column's name, so `set` reads
+it rather than recovering it from rendered SQL — an aggregate or a `COALESCE`
+cannot be assigned to, and cannot be offered.
+
 Use these in `update_all` to avoid rewriting an array column wholesale:
 
 ```jade
 appointments
   |> update_all(
-       (a) -> { a.id |> eq(to_expr(aid)) },
-       (a) -> { [a.tags |> set_(array_append(a.tags, new_tag))] },
+       (a) -> { a.id |> eq(aid) },
+       (a, s) -> { [s.tags |> set_expr(array_append(a.tags, new_tag))] },
      )
 # UPDATE appointments SET tags = array_append(tags, ?) WHERE id = ?
 ```
@@ -312,70 +523,93 @@ Out of scope: `unnest`, `array_agg`. Add when a caller hits them.
 | Function                                                  | SQL                |
 |-----------------------------------------------------------|--------------------|
 | `jsonb_contains(Expr(Value), a) -> Expr(Bool)`            | `col @> ?`         |
-| `jsonb_path_exists(Expr(Value), String) -> Expr(Bool)`    | `col @? ?::jsonpath` |
+| `jsonb_path_exists(Expr(Value), String) -> Expr(Bool)`    | `jsonb_path_exists(col, ?)` |
 
 `jsonb_contains` auto-encodes the value via its `Encodable` instance,
 so you can pass any record / scalar / list directly:
 
 ```jade
-import Sql exposing (column, jsonb_contains, jsonb_path_exists)
+import Sql exposing (jsonb_contains, jsonb_path_exists)
 
 struct KindMatch = { kind: String }
 
 # WHERE r.meta @> ?       (param: { "kind": "referral" })
-def matches_kind(k: String) -> Expr(Bool)
-  jsonb_contains(column("r", "meta"), KindMatch(k))
+def matches_kind(k: String) -> (ReferralsCols -> Expr(Bool))
+  (r) -> { jsonb_contains(r.meta, KindMatch(k)) }
 end
 
-# WHERE r.meta @? ?::jsonpath   (param: "$.priority ? (@ > 1)")
-def has_priority_gt(path: String) -> Expr(Bool)
-  jsonb_path_exists(column("r", "meta"), path)
+
+# WHERE jsonb_path_exists(r.meta, ?)   (param: "$.priority ? (@ > 1)")
+def has_priority_gt(path: String) -> (ReferralsCols -> Expr(Bool))
+  (r) -> { jsonb_path_exists(r.meta, path) }
 end
 ```
 
-The `@?` operator requires `jsonpath` on the right; the param binds as
-text and gets cast at the SQL level.
+Postgres spells four of its jsonb operators with a `?` — `@?`, `?`, `?|` and
+`?&` — and the runtime rewrites every `?` outside a quoted span into a `$n`
+placeholder. It cannot tell an operator from a parameter, since `meta ? 'kind'`
+and `id = ?` are the same character in the same position. So `jsonb_path_exists`
+renders the function Postgres gives for `@?` rather than the operator: it holds
+no `?`, and its declared parameter type supplies the `jsonpath` the operator
+form needed a cast for. Anything added here later wants the same treatment.
 
-## Build mutations
+## Build writes
 
-Define codec interfaces for your domain type:
+One interface says which columns a value writes:
 
 ```jade
-import Sql exposing(Assignment, SqlMapper, Identified, assign)
-import Encode exposing(encode)
-import Decode exposing(Value)
+import Sql exposing(Assignment, Assignable, assign)
 
 struct Patient = { id: Int, name: String, mrn: String }
 
-implements SqlMapper(Patient) with
+implements Assignable(Patient) with
   to_assigns: encode_patient
 end
 
-implements Identified(Patient) with
-  pk_values: encode_patient_pk
-end
-
 def encode_patient(p: Patient) -> List(Assignment)
   [
+    assign("id",   p.id),
     assign("name", p.name),
     assign("mrn",  p.mrn)
   ]
 end
+```
 
-def encode_patient_pk(p: Patient) -> List(Value)
-  [encode(p.id)]
-end
+`Assignable` derives for any struct, so the `implements` block above is
+only needed when you want something other than one column per field.
+
+**The struct you pass is the columns you write.** `insert` writes every
+assignment. `update` and `delete` take the key as an argument, so what you
+write and which row you write it to stay separate:
+
+```jade
+struct NewPatient = { name: String, mrn: String }
+
+struct Rename = { name: String }
+
+NewPatient("Ada", "MRN-1") |> insert(patients)   # INSERT (name, mrn)
+Rename("Ada") |> update(patients, 7)             # SET name WHERE id = 7
+delete(patients, 7)                              # DELETE WHERE id = 7
 ```
 
+A patch needs no key field of its own, and a struct that does carry one —
+a whole row — has it stripped from the `SET`. Every write is either keyed
+or scoped: `update` and `delete` take a key, `update_all` and `delete_all`
+take a predicate, and there is no third form to land in with neither.
+
+The key is a `k`, never a column name and never an order, so a composite
+key cannot be listed the wrong way round — the generated values function
+spreads it across its columns as `structure.sql` declares them.
+
 `assign(col, value)` is shorthand for
 `Assignment(col, "?", [encode(value)])`. For non-`?` placeholders
 (e.g. `"visit_no + ?"` for increments) use the `Assignment(...)`
 constructor directly.
 
-Then the mutation API works on values directly:
+Then the write API works on values directly:
 
 ```jade
-import Sql.Mutation exposing(insert, update, delete, insert_all, update_all, delete_all, to_sql)
+import Sql.Write exposing(insert, update, delete, insert_all, update_all, delete_all, to_sql)
 
 p |> insert(patients) |> to_sql        # INSERT INTO patients (name, mrn) VALUES (?, ?)
 p |> update(patients) |> to_sql        # UPDATE patients SET name = ?, mrn = ? WHERE id = ?
@@ -384,33 +618,84 @@ p |> delete(patients) |> to_sql        # DELETE FROM patients WHERE id = ?
 [p1, p2] |> insert_all(patients) |> to_sql
 
 appointments
-|> update_all((a) -> { a.status |> eq(to_expr("scheduled")) },
-              (a) -> { [a.cancelled |> set_(to_expr(True))] })
+|> update_all((a) -> { a.status |> eq("scheduled") },
+              (a, s) -> { [s.cancelled |> set(True)] })
 |> to_sql
 
 appointments
-|> delete_all((a) -> { a.cancelled |> eq(to_expr(True)) })
+|> delete_all((a) -> { a.cancelled |> eq(True) })
 |> to_sql
 ```
 
+### Upserts
+
+`on_conflict` takes a `Unique` as the conflict target, so the index named is
+one the database has, and an action saying which of the two forms it is. The
+write already knows its table, so `do_update` receives the `SET` columns
+without being handed the table again:
+
+```jade
+import Sql exposing (set_excluded)
+import Sql.Write exposing (do_nothing, do_update, insert, on_conflict)
+
+NewUser("ada@example.com", "ada")
+  |> insert(users)
+  |> on_conflict(users_email_key, do_nothing)
+# INSERT INTO users AS users (email, handle) VALUES (?, ?) ON CONFLICT (email) DO NOTHING
+
+NewUser("ada@example.com", "ada")
+  |> insert(users)
+  |> on_conflict(users_email_key, do_update((s) -> { [set_excluded(s.handle)] }))
+# ... ON CONFLICT (email) DO UPDATE SET handle = EXCLUDED.handle
+```
+
+A primary key is a unique index like any other, so it is generated as one
+under the name the DDL gives it — which is what `upsert_all` targets:
+
+```jade
+row |> insert(users) |> on_conflict(users_pkey, do_update((s) -> { ... }))
+# ... ON CONFLICT (id) DO UPDATE SET ...
+```
+
+`val(v)` puts a value where an expression is wanted. The operators take
+values directly, so this is for the positions that cannot — a constant field
+in a projection or a JSON document:
+
+```jade
+select(Row(_, _)) |> field(c.id) |> field_as(val("patient"), "kind")
+# SELECT patients.id, ? AS kind FROM patients patients
+```
+
+It binds rather than inlining, so a string with a quote in it is a parameter
+and not a syntax error.
+
+`set_excluded(col)` renders `col = EXCLUDED.col`, which is what an upsert wants
+nearly every time. For anything else, `excluded(col)` is the proposed row's
+value as an ordinary `Expr`, so `set_expr(s.count_, excluded(s.count_))` and
+arithmetic over it compose as usual.
+
+The build receives the table's `SET` columns, which is why the table is passed
+again: a `Write` carries its columns aliased for the statement, and the left of
+a `SET` takes no alias.
+
 ### RETURNING
 
-`returning` is the mutation-side counterpart to `select` for queries.
-It takes a closure that receives the table's column accessors and
-builds a Q-wrapped selector projecting them into a target type. The
-Q wrapper is just to share the same `select`/`field` builders as
-queries — `returning` extracts the inner `Selector` and discards the
-empty Q state.
+`returning_with` names the columns coming back, from the table's accessors.
+It is a step of its own rather than something `fetch_one` does for you: a
+write has one type whether you run it for a count or for a row, so folding the
+projection into the runner would mean `execute` and `fetch_one` producing
+different SQL from the same `Write`.
 
 ```jade
 import Sql exposing(Selector)
 import Sql.Query exposing(select, field)
-import Sql.Mutation exposing(insert, returning, to_sql)
+import Sql.Write exposing(insert, returning_with, to_sql)
 
-# INSERT INTO patients (name, mrn) VALUES (?, ?) RETURNING id, name, mrn
+# INSERT INTO patients (name, mrn) VALUES (?, ?)
+#   RETURNING patients.id, patients.name, patients.mrn
 np
 |> insert(patients)
-|> returning((p) -> {
+|> returning_with((p) -> {
   select(Patient(_, _, _))
   |> field(p.id)
   |> field(p.name)
@@ -419,32 +704,37 @@ np
 |> to_sql                    # or |> fetch_one to run
 ```
 
-Bonus: the projector can be defined once and shared between SELECT
-queries and RETURNING — both contexts now take the same `cols ->
-Q(Selector(target))` shape, so a single `def patient_projector(p)`
-works for `from(patients) |> patient_projector` (query) and
-`... |> returning(patient_projector)` (RETURNING).
-
-Combined with `Sql.fetch_one`, the inserted row decodes into the
-target struct:
+A projection is a function of the columns, so it is written once and shared
+between a SELECT and a RETURNING — both take the same `cols -> Select(a)`
+shape:
 
 ```jade
-def create(np: NewPatient) -> Task(Patient, SqlError)
-  np |> insert(patients) |> returning((p) -> {
-    select(Patient(_, _, _))
-    |> field(p.id)
-    |> field(p.name)
-    |> field(p.mrn)
-  })
-  |> fetch_one
+def patient_row(p: PatientsCols) -> Select(Patient)
+  select(Patient(_, _, _)) |> field(p.id) |> field(p.name) |> field(p.mrn)
 end
 ```
 
-`insert` / `update` / `delete` need `SqlMapper(a)` + `Identified(a)`.
-`insert_all` needs only `SqlMapper`. `update_all`/`delete_all` build
-the SET / WHERE clauses directly from the column accessors — no codec.
+`from(patients) |> patient_row` for the read, `returning_with(patient_row)`
+for the write. With row polymorphism a projection can span tables — one
+`def just_id(c: { a | id: Expr(Int) })` serves every table with an `id`.
 
-`SqlMapper` is also implemented for `List(Assignment)` itself, so you
+That is why there is no version that reads the columns off the result type's
+field names. It would save the `field` lines, and it is the one thing in the
+library that could name a column the table does not have — a projection built
+from accessors cannot.
+
+
+`filter` narrows a query or a write you have already built. Where
+`where` takes a predicate, `filter` takes a *function* of the columns, so a
+caller that has not bound them can still add one — enough to write a
+tenancy wrapper that scopes a keyed write, rather than funnelling every
+scoped write through the `_all` forms.
+
+`insert` / `insert_all` / `update` / `delete` need `Assignable(a)`, and
+nothing else. `update_all`/`delete_all` build the SET / WHERE clauses
+directly from the column accessors — no codec.
+
+`Assignable` is also implemented for `List(Assignment)` itself, so you
 can pass an assignment list to `insert` directly when you've already
 built it (e.g. from a sparse changeset):
 
@@ -457,18 +747,26 @@ sparse_changes
 ### Timestamps
 
 `insert`/`update` emit only the columns you set — they don't auto-fill
-`created_at` / `updated_at`. Opt in per-write with `timestamped`, which
-works like ActiveRecord: `created_at` + `updated_at` on insert, `updated_at`
-only on update.
+`created_at` / `updated_at`. Opt in per-write with `timestamped`, which wraps
+the **value** being written and works like ActiveRecord: `created_at` +
+`updated_at` on insert, `updated_at` only on update.
 
 ```jade
-import Sql.Mutation exposing (insert, timestamped, update)
+import Sql.Write exposing (insert, timestamped, update)
 
-new_patient |> insert(patients) |> timestamped |> execute   -- both set
-patient     |> update(patients) |> timestamped |> execute   -- updated_at only
-new_import  |> insert(patients) |> execute                  -- no timestamps
+insert(new_patient |> timestamped, patients) |> execute   -- both set
+update(patch |> timestamped, patients, id) |> execute     -- updated_at only
+insert(new_import, patients) |> execute                   -- no timestamps
 ```
 
+It wraps the value rather than the built write so the required-columns check
+sees it: a table declaring the timestamps NOT NULL demands them of the value,
+and a pipe further down the chain could not answer for that.
+
+`update` drops the `created_at` the wrapper added, not any `created_at` you
+assigned yourself — the wrapper writes a clock token the runtime substitutes,
+so the two are distinguishable and a backdating update still lands.
+
 It's opt-in on purpose — backfills, imports, and `touch: false`-style writes
 just omit it (and can set the columns explicitly). The value is the **app
 clock** at execute time (set in Ruby, the same clock Rails uses, so