fastify-auto-sqlapi 0.3.0 → 0.4.1

package/AGENTS_FRONTEND.md

@@ -1,111 +1,136 @@
 # fastify-auto-sqlapi — client API (LLM reference)
 
-This file is the request GRAMMAR. For this deployment's tables/fields/aliases (the
-vocabulary), fetch `GET {p}/agent/manifest.md` if available, or consult Swagger.
+This is the request GRAMMAR. The vocabulary (this deployment's tables, fields, join aliases, computed fields, extra filters) comes from `GET {p}/agent/manifest.md` when enabled, or from Swagger.
 
-Rules: all request/response fields are camelCase schema field names — how the database names its columns is invisible here and irrelevant, the server maps them. `{p}` = deployment prefix (e.g. `/api`). `{table}` = the table's key in the manifest, which may differ from the database table name (one table can be exposed under several keys, each with its own rules). Join keys are backend-declared ALIASES (default = joined table name; list per table in Swagger). Write responses are PK-only. Write bodies reject unknown properties (400) — send only real schema fields. Arrays for bulk are capped (default 1000/request; chunk client-side). Composite-PK tables have no get/delete/bulk-delete (404) — use search / update.
+- All request/response fields are camelCase schema field names; the server maps them to columns.
+- `{p}` = deployment prefix (e.g. `/api`). `{table}` = the table's key in the manifest, which may differ from the DB table name (one table can be exposed under several keys, each with its own rules).
+- Join keys are backend-declared ALIASES (default: the joined table name).
+- Write responses return PKs only. Send only real schema fields in write bodies: unknown ones are dropped or rejected (400), depending on the server.
+- Composite-PK tables have no get/delete/bulk-delete routes (404): use search / update.
 
 ## Endpoints
 
 ```
-POST   {p}/search/{table}        body=search request           → {table, main:[...], ...}
-GET    {p}/rest/{table}/:id                                    → {main:{...}} | 404
-POST   {p}/rest/{table}          body={main, secondaries?}     → 201 {main:{id}, secondaries?}
-PUT    {p}/rest/{table}          body={main(+PK), secondaries?, deletions?} → {main:{id}, ...}
-DELETE {p}/rest/{table}/:id                                    → {main:{id}} | 404
-PUT    {p}/bulk/{table}          body=[{main, secondaries?, deletions?},...] → [{main:{id}},...]
-POST   {p}/bulk/{table}/delete   body=[{id:1},{id:2}]          → [{main:{id:1}},...]
+POST {p}/search/{table} body=search request → {table, main:[...], ...}
+GET {p}/rest/{table}/:id → {main:{...}} | 404
+POST {p}/rest/{table} body={main, secondaries?} → 201 {main:{id}, secondaries?}
+PUT {p}/rest/{table} body={main(+PK), secondaries?, deletions?} → {main:{id}, secondaries?, deletions?}
+DELETE {p}/rest/{table}/:id → {main:{id}} | 404
+PUT {p}/bulk/{table} body=[{main, secondaries?, deletions?}, ...] → [{main:{id}}, ...]
+POST {p}/bulk/{table}/delete body=[{id:1}, {id:2}] → [{main:{id:1}}, ...] // key = the table's PK field
 ```
 
-## SEARCH
+## Search
 
-Query string (all optional): `?orderBy=...&page=1&itemsPerPage=20&computeMin=f&computeMax=f&computeSum=f&computeAvg=f`
-Body (all optional; `{}` = first N rows). Everything below is combinable in one request:
+Querystring, all optional: `orderBy`, `page`, `itemsPerPage`, `computeMin|Max|Sum|Avg=<field>`. Body, all optional and combinable; `{}` returns the first N rows.
 
 ```jsonc
 // POST {p}/search/customer?orderBy=orders.sum.total DESC, creator.name ASC, id&page=1&itemsPerPage=20&computeSum=total
 {
-  "filters": { "status": "active", "deletedById": null },   // equality AND; null → IS NULL; extraFilters names (backend-defined, see manifest) also accepted here
-  "conditions": [                                            // advanced, AND, same field repeatable
+  "filters": { "status": "active", "deletedById": null }, // equality, AND; null → IS NULL; also computed fields and backend extra filters (see manifest). Unknown key → 400
+  "conditions": [ // AND; the same field may repeat
     { "field": "total", "method": "isBetween", "params": [100, 500] },
     { "field": "name", "method": "isILike", "params": ["%mario%"] },
     { "field": "status", "method": "isIn", "params": [["active", "pending"]] },
-    { "field": "orders.count.id", "method": "isGreaterOrEqual", "params": [4] }  // HAVING-style: needs matching joinGroup below
+    { "field": "orders.count.id", "method": "isGreaterOrEqual", "params": [4] } // alias.fn.field, HAVING-style: needs the matching joinGroup below
   ],
-  "selectComputed": ["displayName"],       // backend computed fields, projected into main rows only if listed
-  "joinMustExist": {                       // EXISTS on child: filters WHICH main rows return; no data fetched
+  "selectComputed": ["displayName"], // computed fields are projected into main rows only when listed
+  "joinMustExist": { // EXISTS on children: decides WHICH main rows return; fetches nothing
     "labels": { "filters": { "labelId": 1 }, "conditions": [] }
   },
-  "joinMultiple": {                        // side query: fetches child rows OF the returned mains
-    "orders": { "filters": { "status": "pending" }, "selection": "id,total,status" }
+  "joinMultiple": { // side query: child rows of the returned main rows
+    "orders": { "filters": { "status": "pending" }, "conditions": [], "selection": "id,total,status" }
   },
-  "joinGroup": {                           // aggregations on child rows
+  "joinGroup": { // aggregates child rows of the returned main rows
     "orders": {
-      "aggregations": {
-        "by": "status",                    // optional GROUP BY (schema field or backend computed, e.g. month bucket)
-        "sum": ["total"], "min": ["total"], "max": ["total"], "avg": ["total"],
-        "count": ["id"], "distinctCount": ["status"]
-      },
-      "filters": { "status": "active" }    // narrows child rows before aggregating
+      "aggregations": { "by": "status", "sum": ["total"], "min": ["total"], "max": ["total"], "avg": ["total"], "count": ["id"], "distinctCount": ["status"] }, // by: optional GROUP BY (field or computed)
+      "filters": { "status": "active" }, "conditions": [] // narrow children before aggregating
     }
   },
-  "joinLeft": {                            // N:1 parent embed (alias declared unique by backend)
-    "creator": { "selection": "id,name" }  // filters/conditions here EXCLUDE mains whose parent doesn't match; schema fields only (extraFilters NOT usable here)
+  "joinLeft": { // N:1 parent (alias declared unique by the backend)
+    "creator": { "selection": "id,name", "filters": {}, "conditions": [] } // filters here EXCLUDE mains whose parent does not match; no extra filters here
   }
 }
 ```
 
-Response (each section present only if requested):
+Response; each section is present only if requested:
 
 ```jsonc
 {
   "table": "customer",
   "main": [{ "id": 1, "name": "Mario", "creatorId": 7, "displayName": "..." }],
-  "joinMultiple": { "orders": [{ "id": 10, "customerId": 1, "total": 50 }] },
+  "joinMultiple": { "orders": [{ "id": 10, "customerId": 1, "total": 50 }] }, // flat list for all mains: group client-side by FK
   "joinGroup": { "orders": {
-    "sum": { "total": 150 },                                  // keyed by fn when no "by"
-    "rows": [{ "by": "pending", "sum_total": 100 }]           // rows[] when "by" is set
+    "sum": { "total": 150 }, // no "by": ONE total over the children of ALL returned mains
+    "rows": [{ "by": "pending", "sum_total": 100 }] // with "by": one row per group; by = FK field gives per-main values
   }},
-  "joinLeft": { "creator": [{ "id": 7, "name": "Alice" }] },  // deduped; map client-side: main.creatorId === creator.id
-  "pagination": {                                             // present when page/itemsPerPage sent
+  "joinLeft": { "creator": [{ "id": 7, "name": "Alice" }] }, // deduplicated: match main.creatorId === creator.id
+  "pagination": { // only when page or itemsPerPage is sent
     "total": 25, "pages": 3,
-    "computed": { "sum": { "total": 999 } },                  // computeMin/Max/Sum/Avg (require pagination)
+    "computed": { "sum": { "total": 999 } }, // computeMin/Max/Sum/Avg over all matching rows; require pagination
     "paginator": { "page": 1, "itemsPerPage": 20 }
   }
 }
 ```
 
-`orderBy` forms (comma-separable): `field [ASC|DESC]` | `alias.parentField` (joinLeft-eligible alias, adds LEFT JOIN) | `alias.fn.field` (fn: sum|min|max|avg|count|distinctCount — the joinGroup with that fn+field MUST be in the body; rows without children sort as 0). For 3-part orderBy and HAVING-style conditions: `aggregations.by` is allowed only when it equals the correlation FK (else 400); aggregation orderBy is rejected (400) on tables with distinctResults.
+Pagination:
+- Without `page`/`itemsPerPage`, the server caps rows at its maximum (default 1000) and returns no `pagination` block.
+- With `page` only, `itemsPerPage` defaults to 500 (or the server maximum if lower).
+- Both are integers ≥ 1. `itemsPerPage` above the server maximum → 400.
 
-Condition methods (params arity): `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual` → `[v]`; `isLike|isNotLike|isILike|isNotILike` → `["%p%"]`; `isBetween|isNotBetween` → `[from,to]`; `isIn|isNotIn` → `[[v1,v2]]`; `isNull|isNotNull` → `[]`. Unknown field or method → 400; so is a `params` that is not an array or is shorter than the arity above (`isNull`/`isNotNull` take none).
+`orderBy` is a comma-separated list, each part one of:
+- `field [ASC|DESC]`, including computed fields.
+- `alias.parentField`: joinLeft alias; adds the LEFT JOIN.
+- `alias.fn.field`, with fn one of `sum|min|max|avg|count|distinctCount`. The joinGroup with that fn and field must be in the body.
 
-## WRITES
+For `alias.fn.field`, in both `orderBy` and conditions, the joinGroup `by` must be absent or equal to the FK (else 400). In `orderBy` it is also a 400 on tables with distinct results.
+
+A main without children (or none left after the joinGroup filters) has `count`, `distinctCount` and `sum` = 0, but `min`, `max` and `avg` = null. Null sorts where the database puts it (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC) and fails every comparison: `max < 5` excludes such mains; `isNull` selects them.
+
+Condition methods and `params` arity:
+- `[v]`: `isEqual|isNotEqual|isGreater|isGreaterOrEqual|isLess|isLessOrEqual|isNotGreater|isNotGreaterOrEqual|isNotLess|isNotLessOrEqual`
+- `["%p%"]`: `isLike|isNotLike|isILike|isNotILike`
+- `[from, to]`: `isBetween|isNotBetween`
+- `[[v1, v2]]`: `isIn|isNotIn`
+- `[]`: `isNull|isNotNull`
+
+An unknown field or method, or `params` that is not an array or is too short → 400.
+
+## Writes
 
 ```jsonc
-// POST {p}/rest/customer  (insert; omit auto-generated PKs)
+// POST {p}/rest/customer — insert; omit auto-generated PKs
 { "main": { "name": "Mario", "email": "m@t.it" },
-  "secondaries": { "orders": [{ "total": 50, "status": "pending" }] } }  // child FK auto-filled from new main PK
+  "secondaries": { "orders": [{ "total": 50, "status": "pending" }] } } // child FK auto-filled from the new main PK
 // → 201 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 10 }] } }
 
-// PUT {p}/rest/customer  (update; main MUST include PK; partial fields ok; null = set column NULL)
+// PUT {p}/rest/customer — update; main MUST include the PK; send only the fields to change; null sets NULL
 { "main": { "id": 1, "email": "new@t.it" },
-  "secondaries": { "orders": [{ "total": 75 }] },      // inserts/upserts children, FK auto-filled
-  "deletions":   { "orders": [{ "id": 10 }] } }        // deletes children by PK (scoped to this main)
+  "secondaries": { "orders": [{ "total": 75 }] }, // insert (or upsert) children, FK auto-filled
+  "deletions": { "orders": [{ "id": 10 }] } } // delete children by PK, only children of this main
 // → 200 { "main": { "id": 1 }, "secondaries": { "orders": [{ "id": 20 }] }, "deletions": { "orders": [{ "id": 10 }] } }
 
-// PUT {p}/bulk/customer  (bulk upsert; one SQL for mains; per-item secondaries/deletions)
+// PUT {p}/bulk/customer — bulk upsert; items need not share keys: an omitted field keeps the stored value (update) or takes the column default (insert)
 [ { "main": { "name": "Mario" }, "secondaries": { "orders": [{ "total": 50 }] } },
   { "main": { "name": "Luigi" } } ]
 // → 200 [ { "main": { "id": 1 }, "secondaries": {...} }, { "main": { "id": 2 } } ]
 ```
 
+Upsert tables (see manifest):
+- Every row, main or child, carries its conflict key: missing, null, or shared by two rows of one request → 400.
+- When the key is the id, rows without an id are inserted.
+- Bulk arrays are capped (default 1000): chunk client-side.
+
 ## Errors
 
-400 (schema or business validation) — map `fields[].path` to form fields:
+400 (schema or business validation): map `fields[].path` to form fields.
 
 ```json
 { "statusCode": 400, "error": "Bad Request", "message": "Validation failed",
   "fields": [ { "path": "body.main.name", "code": "required", "message": "must have required property 'name'" } ] }
 ```
 
-Other: 404 (get/delete not found), 400 `itemsPerPage exceeds the maximum` (lower it), 500 raw DB errors (constraint violations surface unmapped). Fixed complexity caps, per search: **100 `conditions`** per section (top level and each join family) and **20** comma-separated `orderBy` parts (`orderBy` string ≤ 1024 chars) — over either → 400: collapse a long list of equality conditions into one `isIn`. `paginator.page` and `paginator.itemsPerPage` must be integers ≥ 1 — send numbers, not querystring strings.
+- 403: tenant violation.
+- 404: record not found, or outside your tenant.
+- 500: DB errors (e.g. constraint violations), unmapped, with a `requestId` to report.
+- Per search, max 100 `conditions` per section (top level and each join) and max 20 `orderBy` parts (≤ 1024 chars); over either → 400. Collapse many equality conditions into one `isIn`.

package/BREAKING_CHANGES.md

@@ -744,3 +744,132 @@ export const dbTables: DbTables = { customer_order: TableCustomerOrder };
 
 A client that read `table` from a search response to recover the physical table name should
 use the key it called instead — that is now what `table` returns.
+
+---
+
+# Breaking Change — an upsert targets a unique key verified at startup
+
+*Landed in **0.4.0**.* Decision and rationale: [ADR 0021](./docs/adr/0021-upsert-targets-a-verified-unique-key.md).
+
+## Why this changed
+
+`upsertMap` accepted any column list, and the dialects disagreed on what it meant:
+
+- **No unique index on the declared columns**: PostgreSQL failed every write; MySQL never
+  conflicted and inserted duplicates, silently.
+- **MySQL `ON DUPLICATE KEY UPDATE` fires on any unique index**, not on the declared key: a row
+  carrying another row's unique value (an `email`, an `id`) updated *that* row, silently, where
+  PostgreSQL refused the write.
+- **A natural-key upsert on MySQL returned wrong PKs** for the rows it updated, and secondaries
+  were attached to them.
+
+## What changed
+
+- **The generated Schema carries `uniqueKeys`**, the table's unique keys other than the
+  primary key — emitted even when empty. Partial, expression and (MySQL) prefix indexes are not
+  keys an upsert can target and are left out.
+- **`defineTable` refuses an `upsertMap` rule that is not exactly the Schema's `primaryKey` or
+  one of its `uniqueKeys`** (same fields, any order). This includes rules on write-join child
+  schemas — the child still needs no `defineTable` of its own. A rule on a view is refused.
+- **Every upserted row must carry its key — `400` otherwise**: a natural key must be present
+  and not null; the primary key may be absent altogether (a plain insert with a generated key)
+  but not partial or null. Two rows of one request with the same key are a `400` too.
+- **MySQL and MariaDB upsert by key** — probe, insert, update — instead of
+  `ON DUPLICATE KEY UPDATE`. A row whose other unique column belongs to another row is now a
+  database error (sanitized 500) on every dialect, never a write to that other row.
+
+## Who is affected
+
+- **Schemas generated before this release** used with a natural-key rule (`['email']`,
+  `['customerId', 'tag']` that is not the PK…): `defineTable` throws until they are
+  regenerated. Rules on the primary key keep working — `primaryKey` was already generated.
+- **A rule on columns without a unique index**: it never worked on PostgreSQL, and on MySQL it
+  was inserting duplicates. `defineTable` now throws.
+- **Clients sending upsert rows without their key**, or twice the same key in one request:
+  `400`.
+- **MySQL/MariaDB**: an upsert costs two to three statements per chunk instead of one.
+- **A driver configured without `CLIENT_FOUND_ROWS`** (MySQL/MariaDB): the upsert checks the
+  rows its UPDATE matched, and without that flag the driver reports changed rows instead —
+  a row re-sent unchanged would be reported as missing. `mysql2` sets the flag by default.
+- **Code using the exported `SqlDialect` type or `getDialect()` for upserts**: `upsertSql()`
+  and `upsertUpdateSet()` are gone. They are replaced by `onConflict?: { sql(), updateSet() }`,
+  present on PostgreSQL only — its absence is what tells MySQL/MariaDB to upsert by key.
+  A custom `SqlDialect` implementation no longer compiles until it drops the two methods.
+
+## Migration
+
+1. Regenerate the schemas: `npx sqlapi-generate-schema`. Each Schema now ends with
+   `uniqueKeys: [...]`.
+2. Start the application: a rule that is not a unique key fails with a message listing the
+   keys the table has, e.g.
+   `upsertMap rule on 'customer' (email) is not a unique key of the table. An upsert must target exactly one: (id) primary key (ADR 0021).`
+   Either add the unique index the rule assumed, or point the rule at an existing key.
+3. Make sure every upsert row carries its key. For a write-join child keyed on
+   `(parentId, lang)`, the FK is filled from the parent — the client sends `lang`.
+4. If you use `SqlDialect` directly: build an upsert through `QueryClient.insertOrUpdate` /
+   `bulkInsertOrUpdate`, which pick the right strategy per dialect, rather than from the
+   dialect's clause. The PostgreSQL clause, if you need it, is now
+   `getDialect('postgres').onConflict!.sql(keys, getDialect('postgres').onConflict!.updateSet(fields, keepAsIs))`
+   — `updateSet` returns `''` when nothing is left to update, as before. A custom dialect
+   implements `onConflict` only when its upsert syntax names its conflict target; otherwise it
+   leaves it out and gets the upsert by key.
+
+```typescript
+// before
+const dialect = getDialect('postgres');
+dialect.upsertSql(quotedKeys, dialect.upsertUpdateSet(fields, conflictKeys));
+
+// after
+const { onConflict } = getDialect('postgres');
+onConflict!.sql(quotedKeys, onConflict!.updateSet(fields, conflictKeys));
+```
+
+---
+
+# Breaking Change — `min`, `max` and `avg` of a main row without children are NULL
+
+*Landed in **0.4.1**.*
+
+## Why this changed
+
+`orderBy` and HAVING-style conditions on `<alias>.<fn>.<field>` run a correlated subquery per
+main row, and every aggregate was wrapped in `COALESCE(…, 0)`. Over no child rows, that 0 is
+the right answer for `count`, `distinctCount` and `sum`, but `min`, `max` and `avg` have no
+value at all:
+
+- **PostgreSQL**: on a text, char, date or timestamp column the request failed with a 500,
+  `COALESCE types … and integer cannot be matched`.
+- **MySQL/MariaDB**: no error, but those mains were compared as `0` — `max(orderDate) <
+  '2026-03-01'` matched every main without children.
+- **Both, numeric columns**: a 0 that no child row holds decided the ordering and conditions.
+
+## What changed
+
+- `count`, `distinctCount` and `sum` over no rows are still 0.
+- `min`, `max` and `avg` over no rows are NULL. In `orderBy` they sort where the database puts
+  NULL (PostgreSQL: last in ASC, first in DESC; MySQL/MariaDB: first in ASC, last in DESC). In
+  conditions they fail every comparison; `isNull` / `isNotNull` select them.
+- "Without children" includes children all excluded by the joinGroup's own `filters` /
+  `conditions`.
+- `result.joinGroup` is unchanged: it was never coalesced.
+
+## Who is affected
+
+Clients that order or filter by `min`, `max` or `avg` of a **numeric** column on tables where
+some main rows have no children:
+
+- `orderBy=orders.min.total ASC` on PostgreSQL: those mains move from first to last.
+  `… DESC`: from last to first. On MySQL/MariaDB the order is unchanged (NULL sorts as the
+  smallest value, where the 0 was for non-negative columns).
+- `conditions: [{ field: 'orders.max.total', method: 'isLess', params: [5] }]`: those mains
+  no longer match. `isGreater` with a negative value, `isEqual` with 0 and similar change the
+  same way.
+
+## Migration
+
+- To drop mains without children from a result, add `{ field: 'orders.count.id', method:
+  'isGreater', params: [0] }` (or `isNotNull` on the aggregate).
+- To list only them, use `isNull` on the aggregate, or `isEqual 0` on `count`.
+- Conditions are ANDed, so "below 5 **or** no children" is no longer one request: run the
+  `isNull` search separately, or compare against a `count` instead where that expresses the
+  same thing.

package/CHANGELOG.md

@@ -9,6 +9,89 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ## [Unreleased]
 
+## [0.4.1]
+
+### Changed
+
+- **BREAKING: `min`, `max` and `avg` of a main row without children are NULL, not 0, in
+  `orderBy` and HAVING-style conditions.** The correlated subquery behind `alias.fn.field`
+  wrapped every aggregate in `COALESCE(…, 0)`. That 0 is right for `count`, `distinctCount` and
+  `sum`, which keep it; for `min`/`max`/`avg` it invented a value the children do not have. On
+  numeric columns, such mains now sort where the database puts NULL (PostgreSQL: last in ASC,
+  first in DESC; MySQL/MariaDB: first in ASC, last in DESC) instead of as 0, and a condition
+  like `max < 5` no longer matches them (`isNull` does). See
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--min-max-and-avg-of-a-main-row-without-children-are-null).
+
+### Fixed
+
+- **PostgreSQL: `orderBy` or a condition on `min`/`max`/`avg` of a non-numeric column no longer
+  fails.** `orderBy=charge.max.monthYear` over a `character(7)` column (or any text, date or
+  timestamp one) was a 500, `COALESCE types character and integer cannot be matched`, whenever
+  the request reached the database. MySQL/MariaDB did not fail but compared those mains as `0`:
+  `max(orderDate) < '2026-03-01'` matched every main without children. Both now compare the
+  aggregate as NULL, as above.
+
+## [0.4.0]
+
+### Changed
+
+- **BREAKING: an upsert targets a unique key verified at startup** ([ADR 0021](./docs/adr/0021-upsert-targets-a-verified-unique-key.md)).
+  `upsertMap` accepted any column list, and on MySQL `ON DUPLICATE KEY UPDATE` fired on *any*
+  unique index: a declared key without a unique index inserted duplicates, and a row carrying
+  another row's unique value updated that other row — both silently, where PostgreSQL failed.
+  Now:
+  - the generated Schema carries `uniqueKeys` (partial, expression and prefix indexes left out);
+  - `defineTable` refuses a rule that is not exactly the `primaryKey` or a `uniqueKeys` entry —
+    write-join children included, still without a `defineTable` of their own;
+  - an upserted row without its key, or two rows of one request with the same key, is a `400`
+    (a row naming no PK field at all is still a plain insert when the key is the PK);
+  - MySQL and MariaDB upsert by key — probe, insert, update: two to three statements per chunk
+    instead of one. PostgreSQL keeps `ON CONFLICT (key)`, unchanged;
+  - the exported `SqlDialect` type loses `upsertSql()` and `upsertUpdateSet()`, replaced by
+    `onConflict?: { sql(), updateSet() }`, present on PostgreSQL only.
+  Regenerate the schemas; see
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--an-upsert-targets-a-unique-key-verified-at-startup).
+
+### Fixed
+
+- **Bulk writes no longer lose or overwrite fields when items do not share the same keys.**
+  `bulkUpsert` (route and `sqlApi`), secondaries of every write, and
+  `QueryClient.bulkInsert` / `bulkInsertOrUpdate` took the column list of the whole batch from
+  the first record. A field present only on a later item was silently dropped; a field present
+  only on an earlier item was bound as NULL for the others — skipping the column default on
+  insert (or failing on a `NOT NULL DEFAULT` column) and wiping the stored value on upsert.
+  Each record now writes exactly its own fields: records are grouped by column set, one
+  statement per group, PKs still returned in input order. Batches whose items share the same
+  keys still run as a single statement.
+- **An upsert item holding only its conflict keys returns its PK.** Such an item has nothing
+  to update, so an existing row is left untouched — but postgres `DO NOTHING` returns no row
+  for it and mysql's `insertId` says nothing about it: the single upsert returned `undefined`
+  and a bulk upsert failed with a 500 after writing. The PK now comes from the item when it
+  holds it, otherwise it is looked up by the conflict keys (one `SELECT` per chunk).
+- **MySQL: an upsert by a natural key returns the PK of the row it updated.** With a conflict
+  key that is not the PK (the README's `email` sync), the PKs were synthesized as
+  `insertId + n`, which counts only inserted rows: re-sending a payload returned ids of other
+  rows, or of rows that do not exist, and secondaries were attached to them. The upsert by key
+  above takes them from its probe.
+
+### Documentation
+
+- **Agent files rewritten for LLM readers** — `AGENTS.md`, `AGENTS_BACKEND.md` and
+  `AGENTS_FRONTEND.md` went from 107 KB to 39 KB. Duplicated sections were merged, the
+  `defineTable` reference is now one annotated example, and markdown links and emoji were
+  removed. No API changed; several statements were wrong and are corrected:
+  - write bodies are closed, but under Fastify's default `removeAdditional: true` an unknown
+    property is stripped silently; it is a `400` only with `removeAdditional: false`. Unknown
+    `filters` keys, by contrast, are always a `400`;
+  - `ConditionBuilder.raw()` takes `?` markers, not `$1`;
+  - a computed field's `values` is required (the translated-jsonb example omitted it);
+  - a `joinGroup` without `by` returns one total over the children of all returned main rows,
+    not one per row; `by` set to the FK gives per-row values;
+  - search pagination is querystring-only (`page`, `itemsPerPage`), and `distinctResults`
+    rejects only aggregation `orderBy`, not aggregation conditions;
+  - the plugin options now list `agentManifest`, `sqlApi.search` lists `selectComputed` and
+    `maxRows`, and the exports list is complete.
+
 ## [0.3.0]
 
 ### Changed
@@ -685,7 +768,9 @@ the join API redesign (documented in [BREAKING_CHANGES.md](./BREAKING_CHANGES.md
 primary key support in updates, transactional insert/update with secondaries, the hook matrix,
 and bulk operations.
 
-[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.1
+[0.4.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.4.0
 [0.3.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.3.0
 [0.2.4]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.4
 [0.2.3]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.3

package/README.md

@@ -52,7 +52,7 @@ Writes read the same way — *"sync these clients and their tags: update the one
 //        { "main": { "id": 2 } }]
 ```
 
-Conflict keys are declared server-side (`upsertMap`: here customer on `email`, tag on `(customerId, tag)`), so re-sending the same payload updates rows instead of duplicating them — client-side sync without hand-written diffing.
+Conflict keys are declared server-side (`upsertMap`: here customer on `email`, tag on `(customerId, tag)`) and checked at startup against the unique keys the database enforces, so re-sending the same payload updates rows instead of duplicating them and never touches a row through any other key — client-side sync without hand-written diffing.
 
 And multi-tenancy is one plugin option (`getTenantId: (req) => req.user?.organizationId ?? null`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
 

package/dist/bin/generate-schema.js

@@ -37,10 +37,10 @@ function fileStatus(filename, content) {
 function writeSchemaFiles(tableMap, schemasDir) {
     const report = { created: false, touched: false, untouched: 0, files: new Set() };
     for (const schemaName of Object.keys(tableMap)) {
-        const { name: tableName, fields, colMap, primary, generated, isView } = tableMap[schemaName];
+        const { name: tableName, fields, colMap, primary, generated, isView, uniqueKeys } = tableMap[schemaName];
         const filename = path.join(schemasDir, `${schemaName}.ts`);
         report.files.add(`${schemaName}.ts`);
-        const content = generateSchemaFile(schemaName, tableName, fields, colMap, primary, generated, isView);
+        const content = generateSchemaFile(schemaName, tableName, fields, colMap, primary, generated, isView, uniqueKeys);
         const status = fileStatus(filename, content);
         if (status === 'created')
             report.created = true;

package/dist/lib/cli/mysql-introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mysql-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/mysql-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAkBD,oFAAoF;AACpF,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,0BAA0B,IAAI,qBAAqB,CAmBlE;AAyED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,CAejE;AAED,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,qBAAqB,EACvC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAoBvB"}
+{"version":3,"file":"mysql-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/mysql-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAyBD,oFAAoF;AACpF,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,0BAA0B,IAAI,qBAAqB,CAmBlE;AAyED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,UAAU,CAejE;AAED,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,qBAAqB,EACvC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CA+CvB"}

package/dist/lib/cli/mysql-introspect.js

@@ -117,7 +117,30 @@ export async function introspectMysqlTables(connectionConfig, schema) {
          ON t.table_schema = c.table_schema AND t.table_name = c.table_name
        WHERE c.table_schema = ?
        ORDER BY c.table_name, c.ordinal_position`, [schema]);
-        return rows.map(mapMysqlColumnRow);
+        // Unique indexes (constraints included) other than the primary key. An index is left out
+        // whole when any part is an expression (no COLUMN_NAME) or a prefix (SUB_PART): the first
+        // cannot be named by a column list, the second makes only the leading characters unique —
+        // neither is a key an upsert can target (ADR 0021).
+        const [uniqueRows] = await connection.query(`SELECT s.table_name AS table_name, s.column_name AS column_name, s.index_name AS index_name
+       FROM information_schema.statistics s
+       WHERE s.table_schema = ? AND s.non_unique = 0 AND s.index_name <> 'PRIMARY'
+         AND NOT EXISTS (
+           SELECT 1 FROM information_schema.statistics x
+           WHERE x.table_schema = s.table_schema AND x.table_name = s.table_name
+             AND x.index_name = s.index_name
+             AND (x.column_name IS NULL OR x.sub_part IS NOT NULL)
+         )
+       ORDER BY s.table_name, s.index_name, s.seq_in_index`, [schema]);
+        const uniqueKeys = new Map();
+        for (const u of uniqueRows) {
+            const key = `${u.table_name}.${u.column_name}`;
+            uniqueKeys.set(key, [...(uniqueKeys.get(key) ?? []), u.index_name]);
+        }
+        return rows.map((row) => {
+            const column = mapMysqlColumnRow(row);
+            const indexes = uniqueKeys.get(`${column.table_name}.${column.column_name}`);
+            return indexes ? { ...column, unique_keys: indexes } : column;
+        });
     }
     finally {
         await connection.end();

package/dist/lib/cli/pg-introspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pg-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/pg-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAmBjD,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C;AAcD,wBAAsB,gBAAgB,CACpC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAmEvB"}
+{"version":3,"file":"pg-introspect.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/pg-introspect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAmBjD,wBAAgB,qBAAqB,IAAI,MAAM,CAY9C;AAgBD,wBAAsB,gBAAgB,CACpC,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC,CAsFvB"}

package/dist/lib/cli/pg-introspect.js

@@ -26,7 +26,8 @@ export async function introspectTables(connectionString, schema) {
                 c.is_identity::text, c.is_generated::text,
                 (pk.column_name IS NOT NULL) AS is_primary,
                 (t.table_type = 'VIEW') AS is_view,
-                c.ordinal_position::int AS ordinal_position
+                c.ordinal_position::int AS ordinal_position,
+                uk.unique_keys
          FROM information_schema.columns c
          JOIN information_schema.tables t
            ON t.table_schema = c.table_schema AND t.table_name = c.table_name
@@ -38,12 +39,28 @@ export async function introspectTables(connectionString, schema) {
             AND tc.table_schema = kcu.table_schema
            WHERE tc.constraint_type = 'PRIMARY KEY' AND tc.table_schema = $1
          ) pk ON pk.table_name = c.table_name AND pk.column_name = c.column_name
+         -- Unique indexes (constraints are backed by one) other than the primary key, over
+         -- plain columns only: a partial index (indpred) or one on an expression (indexprs)
+         -- cannot be named by a column list, so it is no upsert key (ADR 0021).
+         LEFT JOIN (
+           SELECT tbl.relname::text AS table_name, att.attname::text AS column_name,
+                  array_agg(idx.relname::text ORDER BY idx.relname) AS unique_keys
+           FROM pg_index i
+           JOIN pg_class idx ON idx.oid = i.indexrelid
+           JOIN pg_class tbl ON tbl.oid = i.indrelid
+           JOIN pg_namespace ns ON ns.oid = tbl.relnamespace
+           JOIN pg_attribute att ON att.attrelid = tbl.oid AND att.attnum = ANY(i.indkey)
+           WHERE i.indisunique AND NOT i.indisprimary
+             AND i.indpred IS NULL AND i.indexprs IS NULL
+             AND ns.nspname = $1
+           GROUP BY tbl.relname, att.attname
+         ) uk ON uk.table_name = c.table_name AND uk.column_name = c.column_name
          WHERE c.table_schema = $1
          UNION ALL
          SELECT mc.relname::text, ma.attname::text, mt.typname::text,
                 NULL::text, CASE WHEN ma.attnotnull THEN 'NO' ELSE 'YES' END,
                 'NO'::text, 'NEVER'::text,
-                false, true, ma.attnum::int
+                false, true, ma.attnum::int, NULL::text[]
          FROM pg_class mc
          JOIN pg_namespace mn ON mn.oid = mc.relnamespace
          JOIN pg_attribute ma
@@ -55,6 +72,7 @@ export async function introspectTables(connectionString, schema) {
         // The query's own columns are spelled out rather than spread: `is_identity` and
         // `is_generated` arrive as the standard's string enums and `ordinal_position` only exists
         // to order the union, so none of the three belongs in the `ColumnInfo` handed back.
+        // `unique_keys` is NULL for a column in no unique index.
         return result.rows.map((row) => ({
             table_name: row.table_name,
             column_name: row.column_name,
@@ -67,6 +85,7 @@ export async function introspectTables(connectionString, schema) {
             // mandatory field and the table cannot be inserted into at all.
             ...(row.is_identity === 'YES' ? { is_auto_increment: true } : {}),
             ...(row.is_generated === 'ALWAYS' ? { is_generated: true } : {}),
+            ...(row.unique_keys?.length ? { unique_keys: row.unique_keys } : {}),
         }));
     }
     finally {

package/dist/lib/cli/schema-codegen.d.ts

@@ -30,5 +30,5 @@ export declare function applyExcludeTables(tableMap: TableMap, excludeTables?: s
  * Returns the excluded columns as `table.column`, in map order.
  */
 export declare function applyExcludeColumns(tableMap: TableMap, excludeColumns?: string[]): string[];
-export declare function generateSchemaFile(schemaName: string, tableName: string, fields: Record<string, string>, colMap: Record<string, string>, primary?: string[], generated?: string[], isView?: boolean): string;
+export declare function generateSchemaFile(schemaName: string, tableName: string, fields: Record<string, string>, colMap: Record<string, string>, primary?: string[], generated?: string[], isView?: boolean, uniqueKeys?: string[][]): string;
 //# sourceMappingURL=schema-codegen.d.ts.map

package/dist/lib/cli/schema-codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IACV,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GACA,MAAM,CA6DR;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CA0C1D;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAgBzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAiD3F;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,MAAM,CAAC,EAAE,OAAO,GACf,MAAM,CAoDR"}
+{"version":3,"file":"schema-codegen.d.ts","sourceRoot":"","sources":["../../../src/lib/cli/schema-codegen.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE;IACV,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GACA,MAAM,CA6DR;AAcD,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,QAAQ,CAwD1D;AAaD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAgBzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAmD3F;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,CAAC,EAAE,MAAM,EAAE,EAClB,SAAS,CAAC,EAAE,MAAM,EAAE,EACpB,MAAM,CAAC,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,GACtB,MAAM,CAuDR"}