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.
- package/AGENTS.md +5 -5
- package/AGENTS_BACKEND.md +166 -130
- package/AGENTS_FRONTEND.md +60 -38
- package/BREAKING_CHANGES.md +9 -893
- package/CHANGELOG.md +258 -15
- package/README.md +71 -45
- package/dist/bin/generate-schema.js +12 -12
- package/dist/bin/generate-tables.js +1 -2
- package/dist/bin/utils.d.ts +2 -6
- package/dist/bin/utils.d.ts.map +1 -1
- package/dist/bin/utils.js +13 -33
- package/dist/index.d.ts +13 -33
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -37
- package/dist/lib/adapters/mysql-adapter.d.ts +5 -2
- package/dist/lib/adapters/mysql-adapter.d.ts.map +1 -1
- package/dist/lib/adapters/pg-adapter.d.ts +5 -2
- package/dist/lib/adapters/pg-adapter.d.ts.map +1 -1
- package/dist/lib/agent/manifest.d.ts +27 -10
- package/dist/lib/agent/manifest.d.ts.map +1 -1
- package/dist/lib/agent/manifest.js +43 -26
- package/dist/lib/agent/tool-schemas.d.ts +5 -4
- package/dist/lib/agent/tool-schemas.d.ts.map +1 -1
- package/dist/lib/agent/tool-schemas.js +5 -5
- package/dist/lib/cli/config.d.ts +37 -2
- package/dist/lib/cli/config.d.ts.map +1 -1
- package/dist/lib/cli/config.js +106 -16
- package/dist/lib/cli/mysql-introspect.d.ts +6 -1
- package/dist/lib/cli/mysql-introspect.d.ts.map +1 -1
- package/dist/lib/cli/mysql-introspect.js +15 -15
- package/dist/lib/cli/pg-introspect.d.ts +0 -1
- package/dist/lib/cli/pg-introspect.d.ts.map +1 -1
- package/dist/lib/cli/pg-introspect.js +2 -13
- package/dist/lib/cli/tables-codegen.d.ts +0 -4
- package/dist/lib/cli/tables-codegen.d.ts.map +1 -1
- package/dist/lib/cli/tables-codegen.js +24 -87
- package/dist/lib/db.d.ts +42 -17
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +114 -40
- package/dist/lib/dialect.d.ts +5 -0
- package/dist/lib/dialect.d.ts.map +1 -1
- package/dist/lib/dialect.js +3 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts +5 -0
- package/dist/lib/engine/bulk/bulk-delete.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-delete.js +66 -30
- package/dist/lib/engine/bulk/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/engine/bulk/bulk-upsert.js +45 -26
- package/dist/lib/engine/read-hooks.d.ts +3 -3
- package/dist/lib/engine/read-hooks.d.ts.map +1 -1
- package/dist/lib/engine/read-hooks.js +3 -3
- package/dist/lib/engine/rest/delete.d.ts.map +1 -1
- package/dist/lib/engine/rest/delete.js +12 -18
- package/dist/lib/engine/rest/get.js +8 -8
- package/dist/lib/engine/rest/insert.d.ts.map +1 -1
- package/dist/lib/engine/rest/insert.js +31 -18
- package/dist/lib/engine/rest/update.d.ts.map +1 -1
- package/dist/lib/engine/rest/update.js +34 -17
- package/dist/lib/engine/search/aggregations.d.ts +3 -3
- package/dist/lib/engine/search/aggregations.d.ts.map +1 -1
- package/dist/lib/engine/search/aggregations.js +20 -16
- package/dist/lib/engine/search/conditions.d.ts +9 -5
- package/dist/lib/engine/search/conditions.d.ts.map +1 -1
- package/dist/lib/engine/search/conditions.js +31 -20
- package/dist/lib/engine/search/fields.d.ts +44 -11
- package/dist/lib/engine/search/fields.d.ts.map +1 -1
- package/dist/lib/engine/search/fields.js +94 -28
- package/dist/lib/engine/search/join-families.d.ts +7 -7
- package/dist/lib/engine/search/join-families.d.ts.map +1 -1
- package/dist/lib/engine/search/join-families.js +84 -75
- package/dist/lib/engine/search/joins.d.ts +15 -7
- package/dist/lib/engine/search/joins.d.ts.map +1 -1
- package/dist/lib/engine/search/joins.js +23 -13
- package/dist/lib/engine/search/order-by.d.ts +11 -12
- package/dist/lib/engine/search/order-by.d.ts.map +1 -1
- package/dist/lib/engine/search/order-by.js +24 -28
- package/dist/lib/engine/search/search.d.ts.map +1 -1
- package/dist/lib/engine/search/search.js +111 -62
- package/dist/lib/engine/validate.d.ts +21 -3
- package/dist/lib/engine/validate.d.ts.map +1 -1
- package/dist/lib/engine/validate.js +106 -16
- package/dist/lib/engine/write-helpers.d.ts +69 -16
- package/dist/lib/engine/write-helpers.d.ts.map +1 -1
- package/dist/lib/engine/write-helpers.js +257 -105
- package/dist/lib/errors.d.ts +42 -10
- package/dist/lib/errors.d.ts.map +1 -1
- package/dist/lib/errors.js +69 -15
- package/dist/lib/nullable.d.ts +3 -2
- package/dist/lib/nullable.d.ts.map +1 -1
- package/dist/lib/nullable.js +14 -5
- package/dist/lib/read-access.d.ts +33 -21
- package/dist/lib/read-access.d.ts.map +1 -1
- package/dist/lib/read-access.js +42 -23
- package/dist/lib/schema/bulk-delete.d.ts +13 -7
- package/dist/lib/schema/bulk-delete.d.ts.map +1 -1
- package/dist/lib/schema/bulk-delete.js +18 -8
- package/dist/lib/schema/bulk-upsert.d.ts +3 -3
- package/dist/lib/schema/bulk-upsert.d.ts.map +1 -1
- package/dist/lib/schema/bulk-upsert.js +9 -14
- package/dist/lib/schema/get.d.ts +1 -1
- package/dist/lib/schema/get.d.ts.map +1 -1
- package/dist/lib/schema/get.js +2 -2
- package/dist/lib/schema/helpers.d.ts +41 -23
- package/dist/lib/schema/helpers.d.ts.map +1 -1
- package/dist/lib/schema/helpers.js +80 -33
- package/dist/lib/schema/insert.d.ts +1 -1
- package/dist/lib/schema/insert.d.ts.map +1 -1
- package/dist/lib/schema/insert.js +12 -20
- package/dist/lib/schema/search.d.ts +2 -13
- package/dist/lib/schema/search.d.ts.map +1 -1
- package/dist/lib/schema/search.js +64 -61
- package/dist/lib/schema/update.d.ts +1 -1
- package/dist/lib/schema/update.d.ts.map +1 -1
- package/dist/lib/schema/update.js +6 -13
- package/dist/lib/sql-api.d.ts +47 -25
- package/dist/lib/sql-api.d.ts.map +1 -1
- package/dist/lib/sql-api.js +70 -27
- package/dist/lib/table-helpers.d.ts +92 -14
- package/dist/lib/table-helpers.d.ts.map +1 -1
- package/dist/lib/table-helpers.js +367 -128
- package/dist/lib/tenant.d.ts +16 -22
- package/dist/lib/tenant.d.ts.map +1 -1
- package/dist/lib/tenant.js +38 -54
- package/dist/lib/write-access.d.ts +15 -9
- package/dist/lib/write-access.d.ts.map +1 -1
- package/dist/lib/write-access.js +12 -4
- package/dist/routes/auto/agent-manifest.routes.d.ts +1 -1
- package/dist/routes/auto/agent-manifest.routes.js +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-delete.routes.js +1 -7
- package/dist/routes/auto/bulk-upsert.routes.d.ts +2 -2
- package/dist/routes/auto/bulk-upsert.routes.d.ts.map +1 -1
- package/dist/routes/auto/bulk-upsert.routes.js +2 -2
- package/dist/routes/auto/delete.routes.d.ts +2 -2
- package/dist/routes/auto/delete.routes.d.ts.map +1 -1
- package/dist/routes/auto/delete.routes.js +8 -10
- package/dist/routes/auto/get.routes.d.ts +2 -2
- package/dist/routes/auto/get.routes.d.ts.map +1 -1
- package/dist/routes/auto/get.routes.js +5 -5
- package/dist/routes/auto/insert.routes.d.ts +2 -2
- package/dist/routes/auto/insert.routes.d.ts.map +1 -1
- package/dist/routes/auto/insert.routes.js +1 -7
- package/dist/routes/auto/plugin.d.ts +6 -0
- package/dist/routes/auto/plugin.d.ts.map +1 -1
- package/dist/routes/auto/plugin.js +60 -36
- package/dist/routes/auto/route-helpers.d.ts +26 -12
- package/dist/routes/auto/route-helpers.d.ts.map +1 -1
- package/dist/routes/auto/route-helpers.js +50 -19
- package/dist/routes/auto/search.routes.d.ts +2 -2
- package/dist/routes/auto/search.routes.d.ts.map +1 -1
- package/dist/routes/auto/search.routes.js +36 -24
- package/dist/routes/auto/update.routes.d.ts +2 -2
- package/dist/routes/auto/update.routes.d.ts.map +1 -1
- package/dist/routes/auto/update.routes.js +1 -8
- package/dist/routes/sql-api-decorator.d.ts +30 -12
- package/dist/routes/sql-api-decorator.d.ts.map +1 -1
- package/dist/routes/sql-api-decorator.js +44 -27
- package/dist/types/cli.d.ts +17 -6
- package/dist/types/cli.d.ts.map +1 -1
- package/dist/types/computed.d.ts +1 -1
- package/dist/types/computed.d.ts.map +1 -1
- package/dist/types/conditions.d.ts +3 -1
- package/dist/types/conditions.d.ts.map +1 -1
- package/dist/types/db.d.ts +44 -4
- package/dist/types/db.d.ts.map +1 -1
- package/dist/types/dml.d.ts +26 -17
- package/dist/types/dml.d.ts.map +1 -1
- package/dist/types/hooks.d.ts +62 -0
- package/dist/types/hooks.d.ts.map +1 -0
- package/dist/types/hooks.js +1 -0
- package/dist/types/join.d.ts +25 -8
- package/dist/types/join.d.ts.map +1 -1
- package/dist/types/plugin.d.ts +58 -19
- package/dist/types/plugin.d.ts.map +1 -1
- package/dist/types/plugin.js +2 -0
- package/dist/types/request.d.ts +2 -2
- package/dist/types/schema.d.ts +3 -3
- package/dist/types/schema.d.ts.map +1 -1
- package/dist/types/search.d.ts +28 -13
- package/dist/types/search.d.ts.map +1 -1
- package/dist/types/search.js +2 -1
- package/dist/types/table.d.ts +109 -94
- package/dist/types/table.d.ts.map +1 -1
- package/dist/types/table.js +7 -2
- package/dist/types/tenant.d.ts +28 -2
- package/dist/types/tenant.d.ts.map +1 -1
- package/dist/types/tenant.js +7 -1
- package/dist/types/validation.d.ts +69 -13
- package/dist/types/validation.d.ts.map +1 -1
- package/dist/types.d.ts +1 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/docs/GLOSSARY.md +11 -5
- package/docs/adr/0003-bulk-not-transactional.md +2 -1
- package/docs/adr/0006-raw-db-errors.md +2 -1
- package/docs/adr/0013-sanitized-db-errors.md +2 -1
- package/docs/adr/0014-what-follows-a-write-join.md +1 -1
- package/docs/adr/0022-stay-on-0x-while-every-consumer-is-first-party.md +88 -0
- package/docs/adr/0023-a-write-runs-in-a-transaction-or-not-at-all.md +60 -0
- package/docs/adr/0024-the-consumer-maps-driver-codes-through-dberrors.md +78 -0
- package/docs/adr/0025-validatebulk-replaces-validate-in-a-bulk-upsert.md +46 -0
- package/docs/adr/0026-update-carries-its-primary-key-in-main.md +43 -0
- package/docs/adr/0027-the-1-0-contract.md +74 -0
- package/docs/adr/0028-select-star-is-the-default-projection.md +64 -0
- package/docs/adr/0029-a-write-names-its-child-rows-by-action.md +96 -0
- package/docs/adr/0030-a-child-row-is-validated-by-its-own-table.md +117 -0
- package/docs/adr/0031-an-insert-excluded-upsert-key-addresses-an-existing-row.md +58 -0
- package/docs/adr/0032-tenant-scope-names-schema-fields.md +56 -0
- package/docs/adr/README.md +12 -1
- package/docs/upgrading/0.x.md +906 -0
- package/docs/upgrading/1.0.md +628 -0
- 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.
|
package/docs/adr/README.md
CHANGED
|
@@ -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
|
|