fastify-auto-sqlapi 0.5.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/AGENTS.md +5 -5
  2. package/AGENTS_BACKEND.md +166 -130
  3. package/AGENTS_FRONTEND.md +60 -38
  4. package/BREAKING_CHANGES.md +9 -893
  5. package/CHANGELOG.md +258 -15
  6. package/README.md +71 -45
  7. package/dist/bin/generate-schema.js +12 -12
  8. package/dist/bin/generate-tables.js +1 -2
  9. package/dist/bin/utils.d.ts +2 -6
  10. package/dist/bin/utils.d.ts.map +1 -1
  11. package/dist/bin/utils.js +13 -33
  12. package/dist/index.d.ts +13 -33
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +6 -37
  15. package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
  16. package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
  17. package/dist/lib/adapters/pg-adapter.d.ts +5 -2
  18. package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
  19. package/dist/lib/agent/manifest.d.ts +27 -10
  20. package/dist/lib/agent/manifest.d.ts.map +1 -1
  21. package/dist/lib/agent/manifest.js +43 -26
  22. package/dist/lib/agent/tool-schemas.d.ts +5 -4
  23. package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
  24. package/dist/lib/agent/tool-schemas.js +5 -5
  25. package/dist/lib/cli/config.d.ts +37 -2
  26. package/dist/lib/cli/config.d.ts.map +1 -1
  27. package/dist/lib/cli/config.js +106 -16
  28. package/dist/lib/cli/mysql-introspect.d.ts +6 -1
  29. package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
  30. package/dist/lib/cli/mysql-introspect.js +15 -15
  31. package/dist/lib/cli/pg-introspect.d.ts +0 -1
  32. package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
  33. package/dist/lib/cli/pg-introspect.js +2 -13
  34. package/dist/lib/cli/tables-codegen.d.ts +0 -4
  35. package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
  36. package/dist/lib/cli/tables-codegen.js +24 -87
  37. package/dist/lib/db.d.ts +42 -17
  38. package/dist/lib/db.d.ts.map +1 -1
  39. package/dist/lib/db.js +114 -40
  40. package/dist/lib/dialect.d.ts +5 -0
  41. package/dist/lib/dialect.d.ts.map +1 -1
  42. package/dist/lib/dialect.js +3 -0
  43. package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
  44. package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
  45. package/dist/lib/engine/bulk/bulk-delete.js +66 -30
  46. package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
  47. package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
  48. package/dist/lib/engine/read-hooks.d.ts +3 -3
  49. package/dist/lib/engine/read-hooks.d.ts.map +1 -1
  50. package/dist/lib/engine/read-hooks.js +3 -3
  51. package/dist/lib/engine/rest/delete.d.ts.map +1 -1
  52. package/dist/lib/engine/rest/delete.js +12 -18
  53. package/dist/lib/engine/rest/get.js +8 -8
  54. package/dist/lib/engine/rest/insert.d.ts.map +1 -1
  55. package/dist/lib/engine/rest/insert.js +31 -18
  56. package/dist/lib/engine/rest/update.d.ts.map +1 -1
  57. package/dist/lib/engine/rest/update.js +34 -17
  58. package/dist/lib/engine/search/aggregations.d.ts +3 -3
  59. package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
  60. package/dist/lib/engine/search/aggregations.js +20 -16
  61. package/dist/lib/engine/search/conditions.d.ts +9 -5
  62. package/dist/lib/engine/search/conditions.d.ts.map +1 -1
  63. package/dist/lib/engine/search/conditions.js +31 -20
  64. package/dist/lib/engine/search/fields.d.ts +44 -11
  65. package/dist/lib/engine/search/fields.d.ts.map +1 -1
  66. package/dist/lib/engine/search/fields.js +94 -28
  67. package/dist/lib/engine/search/join-families.d.ts +7 -7
  68. package/dist/lib/engine/search/join-families.d.ts.map +1 -1
  69. package/dist/lib/engine/search/join-families.js +84 -75
  70. package/dist/lib/engine/search/joins.d.ts +15 -7
  71. package/dist/lib/engine/search/joins.d.ts.map +1 -1
  72. package/dist/lib/engine/search/joins.js +23 -13
  73. package/dist/lib/engine/search/order-by.d.ts +11 -12
  74. package/dist/lib/engine/search/order-by.d.ts.map +1 -1
  75. package/dist/lib/engine/search/order-by.js +24 -28
  76. package/dist/lib/engine/search/search.d.ts.map +1 -1
  77. package/dist/lib/engine/search/search.js +111 -62
  78. package/dist/lib/engine/validate.d.ts +21 -3
  79. package/dist/lib/engine/validate.d.ts.map +1 -1
  80. package/dist/lib/engine/validate.js +106 -16
  81. package/dist/lib/engine/write-helpers.d.ts +69 -16
  82. package/dist/lib/engine/write-helpers.d.ts.map +1 -1
  83. package/dist/lib/engine/write-helpers.js +257 -105
  84. package/dist/lib/errors.d.ts +42 -10
  85. package/dist/lib/errors.d.ts.map +1 -1
  86. package/dist/lib/errors.js +69 -15
  87. package/dist/lib/nullable.d.ts +3 -2
  88. package/dist/lib/nullable.d.ts.map +1 -1
  89. package/dist/lib/nullable.js +14 -5
  90. package/dist/lib/read-access.d.ts +33 -21
  91. package/dist/lib/read-access.d.ts.map +1 -1
  92. package/dist/lib/read-access.js +42 -23
  93. package/dist/lib/schema/bulk-delete.d.ts +13 -7
  94. package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
  95. package/dist/lib/schema/bulk-delete.js +18 -8
  96. package/dist/lib/schema/bulk-upsert.d.ts +3 -3
  97. package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
  98. package/dist/lib/schema/bulk-upsert.js +9 -14
  99. package/dist/lib/schema/get.d.ts +1 -1
  100. package/dist/lib/schema/get.d.ts.map +1 -1
  101. package/dist/lib/schema/get.js +2 -2
  102. package/dist/lib/schema/helpers.d.ts +41 -23
  103. package/dist/lib/schema/helpers.d.ts.map +1 -1
  104. package/dist/lib/schema/helpers.js +80 -33
  105. package/dist/lib/schema/insert.d.ts +1 -1
  106. package/dist/lib/schema/insert.d.ts.map +1 -1
  107. package/dist/lib/schema/insert.js +12 -20
  108. package/dist/lib/schema/search.d.ts +2 -13
  109. package/dist/lib/schema/search.d.ts.map +1 -1
  110. package/dist/lib/schema/search.js +64 -61
  111. package/dist/lib/schema/update.d.ts +1 -1
  112. package/dist/lib/schema/update.d.ts.map +1 -1
  113. package/dist/lib/schema/update.js +6 -13
  114. package/dist/lib/sql-api.d.ts +47 -25
  115. package/dist/lib/sql-api.d.ts.map +1 -1
  116. package/dist/lib/sql-api.js +70 -27
  117. package/dist/lib/table-helpers.d.ts +92 -14
  118. package/dist/lib/table-helpers.d.ts.map +1 -1
  119. package/dist/lib/table-helpers.js +367 -128
  120. package/dist/lib/tenant.d.ts +16 -22
  121. package/dist/lib/tenant.d.ts.map +1 -1
  122. package/dist/lib/tenant.js +38 -54
  123. package/dist/lib/write-access.d.ts +15 -9
  124. package/dist/lib/write-access.d.ts.map +1 -1
  125. package/dist/lib/write-access.js +12 -4
  126. package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
  127. package/dist/routes/auto/agent-manifest.routes.js +2 -2
  128. package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
  129. package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
  130. package/dist/routes/auto/bulk-delete.routes.js +1 -7
  131. package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
  132. package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
  133. package/dist/routes/auto/bulk-upsert.routes.js +2 -2
  134. package/dist/routes/auto/delete.routes.d.ts +2 -2
  135. package/dist/routes/auto/delete.routes.d.ts.map +1 -1
  136. package/dist/routes/auto/delete.routes.js +8 -10
  137. package/dist/routes/auto/get.routes.d.ts +2 -2
  138. package/dist/routes/auto/get.routes.d.ts.map +1 -1
  139. package/dist/routes/auto/get.routes.js +5 -5
  140. package/dist/routes/auto/insert.routes.d.ts +2 -2
  141. package/dist/routes/auto/insert.routes.d.ts.map +1 -1
  142. package/dist/routes/auto/insert.routes.js +1 -7
  143. package/dist/routes/auto/plugin.d.ts +6 -0
  144. package/dist/routes/auto/plugin.d.ts.map +1 -1
  145. package/dist/routes/auto/plugin.js +60 -36
  146. package/dist/routes/auto/route-helpers.d.ts +26 -12
  147. package/dist/routes/auto/route-helpers.d.ts.map +1 -1
  148. package/dist/routes/auto/route-helpers.js +50 -19
  149. package/dist/routes/auto/search.routes.d.ts +2 -2
  150. package/dist/routes/auto/search.routes.d.ts.map +1 -1
  151. package/dist/routes/auto/search.routes.js +36 -24
  152. package/dist/routes/auto/update.routes.d.ts +2 -2
  153. package/dist/routes/auto/update.routes.d.ts.map +1 -1
  154. package/dist/routes/auto/update.routes.js +1 -8
  155. package/dist/routes/sql-api-decorator.d.ts +30 -12
  156. package/dist/routes/sql-api-decorator.d.ts.map +1 -1
  157. package/dist/routes/sql-api-decorator.js +44 -27
  158. package/dist/types/cli.d.ts +17 -6
  159. package/dist/types/cli.d.ts.map +1 -1
  160. package/dist/types/computed.d.ts +1 -1
  161. package/dist/types/computed.d.ts.map +1 -1
  162. package/dist/types/conditions.d.ts +3 -1
  163. package/dist/types/conditions.d.ts.map +1 -1
  164. package/dist/types/db.d.ts +44 -4
  165. package/dist/types/db.d.ts.map +1 -1
  166. package/dist/types/dml.d.ts +26 -17
  167. package/dist/types/dml.d.ts.map +1 -1
  168. package/dist/types/hooks.d.ts +62 -0
  169. package/dist/types/hooks.d.ts.map +1 -0
  170. package/dist/types/hooks.js +1 -0
  171. package/dist/types/join.d.ts +25 -8
  172. package/dist/types/join.d.ts.map +1 -1
  173. package/dist/types/plugin.d.ts +58 -19
  174. package/dist/types/plugin.d.ts.map +1 -1
  175. package/dist/types/plugin.js +2 -0
  176. package/dist/types/request.d.ts +2 -2
  177. package/dist/types/schema.d.ts +3 -3
  178. package/dist/types/schema.d.ts.map +1 -1
  179. package/dist/types/search.d.ts +28 -13
  180. package/dist/types/search.d.ts.map +1 -1
  181. package/dist/types/search.js +2 -1
  182. package/dist/types/table.d.ts +109 -94
  183. package/dist/types/table.d.ts.map +1 -1
  184. package/dist/types/table.js +7 -2
  185. package/dist/types/tenant.d.ts +28 -2
  186. package/dist/types/tenant.d.ts.map +1 -1
  187. package/dist/types/tenant.js +7 -1
  188. package/dist/types/validation.d.ts +69 -13
  189. package/dist/types/validation.d.ts.map +1 -1
  190. package/dist/types.d.ts +1 -0
  191. package/dist/types.d.ts.map +1 -1
  192. package/dist/types.js +1 -0
  193. package/docs/GLOSSARY.md +11 -5
  194. package/docs/adr/0003-bulk-not-transactional.md +2 -1
  195. package/docs/adr/0006-raw-db-errors.md +2 -1
  196. package/docs/adr/0013-sanitized-db-errors.md +2 -1
  197. package/docs/adr/0014-what-follows-a-write-join.md +1 -1
  198. package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
  199. package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
  200. package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
  201. package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
  202. package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
  203. package/docs/adr/0027-the-1-0-contract.md +74 -0
  204. package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
  205. package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
  206. package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
  207. package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
  208. package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
  209. package/docs/adr/README.md +12 -1
  210. package/docs/upgrading/0.x.md +906 -0
  211. package/docs/upgrading/1.0.md +628 -0
  212. package/package.json +4 -5
@@ -0,0 +1,96 @@
1
+ # 0029. A write names its child rows by action — `upsert`, `delete`, `replace` — and answers with what happened
2
+
3
+ - **Status**: accepted (narrows the scope of [0003](./0003-bulk-not-transactional.md) for one item's children)
4
+ - **Date**: 2026-11-16
5
+
6
+ ## Context
7
+
8
+ A write join writes child rows next to the main row. Through 1.0's development the request
9
+ named them `secondaries` (rows to write) and `deletions` (rows to delete), the same nouns the
10
+ response used for what was written and removed.
11
+
12
+ To set the tags of a post to exactly `{ 3 }`, a client had to know which tags the post has
13
+ now and send the difference: tag 3 under `secondaries`, the others under `deletions`. That is a
14
+ read before every write, and a race between the two. For many relations the request does
15
+ hold the whole set — the tags of a post, the members of a group, the translations of a
16
+ product — and a consumer migrating to 1.0 asked for it, atomic with the audit row its
17
+ after-hook writes.
18
+
19
+ Two shapes were tried before this one:
20
+
21
+ - **`replace: true` on the relation.** `secondaries` silently meant "the complete set" for that
22
+ alias: the meaning of a request lived in a server config the client cannot see, adding a
23
+ single row became impossible without sending them all, and `deletions` had to be refused for
24
+ the alias.
25
+ - **A third request key next to `secondaries` and `deletions`.** It removed the ambiguity, but
26
+ read as two nouns and a verb: `secondaries` names rows, not what to do with them.
27
+
28
+ ## Decision
29
+
30
+ **A write request names its child rows in one section per action, by write alias:**
31
+
32
+ - `upsert` — write these rows: inserted, or upserted on the relation's `upsertKey`. The other
33
+ child rows stay.
34
+ - `delete` — delete these rows, named by their key; the FK to the main row is filled in, so
35
+ only children of this main row are reached. Update and bulk upsert only.
36
+ - `replace` — these are all the child rows: the rows sent are upserted on the relation's
37
+ `upsertKey`, every other child row of the main row is deleted. `[]` deletes them all.
38
+
39
+ **The answer keeps nouns: `secondaries` for the rows written, `deletions` for the rows
40
+ removed** — in the response and in `afterInsert`/`afterUpdate`. The request says what to do,
41
+ the response what happened; a `replace` shows up in both.
42
+
43
+ `validate` and `validateBulk` receive the request's sections under the request's names
44
+ (`{ main, upsert, replace }`), because the paths they return point into the request
45
+ (`upsert.tags.0.tagId`).
46
+
47
+ The rules that follow:
48
+
49
+ - **`replace` needs the relation's `upsertKey`**: the key is what tells a child row the request
50
+ sends from one it no longer does. Without one, `replace.<alias>` is a 400 `unknown_field`,
51
+ and the request schema does not offer it.
52
+ - **An alias sits in one section.** In `replace` and in `upsert` or `delete` too, it is a 400
53
+ `conflicting_alias` at `replace.<alias>`: the set already says what stays and what goes.
54
+ Different aliases combine freely.
55
+ - **Upsert, then delete the rest — never delete everything and insert.** The rows that stay
56
+ keep their identity, their generated columns and their own children, which deleting and
57
+ re-inserting them would cascade to.
58
+ - **The child table's tenant guard joins the DELETE** (`buildTenantRowGuard`, as for `delete`):
59
+ a child row of another tenant pointing at the same main row is never touched.
60
+ - **Insert and update run their child rows and after-hook in their transaction.**
61
+ - **A bulk upsert stays without a transaction (ADR 0003), but an item with a `replace` runs its
62
+ child rows and `afterInsert` in a transaction of its own.** The batch is many operations,
63
+ each with its own outcome; within one item, a replacement is one change and must not end
64
+ half done. The item's main row is written by the batch's single statement before that, so it
65
+ is outside the item's transaction.
66
+ - **`secondaries` and `deletions` in a request are a 400 `retired_key`** naming the section
67
+ that replaced them (ADR 0027: refused, not ignored).
68
+
69
+ ## Alternatives considered
70
+
71
+ - **`replace: true` on the relation.** One meaning per alias, decided by the server — but
72
+ invisible in the request, and it took away the ability to add or remove a single row.
73
+ - **A request flag** (`replace: ['tags']` next to `secondaries`). The same key would mean "add"
74
+ or "all of them" depending on another key, and a client forgetting the flag silently keeps
75
+ rows it meant to drop.
76
+ - **`secondaries` / `deletions` / `replacements`.** Backward compatible, but the trio mixes a
77
+ noun for rows with nouns for actions; the request keeps reading like a response.
78
+ - **Per-alias operations** (`secondaries: { tags: { add, remove, set } }`). Every alias would
79
+ carry its own little grammar, and the error paths would grow a level; one section per action
80
+ reads the same for every alias.
81
+ - **Delete every child row, then insert the ones sent.** It changes the identity of the rows
82
+ that stay, resets their generated columns and cascades to their children; it also works
83
+ without an `upsertKey`, hiding a relation whose rows cannot be told apart.
84
+ - **A transaction for the whole bulk upsert**, or none for an item either. The first is ADR
85
+ 0003's rejected option; the second leaves an item with the new rows written and the old ones
86
+ still there, a state no request describes.
87
+
88
+ ## Consequences
89
+
90
+ - A client sets a relation to an exact set in one request, without reading it first, and can
91
+ still add or remove single rows with `upsert` and `delete`.
92
+ - Every 1.0 client renames `secondaries` to `upsert` and `deletions` to `delete` in its write
93
+ bodies; the responses and the after-hooks are unchanged.
94
+ - The manifest gives each write join its `upsertKey`: present, the alias takes `replace`.
95
+ - A bulk upsert with `replace` items opens one transaction per such item, so it needs an
96
+ adapter with `connect()` (ADR 0023) even though the batch itself has none.
@@ -0,0 +1,117 @@
1
+ # 0030. A child row is validated by its own table — a write join runs the child's `validate`
2
+
3
+ - **Status**: accepted — supersedes the `validate` row of [0014](./0014-what-follows-a-write-join.md)
4
+ - **Date**: 2026-11-16
5
+
6
+ ## Context
7
+
8
+ ADR 0014 decided what a write join runs on a child row: the child table's transforms
9
+ (`insertExclude`, `beforeInsert`, `tenantScope`), not its verdicts (`validate`, `afterInsert`).
10
+ It rejected running the child's `validate` *"for now, not on principle"*: it would have made a
11
+ host's write start failing on child rows accepted the day before, for consumers that never
12
+ opted in.
13
+
14
+ That cost was real while 0.x consumers were upgrading minor by minor. Before 1.0 is published
15
+ it is not: every consumer migrates once (ADR 0027), and a rule that changes behavior is
16
+ cheapest now.
17
+
18
+ Meanwhile the gap has a cost of its own. A consumer avoids write joins for its link tables
19
+ precisely because a child row written through one skips its table's `validate`: the rules
20
+ `article_info` enforces on `POST /rest/article_info` do not hold when the same row arrives
21
+ under `upsert.info` of `POST /rest/article`. So the rule has to be written twice — once on the
22
+ child, once in the host's `validate` — or the consumer gives up the write join, and with it
23
+ `replace` (ADR 0029) and the atomic write.
24
+
25
+ The same consumer gave a second reason, that the child's `beforeInsert` did not see the FK to
26
+ the main row. That one is already fixed, within 0014: the FK is filled in before the hook, and
27
+ again after it, so it still always wins.
28
+
29
+ ## Decision
30
+
31
+ **A write join runs the child table's `validate` on every child row it writes** — those of
32
+ `upsert` and of `replace`, not those of `delete`, which removes rows and renders no verdict on
33
+ them.
34
+
35
+ - **It runs before any SQL, after the host's `validate`.** A 400 writes nothing, as for every
36
+ other validation; every child row is checked and all their errors answered together.
37
+ - **The child's `validate` receives the child row as `main`**, camelCase, as the request sent
38
+ it, with the FK to the main row filled in when the main row's key is in the request — an
39
+ update, or an insert naming its key — and absent when the database generates it.
40
+ - **It also receives `parent: { alias, main }`**: the alias the row was sent under and the main
41
+ row of the request, as sent. `parent` is absent on the table's own routes, so it is both data
42
+ — a rule on the parent's fields needs no FK and no query — and the signal that the row is a
43
+ child, whose FK the engine fills in.
44
+ - **Its paths are re-rooted into the request.** The child returns paths of its own grammar
45
+ (`main.title`, or `''`); the engine answers them at `upsert.info.0.title` (`replace.…` for a
46
+ replace, `<item>.upsert.…` in a bulk upsert, `upsert.info.0` for `''`). Any other path is the
47
+ hook's programming error, a 500 naming it, as a malformed `validate` result already is.
48
+ - **When the child declares `validateBulk`, it replaces the per-row `validate`**, called once
49
+ per alias and main row with the rows as `items` and the same `parent` — the rule of ADR 0025,
50
+ one level down. Its `items.<j>.main.<field>` paths are re-rooted the same way.
51
+ - **The child's `afterInsert` still does not run.** It fires side effects; running N of them
52
+ inside the host's transaction, unordered against the host's own `afterInsert`, is the
53
+ decision 0014 rejected and nothing here changes it.
54
+
55
+ A child row then goes through the single-insert pipeline of ADR 0005, with the FK the engine's:
56
+ `validate` on the row as sent, before any SQL; then, at write time, the `insertExclude` strip,
57
+ the FK fill, `beforeInsert`, the FK fill again, `tenantScope`, the write.
58
+
59
+ ### The FK on an insert with a generated parent key — accepted, with examples
60
+
61
+ On `POST /rest/article` with a database-generated `id`, the article does not exist when the
62
+ child's `validate` runs, so `main.articleId` is absent. In practice:
63
+
64
+ ```ts
65
+ // article_info.validate
66
+ validate: async ({ db, main, parent }) => {
67
+ const errors: ValidatorResult = [];
68
+ // 1. Input rules: hold everywhere, the FK is not involved.
69
+ if (!main.title) errors.push({ path: 'main.title', code: 'required' });
70
+ // 2. The FK is required on the table's own routes; as a child, the engine fills it in.
71
+ if (!parent && !main.articleId) errors.push({ path: 'main.articleId', code: 'required' });
72
+ // 3. A rule querying the parent's rows: absent FK means a new article, which has none yet.
73
+ if (main.articleId && await slugTaken(db, main)) errors.push({ path: 'main.slug', code: 'duplicate' });
74
+ // 4. A rule on the parent's fields: `parent` carries them, no FK needed.
75
+ if (parent?.main.status === 'published' && !main.summary) errors.push({ path: 'main.summary', code: 'required' });
76
+ return errors;
77
+ },
78
+ ```
79
+
80
+ - Input rules (1) and rules on the parent's fields (4) work on every path.
81
+ - A required FK (2) is the one rule that would fail a correct request; `parent` tells the child
82
+ it is one.
83
+ - A rule that reads the parent's existing rows (3) has nothing to read when the parent is new:
84
+ skipping it without the FK is the right answer. A conflict between rows of the same request
85
+ is the host's `validate`'s, or the child's `validateBulk`'s, which see them all.
86
+
87
+ ## Alternatives considered
88
+
89
+ - **Keep 0014 as is.** The host's `validate` already receives the child rows; a rule can be
90
+ written there. But it must be written once per host, and the table that owns the data is not
91
+ the one that guards it — the same misplacement 0014 rejected for `beforeSecondaryInsert`.
92
+ - **Run the child's `validate` inside the transaction, after the main row is written**, so the
93
+ FK is always known. A 400 would roll back and still write nothing on insert and update — but
94
+ not in a bulk upsert, whose main rows are written by one statement outside any transaction
95
+ (ADR 0003): a child's 400 would leave them written. Validation before any SQL is the one rule
96
+ that holds on every path, and the FK it cannot see is the FK nothing needs yet.
97
+ - **No `parent`; a child checks `main.articleId` and lives with the false 400.** It forces a
98
+ table to choose between guarding its own routes and accepting its rows as a child.
99
+ - **A flag instead of `parent`** (`ctx.asChild: true`). It says the row is a child but not
100
+ whose; `parent` says both, under one name.
101
+ - **An opt-in on the relation or the table** (`validateAsChild`). A second way for a table's
102
+ rule to apply or not, decided away from the rule; a consumer forgetting it keeps today's gap.
103
+ - **Run `afterInsert` too, for symmetry.** Rejected by 0014 for its side effects and ordering;
104
+ `validate` has neither.
105
+
106
+ ## Consequences
107
+
108
+ - A rule declared on a table holds wherever its rows are written: its own routes, a write join,
109
+ a bulk upsert.
110
+ - A host's write can fail with a 400 at `upsert.<alias>.<i>.<field>` raised by the child's
111
+ table; clients already handle those paths.
112
+ - A child `validate` that checks the FK as required must guard it with `!parent`, or it refuses
113
+ correct writes through the parent.
114
+ - A child `validate` that queries the database runs once per child row; a table expecting many
115
+ rows per write declares `validateBulk`.
116
+ - `ValidateContext` and `BulkValidateContext` gain `parent?: { alias, main }`; the glossary
117
+ names it.
@@ -0,0 +1,58 @@
1
+ # 0031. An upsert key under `insertExclude` addresses an existing row — it never names a new one
2
+
3
+ - **Status**: accepted
4
+ - **Date**: 2026-11-17
5
+
6
+ ## Context
7
+
8
+ Two declarations meet on every generated table that upserts by its primary key:
9
+
10
+ - `insertExclude: ['id']` — the CLI writes it for every identity/auto-increment PK, and the
11
+ docs say it must be there: the client never picks the key of a new row (ADR 0005);
12
+ - `upsertKey: ['id']` — the rows that carry an id update that row, those without one are
13
+ inserted (ADR 0021).
14
+
15
+ `insertExclude` stripped the field from the client payload before the upsert, the key
16
+ included. So every row sent with an id reached the database without one and was inserted
17
+ again under a new key: a bulk sync by id silently duplicated every row it meant to update, and
18
+ a write join with `upsertKey: ['id']` on a child table generated by the CLI did the same to its
19
+ child rows. Nothing failed — unless another unique column of the copy collided, as a 500.
20
+
21
+ ## Decision
22
+
23
+ **The fields of the upsert key stay on the rows that carry them, and such a key may only name
24
+ an existing row.** For a table — or a write join — whose `upsertKey` has a field the target
25
+ table lists under `insertExclude`:
26
+
27
+ - a row **without** the key is a plain insert, the key generated by the database or assigned
28
+ by `beforeInsert` — as before;
29
+ - a row whose key the **client sent** updates the row that key names. One `SELECT` per
30
+ statement probes those keys before the upsert; a key naming no row is a **400 `not_found`**
31
+ at its path — `main.<field>`, `<i>.main.<field>` in a bulk, `[<i>.]<section>.<alias>.<j>.<field>`
32
+ for a child row — and nothing of that statement is written;
33
+ - a key `beforeInsert` assigned is not probed: the hook names a new row.
34
+
35
+ A key field outside `insertExclude` is unchanged: the client may still create a row under the
36
+ key it sends (ADR 0021).
37
+
38
+ ## Alternatives considered
39
+
40
+ - **The key wins** — never strip an upsert key field, and let a key naming no row insert one
41
+ under that key. Rejected: it gives the client the choice `insertExclude` exists to deny, and
42
+ on PostgreSQL a client-chosen id is a later collision with the sequence.
43
+ - **Refuse the combination in `defineTable`** — rejected: the combination is what the CLI
44
+ generates and what an id-based sync needs; refusing it would push consumers to drop
45
+ `insertExclude` and accept client-chosen ids.
46
+ - **Probe inside the upsert statement** (update-only branch) — not expressible as one
47
+ statement on PostgreSQL, where `ON CONFLICT` always inserts on a miss.
48
+
49
+ ## Consequences
50
+
51
+ - An upsert-by-key on such a table costs one more `SELECT` per statement when rows carry the
52
+ key; none when no row does. On MySQL and MariaDB it precedes the probe the upsert already
53
+ runs (ADR 0021).
54
+ - The probe ignores the tenant: a key naming another tenant's row passes it and is refused
55
+ by the tenant conflict guard with a 403, as before.
56
+ - In a bulk upsert (not transactional, ADR 0003) the main rows are probed before any is
57
+ written; a child row is probed when its item's children are written, like `missing_key`.
58
+ - A new engine code, `not_found`, in the 400 `fields`.
@@ -0,0 +1,56 @@
1
+ # 0032. `tenantScope` names schema fields, resolved to their columns
2
+
3
+ - **Status**: accepted
4
+ - **Date**: 2026-11-18
5
+
6
+ ## Context
7
+
8
+ Every key of a table config names schema fields — `primary`, `readExclude`, `upsertKey`,
9
+ `defaultOrder`, the fields of `buildRelation` — except `tenantScope`, which named real DB
10
+ columns. The reasons given were that the scope is applied to the SQL, after the payload has been
11
+ converted, and that `through.foreignField` belongs to a parent table that may have no generated
12
+ schema. A startup check refused a field name whose column differs, since that was the likely
13
+ mistake.
14
+
15
+ Neither reason holds. Every name in a scope belongs to a table whose schema the scope already
16
+ carries: `column`, `anyOf` and `through.localField` to the table's own, the indirect `column`
17
+ and `through.foreignField` to `through.schema`, which is required. And the exception produced
18
+ the mistake it guarded against: the CLI's own `tables` template wrote the FK field
19
+ (`localField: 'customerId'`), which `defineTable` then refused on a snake_case database.
20
+
21
+ ## Decision
22
+
23
+ **`tenantScope` names schema fields, each resolved to its column through the schema of the table
24
+ it lives on.** The column of one of its fields is accepted as written; any other name is refused
25
+ by `defineTable`.
26
+
27
+ *Amended the same day, before 1.0 shipped:* the first version took any name the schema did not
28
+ carry as a column, to keep a hand-written schema omitting the tenant column working. That let a
29
+ misspelled field pass startup and fail as a 500 on the first request, and nothing relied on the
30
+ omitted column but the one test written to pin it. A scope now names what its schema knows.
31
+
32
+ - The resolution happens where the scope is read (`resolvedTenantScope`), so a table config
33
+ built without `defineTable` gets it too; the engines see columns, as before.
34
+ - A scope naming real columns keeps working: the column of a field is taken as written.
35
+ - A name that is neither a field nor the column of one is refused at startup, naming the scope
36
+ key, the table whose schema was searched and its fields (`checkScopeNames`). The tenant column
37
+ must be in the schema: to keep it out of responses, use `readExclude`, not `excludeColumns`.
38
+ - An `anyOf` scope that names one column twice — once by its field, once by its column — is
39
+ refused by `defineTable`, like any repeated entry.
40
+
41
+ ## Alternatives considered
42
+
43
+ - **Keep columns, fix only the CLI template** — rejected: it keeps the one exception to the
44
+ naming rule, the one that produced the template's mistake.
45
+ - **Fields only, refusing a name that is not a field** — rejected: every 0.x scope naming
46
+ columns would have to be rewritten, for no gain in safety over accepting the columns of fields.
47
+ - **Any name the schema lacks taken as a column** — the first version of this decision, replaced:
48
+ it caught no misspelling, for a case (a schema omitting the tenant column) nothing relied on.
49
+
50
+ ## Consequences
51
+
52
+ - The startup check refusing a field name whose column differs is gone: that name is now the
53
+ documented form.
54
+ - A misspelled field or column is caught at startup, as it was not in 0.x.
55
+ - The docs and the CLI template use field names. A scope naming the columns of its fields needs no
56
+ edit; one naming a column its schema omits does, and the upgrade guide says so.
@@ -28,7 +28,7 @@ not by editing history.
28
28
  | [0011](./0011-join-fields-allowlist.md) | Per-relation field restriction is an allowlist, not a blocklist |
29
29
  | [0012](./0012-anti-duplication-tooling.md) | Repository rules are enforced by executable gates, not by documentation |
30
30
  | [0013](./0013-sanitized-db-errors.md) | Database error messages are sanitized on the wire by default (narrows 0006) |
31
- | [0014](./0014-what-follows-a-write-join.md) | A secondary runs the child table's transform, not its verdicts |
31
+ | [0014](./0014-what-follows-a-write-join.md) | A secondary runs the child table's transform, not its verdicts (its `validate` row superseded by 0030) |
32
32
  | [0015](./0015-non-writable-columns.md) | A column the database computes is not writable — `writeExclude` (narrows 0004) |
33
33
  | [0016](./0016-a-view-is-a-table-config.md) | A view is a table config — the generator refuses to invent its primary key |
34
34
  | [0017](./0017-the-schema-is-the-contract.md) | The database schema is the API contract — by default, and only by default |
@@ -36,6 +36,17 @@ not by editing history.
36
36
  | [0019](./0019-column-exclusion-is-generation-time-config.md) | Removing a column from the API is generation-time config — `excludeColumns`, never a Schema edit |
37
37
  | [0020](./0020-no-conditional-or-mass-update-route.md) | No conditional or mass update route — a predicate write is a custom route |
38
38
  | [0021](./0021-upsert-targets-a-verified-unique-key.md) | An upsert targets a unique key verified at startup — MySQL and MariaDB upsert by key, not by `ON DUPLICATE KEY` |
39
+ | [0022](./0022-stay-on-0x-while-every-consumer-is-first-party.md) | Stay on 0.x while every consumer is first-party — a breaking change bumps the minor, never the patch (superseded by 0027) |
40
+ | [0023](./0023-a-write-runs-in-a-transaction-or-not-at-all.md) | A write runs in a transaction or not at all — `withTransaction` requires `connect()` (narrows 0003's context) |
41
+ | [0024](./0024-the-consumer-maps-driver-codes-through-dberrors.md) | The consumer maps driver error codes through `dbErrors` — the plugin ships no mapping (narrows 0006, 0013) |
42
+ | [0025](./0025-validatebulk-replaces-validate-in-a-bulk-upsert.md) | `validateBulk` replaces `validate` in a bulk upsert — one call for the batch, not one per item |
43
+ | [0026](./0026-update-carries-its-primary-key-in-main.md) | An update carries its primary key in `main` — `PUT /rest/:table` has no `:id` |
44
+ | [0027](./0027-the-1-0-contract.md) | The 1.0 contract — what is public, how it changes, and the rules the API keeps (supersedes 0022) |
45
+ | [0028](./0028-select-star-is-the-default-projection.md) | `'*'` in `select` is the default projection — a computed field is asked for without copying the readable set |
46
+ | [0029](./0029-a-write-names-its-child-rows-by-action.md) | A write names its child rows by action — `upsert`, `delete`, `replace` — and answers with what happened (narrows 0003 for one item's children) |
47
+ | [0030](./0030-a-child-row-is-validated-by-its-own-table.md) | A child row is validated by its own table — a write join runs the child's `validate`, with `parent` (supersedes part of 0014) |
48
+ | [0031](./0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md) | An upsert key under `insertExclude` addresses an existing row — it never names a new one |
49
+ | [0032](./0032-tenant-scope-names-schema-fields.md) | `tenantScope` names schema fields, resolved to their columns |
39
50
 
40
51
  ## When to write one
41
52