fastify-auto-sqlapi 0.5.1 → 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 +246 -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 +93 -27
  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 -64
  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 +25 -16
  91. package/dist/lib/read-access.d.ts.map +1 -1
  92. package/dist/lib/read-access.js +33 -17
  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
package/AGENTS.md CHANGED
@@ -7,8 +7,9 @@ A Fastify plugin that generates REST CRUD endpoints (search, get, insert, update
7
7
  - Calling the API (fetch, list page, form, agent tool): AGENTS_FRONTEND.md, whole file. It is the complete request grammar.
8
8
  - This deployment's tables, fields and join aliases: `GET {prefix}/agent/manifest.md` (when `agentManifest` is on) or Swagger. The docs give the grammar, the manifest gives the vocabulary.
9
9
  - Setting up the plugin, configuring tables, joins, tenant scope, hooks, validation, querying from custom routes/scripts/jobs (`sqlApi`), raw SQL in hooks (`db`): AGENTS_BACKEND.md.
10
- - Migrating from the old join API (`joinFilters`, `joins`, `joinGroups`): BREAKING_CHANGES.md.
11
- - A behavior that looks wrong: docs/adr/ first. These include open-by-default `operations`, non-transactional bulk, always-updatable fields, raw DB errors, and joins not running the target's route guards. They are recorded decisions, not gaps.
10
+ - Upgrading from 0.x: docs/upgrading/1.0.md (0.5 → 1.0), docs/upgrading/0.x.md for older releases; BREAKING_CHANGES.md indexes them.
11
+ - A behavior that looks wrong: docs/adr/ first. These include open-by-default `operations`, non-transactional bulk, always-updatable fields, sanitized DB errors mapped only through `dbErrors`, and joins not running the target's route guards. They are recorded decisions, not gaps.
12
+ - The routes answer errors with their own handler: an application `setErrorHandler` never sees them, an `onError` hook does (AGENTS_BACKEND.md, Rules).
12
13
 
13
14
  These files are the contract. **Do not read the plugin's sources** (`node_modules/fastify-auto-sqlapi/dist/`): they are internal, carry no stability guarantee, and say nothing about which behaviors are deliberate. If the docs do not answer, say so and ask. Never copy an internal helper into consumer code.
14
15
 
@@ -25,10 +26,9 @@ This has two consequences:
25
26
 
26
27
  ## Naming
27
28
 
28
- - camelCase schema field names everywhere: request/response bodies, `defineTable` keys, `buildRelation`, hooks, validators, `sqlApi.*`.
29
+ - camelCase schema field names everywhere: request/response bodies, `defineTable` keys (`tenantScope` included), `buildRelation`, hooks, validators, `sqlApi.*`.
29
30
  - Real DB column names only where you address the database yourself:
30
31
  - `db.*` (QueryClient) record keys, `where` and `conflictKeys`, plus the real table name `Schema.tableName`;
31
- - `tenantScope` columns;
32
- - SQL you write (`extendedCondition`, computed `expr`), where columns come from `Schema.col('field')` / `qiCol('field')` and are never typed literally.
32
+ - SQL you write: in `extendedCondition` columns come from its `col('field')`, in a computed `expr` from `qiCol('field')`, both quoted and qualified for you; never typed literally.
33
33
 
34
34
  The generated Schema maps between the two, whether the DB uses snake_case or camelCase. Clients always send camelCase, including when anchoring an `anyOf` tenant write.
package/AGENTS_BACKEND.md CHANGED
@@ -1,39 +1,42 @@
1
1
  # fastify-auto-sqlapi — backend reference (LLM)
2
2
 
3
- Setting up the plugin and configuring tables. Client request grammar: AGENTS_FRONTEND.md. Migrating from `joinFilters`/`joins`/`joinGroups`: BREAKING_CHANGES.md.
3
+ Setting up the plugin and configuring tables. Client request grammar: AGENTS_FRONTEND.md. Upgrading from 0.x: docs/upgrading/1.0.md (index: BREAKING_CHANGES.md).
4
4
 
5
5
  ## Rules
6
6
 
7
- - Everything is a camelCase **schema field name** (request/response bodies, `defineTable` keys, hooks, `validate`, `sqlApi.*`, `buildRelation`). **Real DB column names** only where you talk to the database yourself: `db.*` (QueryClient), `tenantScope`, and any SQL string you write. Get them with `Schema.col('field')` / `qiCol('field')`, never type them: columns may be snake_case or camelCase, the generated Schema knows which.
7
+ - Everything is a camelCase **schema field name** (request/response bodies, `defineTable` keys — `tenantScope` included —, hooks, `validate`, `sqlApi.*`, `buildRelation`). **Real DB column names** only where you talk to the database yourself: `db.*` (QueryClient) and any SQL string you write. Get them with `col('field')` in `extendedCondition`, `qiCol('field')` in a computed field, `Schema.col('field')` (unquoted) for `db.*`, never type them: columns may be snake_case or camelCase, the generated Schema knows which.
8
8
  - `sqlApi` = high-level (camelCase, validation, hooks, tenant, joins, computed). `db` = the SQL layer under it (real names, none of that). Not interchangeable.
9
+ - **The routes answer their errors with their own handler: an application `app.setErrorHandler` never sees them** and cannot reshape the envelope. To log or report them, add `app.addHook('onError', async (req, reply, error) => …)` before registering the plugin: it runs for every route error, a 500 carrying the driver error under `error.cause`. To change what the client gets, throw `httpError` from a hook or map driver codes in `dbErrors` (the error envelope paragraph under defineTable).
9
10
  - Do not read `node_modules/fastify-auto-sqlapi/dist/`: internal, unstable, not documentation. If this file does not answer, say so.
10
- - Behaviors that look like bugs but are decisions (docs/adr/): default-open `operations`, non-transactional bulk, every field updatable, raw 500 on DB errors, joins not running the target's route guards, no conditional/mass update route. Do not "fix" them.
11
+ - Behaviors that look like bugs but are decisions (docs/adr/): default-open `operations`, non-transactional bulk, every field updatable, a sanitized 500 on DB errors unless mapped in `dbErrors`, joins not running the target's route guards, no conditional/mass update route, `validateBulk` replacing `validate` in bulk, `PUT /rest/:table` taking the PK in `main`. Do not "fix" them.
11
12
 
12
13
  ## CLI: generate Schemas and tables
13
14
 
14
15
  ```ts
15
- // sqlapi.config.ts — CLI only, never read at runtime. These six keys are all that exist.
16
+ // sqlapi.config.ts — CLI only, never read at runtime. These five keys are all that exist, all optional; any other key fails the run.
17
+ import type { CliConfig } from 'fastify-auto-sqlapi';
16
18
  export default {
19
+ connection: process.env.SHOP_DB_URL, // the database to introspect; omit it to use DATABASE_URL. Keep the password in .env, not here
17
20
  outputDir: './src/db', // default './src/db'
18
- schema: 'public', // PostgreSQL only
19
- dialect: 'postgres', // 'postgres' | 'mysql' | 'mariadb'; or --dialect flag
20
- envFile: '.env', // relative to cwd; useful in monorepos
21
+ schema: 'public', // PostgreSQL only; MySQL/MariaDB introspect the URL's database
21
22
  excludeTables: ['knex_*'], // DB table names or * globs: no schema generated, old one removed
22
23
  excludeColumns: ['*.password_hash', 'user.internal_*'], // "<table>.<column>" DB names, * globs. The column does not exist for the API at all (no read, write, filter, manifest). Cannot exclude a PK; a pattern leaving a table with no columns fails the run.
23
- };
24
+ } satisfies CliConfig;
24
25
  ```
25
26
 
26
- Connection comes from env (a `.env` in cwd is loaded, set vars win): `DATABASE_URL`, or `POSTGRES_HOST|PORT|USER|PASSWORD|DB` / `MYSQL_HOST|PORT|USER|PASSWORD|DB`.
27
+ The connection is one URL whose scheme names the dialect: `postgres://` (or `postgresql://`), `mysql://`, `mariadb://`. First found wins: `--url`, then `connection` in the config, then `DATABASE_URL`. The `.env` in cwd is loaded before the config (a variable already set wins), so with `DATABASE_URL` in `.env` the commands take no argument. No URL → the run fails saying so; there is no default database. A `connection` key whose variable is unset fails too, rather than falling back to `DATABASE_URL`. Another env file: `process.loadEnvFile('.env.local')` at the top of the config. The schema CLI prints the database it introspects, password masked.
27
28
 
28
29
  ```bash
29
- npx sqlapi-generate-schema [--dialect mysql] # src/db/schemas/Schema*.ts — generated, NEVER edit (overwritten)
30
+ npx sqlapi-generate-schema # src/db/schemas/Schema*.ts — generated, NEVER edit (overwritten); --url <url> for a one-off database
30
31
  npx sqlapi-generate-tables customer order # src/db/tables/Table*.ts + dbTables.ts — yours to edit
31
32
  npx sqlapi-generate-tables --all # existing files are skipped, never overwritten
32
33
  ```
33
34
 
35
+ Both commands take `--output <dir>` (over the config's `outputDir`) and `--tables a,b` (DB table names; positional names work too). The schema command restricted to some tables neither removes orphan Schemas nor touches the others; without it, a Schema whose table is gone or excluded is deleted. An unknown option fails the run.
36
+
34
37
  - The generated table files detect PKs, `*Id` foreign keys as relations, and put every other key in as commented code.
35
- - The schema CLI prints what it could not decide for you: read that output. It covers database-generated columns (`GENERATED ALWAYS AS`, put in the Schema's `generatedFields` and never writable) and identity/auto-increment PKs (made optional and listed in `excludeFromCreation`). It also prints each view's inferred PK (see Views).
36
- - Schema files import `Type` from `fastify-auto-sqlapi` to avoid duplicate-TypeBox `[Kind]` errors. Their default export (`addSchema`) is optional, only for Swagger `$ref`.
38
+ - The schema CLI prints what it could not decide for you: read that output. It names database-generated columns (`GENERATED ALWAYS AS`, put in the Schema's `generatedFields` and never writable) and views, whose PK the table generator infers or leaves as a TODO (see Views). Identity/auto-increment PKs need no action: the Schema makes them optional and the table generator lists them in `insertExclude`.
39
+ - Schema files import `Type` from `fastify-auto-sqlapi`; do the same for `schemaOverrides`, computed fields and extra filters. Any `typebox` 1.x schema works too, but one built with the legacy `@sinclair/typebox` 0.x loses its markers here: its `Type.Optional` fields silently become required. Their default export (`addSchema`) is optional, only for Swagger `$ref`.
37
40
 
38
41
  ## Server setup
39
42
 
@@ -46,17 +49,19 @@ import { dbTables } from './src/db/tables/dbTables.js';
46
49
  const app = Fastify();
47
50
  await app.register(fastifyPostgres, { connectionString: process.env.DATABASE_URL }); // → fastify.pg
48
51
  await app.register(fastifyAutoSqlApi, {
49
- DbTables: dbTables, // required. Record key = route name: { customer } → /search/customer
52
+ dbTables, // required. Record key = route name: { customer } → /search/customer
50
53
  dialect: 'postgres', // 'postgres' (default) | 'mysql' | 'mariadb'
51
54
  prefix: '/auto', // standard Fastify prefix, applied once. None → /search/customer
52
55
  swagger: true, // or { title, description, version, routePrefix }. Needs @fastify/swagger + @fastify/swagger-ui, else warns and continues
53
56
  onRequests: [auth], // global hooks on every route
54
- getTenantId: (req) => req.user?.organizationId ?? null, // see Tenant scope
57
+ getTenantId: (req) => req.user?.organizationId, // see Tenant scope: undefined → 401 on scoped tables, TENANT_ADMIN → no filter
55
58
  maxItemsPerPage: 1000, // search page cap AND the LIMIT when no paginator is sent → 400 above it
56
59
  maxBulkItems: 1000, // bulk array cap → 400 above it
57
60
  agentManifest: true, // GET {prefix}/agent/manifest(.md), behind the same onRequests
58
61
  debug: true, // log SQL server-side; never changes a response
59
62
  exposeDebugInfo: false, // DEV ONLY: add driver error (message, code, constraint, detail, stack) as `debugInfo` on 500s
63
+ decorate: true, // app.sqlApi for your own routes; false on every registration but one
64
+ dbErrors: { '23505': { status: 409, code: 'duplicate' } }, // driver err.code → { status (400–599), code } in fields, translated client-side; yours to list, per DB ('ER_DUP_ENTRY' on MySQL/MariaDB). Unlisted → 500
60
65
  });
61
66
  // app.sqlApi is now decorated, usable from any route.
62
67
 
@@ -64,56 +69,62 @@ await app.register(fastifyAutoSqlApi, {
64
69
  const pool = mysql.createPool({ host, user, password, database });
65
70
  app.decorate('mysql', pool);
66
71
  app.addHook('onClose', () => pool.end());
67
- await app.register(fastifyAutoSqlApi, { DbTables: dbTables, dialect: 'mysql' });
68
-
69
- // Register only specific routes / different access levels per prefix. Each route plugin works standalone and decorates its own scoped sqlApi; register the main plugin if your own routes need app.sqlApi.
70
- import { searchRoutes, getRoutes, insertRoutes, updateRoutes, deleteRoutes, bulkUpsertRoutes, bulkDeleteRoutes, agentManifestRoutes, setupSwagger } from 'fastify-auto-sqlapi';
71
- await app.register(async (instance) => {
72
- await setupSwagger(instance, { swagger: true });
73
- const opts = { DbTables: publicTables, dialect: 'postgres' };
74
- await instance.register(searchRoutes, opts); // read-only: no insert/update/delete/bulk
75
- await instance.register(getRoutes, opts);
76
- }, { prefix: '/public' });
72
+ await app.register(fastifyAutoSqlApi, { dbTables, dialect: 'mysql' });
73
+
74
+ // Several surfaces: register the plugin again under another prefix with `decorate: false` (app.sqlApi belongs to one registration; a second one without it fails at startup). Each registration's routes run with its own options.
75
+ // `operations` narrows a registration: intersected with each table's own (a composite-PK table is skipped for get/delete, not refused).
76
+ const publicTables = { customer: dbTables.customer }; // a narrower map of your table configs
77
+ await app.register(fastifyAutoSqlApi, {
78
+ dbTables: publicTables, prefix: '/public', decorate: false,
79
+ operations: ['search', 'get'], // read-only: no insert/update/delete/bulk
80
+ swagger: true,
81
+ });
77
82
  ```
78
83
 
79
84
  `pg` returns `numeric`/`int8` as strings and shifts `date`/`timestamp` to local time. The plugin leaves `pg.types` alone (global state). If you want numbers and verbatim dates, set this at startup:
80
85
 
81
86
  ```ts
87
+ import pg from 'pg';
82
88
  pg.types.setTypeParser(pg.types.builtins.INT8, (v) => parseInt(v, 10));
83
89
  pg.types.setTypeParser(pg.types.builtins.NUMERIC, (v) => parseFloat(v));
84
90
  pg.types.setTypeParser(pg.types.builtins.DATE, (v) => v);
85
91
  pg.types.setTypeParser(pg.types.builtins.TIMESTAMP, (v) => v);
86
92
  ```
87
93
 
88
- HTTP responses coerce `"42"` to a number anyway. The parsers matter for `sqlApi.*` results and for hook arithmetic.
94
+ HTTP responses coerce a schema field (`"42"` → `42`) through the response schema. The `joinGroup` and `compute` aggregates are not coerced: they reach the client as the driver returns them — strings on `pg` (`"300.00"`, `"4"`), exact for any size. The parsers matter for those, for `sqlApi.*` results and for hook arithmetic; a parsed value beyond `Number.MAX_SAFE_INTEGER` (2^53 − 1) or with more significant digits than a double holds is no longer exact.
89
95
 
90
96
  ## defineTable
91
97
 
92
- Every key except `primary` and `exportTableInfo` is optional. There is no `tableName` key: the SQL table is `Schema.tableName`, and the route/manifest name is the `dbTables` key. One physical table can therefore be exposed under several keys, each with its own `operations`, `onRequests`, `tenantScope`, `readExclude` and joins.
98
+ Every key except `primary` and `schema` is optional. There is no `tableName` key: the SQL table is `schema.tableName`, and the route/manifest name is the `dbTables` key. One physical table can therefore be exposed under several keys, each with its own `operations`, `onRequests`, `tenantScope`, `readExclude` and joins.
93
99
 
94
100
  ```ts
95
- import { defineTable, exportTableInfo, buildRelation, buildUpsertRules, buildUpsertRule, ConditionBuilder, Type } from 'fastify-auto-sqlapi';
96
- import type { ValidationError } from 'fastify-auto-sqlapi';
97
- import { SchemaCustomer as Schema } from '../schemas/SchemaCustomer';
101
+ import { defineTable, buildRelation, ConditionBuilder, Type } from 'fastify-auto-sqlapi';
102
+ import type { ValidatorResult } from 'fastify-auto-sqlapi';
103
+ import { SchemaCustomer as Schema } from '../schemas/SchemaCustomer.js';
104
+ import { SchemaOrder } from '../schemas/SchemaOrder.js';
105
+ import { decrypt } from '../../crypto.js'; // yours
98
106
 
99
107
  export const TableCustomer = defineTable({
100
- primary: 'id', // or ['agentId', 'teamId']. Composite PK: no get/delete/bulkDelete routes (listing them in `operations` throws, sqlApi.* → 400); use search, update (matches all PK columns), or a custom route.
101
-
102
- // Extra filters: non-column search filters. Not applied as `col = value`, only via the callback. `filters` is typed with schema + extra keys. Not usable under joinLeft (400); use joinMustExist.
103
- ...exportTableInfo(Schema, Type.Object({ q: Type.String(), dateFrom: Type.String(), dateTo: Type.String() }),
104
- (condition, filters) => {
105
- if (filters.q) {
106
- const or = new ConditionBuilder('OR');
107
- or.isILike(Schema.col('name'), `%${filters.q}%`);
108
- or.isILike(Schema.col('email'), `%${filters.q}%`);
109
- condition.append(or);
110
- }
111
- // undefined values are skipped; a missing bound turns isBetween into >= / <=
112
- condition.isBetween(Schema.col('orderDate'), filters.dateFrom, filters.dateTo);
113
- }),
108
+ primary: 'id', // or ['agentId', 'teamId']. Composite PK: no get/delete-by-`:id` routes (listing them in `operations` throws, sqlApi.* → 400); read with search, write with update (matches all PK columns), delete with bulkDelete, `{ ids: [{ agentId, teamId }] }`.
109
+
110
+ schema: Schema, // required: the generated Schema. Column filters (`col = value`, null → IS NULL) come from it.
111
+
112
+ // Extra filters: non-column search filters (a record of fields or a Type.Object). Not applied as `col = value`, only via extendedCondition. Not usable under joinLeft (400); use joinMustExist.
113
+ extraFilters: { q: Type.String(), dateFrom: Type.String(), dateTo: Type.String() },
114
+ extendedCondition: (condition, filters, { col }) => { // `filters` is typed with schema + extra keys
115
+ // col(field): the column quoted and qualified for where this runs (main search, or a join's subquery under its alias). Always use it: a bare Schema.col() is unquoted and unqualified
116
+ if (filters.q) {
117
+ const or = new ConditionBuilder('OR');
118
+ or.isILike(col('name'), `%${filters.q}%`);
119
+ or.isILike(col('email'), `%${filters.q}%`);
120
+ condition.append(or);
121
+ }
122
+ // undefined values are skipped; a missing bound turns isBetween into >= / <=
123
+ condition.isBetween(col('orderDate'), filters.dateFrom, filters.dateTo);
124
+ },
114
125
  // Unknown filter keys (not a field, extra filter or computed) are 400, on main and every join, over HTTP and sqlApi alike.
115
126
 
116
- defaultOrder: 'name ASC, id DESC', // fields mapped to columns; computed allowed; unknown tokens pass as raw SQL
127
+ defaultOrder: 'name ASC, id DESC', // the 1-part orderBy grammar: schema or computed fields, ASC|DESC. No dotted notation, no SQL (an expression → computedFields). Checked at startup
117
128
  distinctResults: true, // SELECT DISTINCT
118
129
  operations: ['search', 'get'], // HTTP route whitelist. OMITTED = ALL ROUTES (default-open). Does not restrict sqlApi.* nor joins pointing at this table.
119
130
  onRequests: [async (req, reply) => { // per-table hooks, after the global ones
@@ -121,24 +132,21 @@ export const TableCustomer = defineTable({
121
132
  }],
122
133
 
123
134
  // --- field visibility ---
124
- excludeFromCreation: ['id', 'createdAt'], // MUST list auto-increment PKs (CLI does it). Strips CLIENT input on insert only: beforeInsert and the FK auto-fill may still set it. Not a security tool: every field stays updatable (ADR 0004).
125
- readExclude: ['passwordHash'], // never projected (search, get, default join selection); naming it in filters/conditions/orderBy/aggregations/selection → 400. Still writable. Static, applies to admins too. PK not allowed.
135
+ insertExclude: ['id', 'createdAt'], // MUST list auto-increment PKs (CLI does it). Strips CLIENT input on insert only: beforeInsert and the FK auto-fill may still set it. A field of the upsertKey is kept: it names an existing row, never a new one (no such row → 400 not_found, ADR 0031). Not a security tool: every field stays updatable (ADR 0004).
136
+ readExclude: ['passwordHash'], // never projected (search, get, default join projection); naming it in filters/conditions/orderBy/aggregations/select → 400. Still writable. Static, applies to admins too. PK not allowed.
126
137
  writeExclude: ['searchVector'], // dropped from insert/update/bulk bodies and in the engines; still readable. For trigger-owned columns; GENERATED columns need nothing. Runs after hooks. Not PK, not also in readExclude (that is excludeColumns).
127
138
  schemaOverrides: { email: Type.String({ format: 'email' }) }, // stricter type for WRITE bodies only (responses and filters keep the generated type: stored rows predate the rule). Taken verbatim: no Optional → mandatory, no Nullable → null rejected.
128
139
 
129
140
  // --- joins (see Relations) ---
130
- allowedReadJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders' })],
131
- allowedWriteJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders' })],
141
+ readJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders' })],
142
+ writeJoins: [buildRelation(Schema, 'id', SchemaOrder, 'customerId', { alias: 'orders', upsertKey: ['id'] })], // upsertKey: the child rows of this relation upsert on it, and it can be replaced
132
143
 
133
- // --- upsert: INSERT becomes upsert for that schema, main or write-join child ---
134
- upsertMap: buildUpsertRules(
135
- buildUpsertRule(Schema, ['email']), // exactly the PK or one of the Schema's uniqueKeys, checked at startup (old Schemas: regenerate). Views: none.
136
- buildUpsertRule(SchemaOrder, ['id']),
137
- ),
138
- // Each upserted row must carry its key (natural key non-null; PK whole, or absent = plain insert), no two rows of a request may share it → 400. A row must still be insertable (PG: NOT NULL without default is required even for an existing row). Another row's unique value = DB error, never a hijack.
144
+ // --- upsert: the main row's INSERT (POST /rest, bulk upsert) becomes INSERT … ON CONFLICT (key) DO UPDATE ---
145
+ upsertKey: ['email'], // exactly the PK or one of the Schema's uniqueKeys, checked at startup (old Schemas: regenerate). Views: none. Main rows only; child rows use the relation's upsertKey. Absent: plain INSERT.
146
+ // Each upserted row must carry its key (natural key non-null; PK whole, or absent = plain insert), no two rows of a request may share it → 400. A key field in insertExclude (the generated PK) only names an existing row: none → 400 not_found. A row must still be insertable (PG: NOT NULL without default is required even for an existing row). Another row's unique value = DB error, never a hijack.
139
147
 
140
148
  // --- tenant (see Tenant scope) ---
141
- tenantScope: { column: 'organization_id' }, // REAL column name
149
+ tenantScope: { column: 'organizationId' }, // schema field, like every key here
142
150
 
143
151
  // --- computed fields (see Computed fields) ---
144
152
  computedFields: {
@@ -152,35 +160,39 @@ export const TableCustomer = defineTable({
152
160
  },
153
161
 
154
162
  // --- validation: after schema validation, before hooks and SQL. Any error → 400, nothing written ---
155
- validate: async (db, req, main, secondaries) => { // camelCase, secondaries keyed by alias
156
- const errors: ValidationError[] = []; // [field, code] or [field, code, message]
157
- if (!main.name) errors.push(['name', 'required']);
158
- const orders = secondaries?.orders ?? [];
159
- if (orders.some((o) => o.total < 0)) errors.push(['orders[0].total', 'min', 'must be >= 0']);
163
+ // Every hook and validator receives ONE context object: { db, req, ...data }. db = the client the
164
+ // operation runs on (inside a write, the transaction's); req = the request, undefined when sqlApi.*
165
+ // is called without one (guard req?.user). Data keys: record, secondaries, deletions, rows, id, ids, main, upsert, replace, parent, items.
166
+ validate: async ({ db, req, main, upsert, replace, parent }) => { // camelCase, the request's child-row sections keyed by alias; parent: { alias, main } when this row arrives as another table's child (ADR 0030), absent on this table's own routes
167
+ const errors: ValidatorResult = []; // { path, code }[], the fields of the 400, as is (no message: no prose, the client translates the code). path = dot path in the request body: main.<field>, upsert.<alias>.<i>.<field>, replace.<alias>.<i>.<field>, '' when not attributable. Anything else (a tuple, a message) → 500
168
+ if (!main.name) errors.push({ path: 'main.name', code: 'required' });
169
+ (upsert?.orders ?? []).forEach((o, i) => { // child rows are untyped: they follow the joined table's schema
170
+ if (Number(o.total) < 0) errors.push({ path: `upsert.orders.${i}.total`, code: 'min' });
171
+ });
160
172
  return errors;
161
173
  },
162
- validateBulk: async (db, req, items) => { // bulk upsert: called once with [{ main, secondaries? }]; when defined, per-item validate is skipped in bulk
174
+ validateBulk: async ({ db, req, items }) => { // bulk upsert: called once with the items as sent, [{ main, upsert?, delete?, replace? }]; when defined, per-item validate is skipped in bulk, so a rule that must hold in bulk is written here too (ADR 0025). Paths start with items.<i>
163
175
  const codes = items.map((i) => i.main.code);
164
- return new Set(codes).size === codes.length ? [] : [['code', 'batch_unique']];
176
+ return new Set(codes).size === codes.length ? [] : [{ path: '', code: 'batch_unique' }];
165
177
  },
166
178
 
167
179
  // --- hooks: camelCase records, mutations reach the SQL ---
168
- beforeInsert: async (db, req, record) => {
169
- record.createdBy = req.user.id;
180
+ beforeInsert: async ({ db, req, record }) => {
181
+ record.createdBy = req?.user?.id;
170
182
  record.createdAt = db.expression('NOW()'); // raw SQL value
171
183
  },
172
- beforeUpdate: async (db, req, fields) => { // PK present but not in SET
173
- if (!req.user.isAdmin) delete fields.isAdmin; // field-level rules: silent strip here, or 400 in validate
174
- fields.updatedAt = db.expression('NOW()');
184
+ beforeUpdate: async ({ db, req, record }) => { // PK present but not in SET
185
+ if (!req?.user?.isAdmin) delete record.isAdmin; // field-level rules: silent strip here, or 400 in validate
186
+ record.updatedAt = db.expression('NOW()');
175
187
  },
176
- afterInsert: async (db, req, record, secondaryRecords) => {}, // record = input + generated PK
177
- afterUpdate: async (db, req, record, secondaryRecords, deletionRecords) => {}, // inside the transaction: throw = rollback
178
- beforeDelete: async (db, req, id) => {}, // throw aborts; runs after tenant ownership is verified
179
- afterDelete: async (db, req, id) => {}, // not called on 404
180
- beforeBulkDelete: async (db, req, ids) => {}, // once; throw aborts the whole batch
181
- afterBulkDelete: async (db, req, deletedIds) => {}, // once, only the ids actually deleted
182
- afterRead: async (db, req, rows, ctx) => { // see afterRead
183
- for (const row of rows) if (row.ssn != null) row.ssn = decrypt(row.ssn);
188
+ afterInsert: async ({ db, req, record, secondaries, deletions }) => {}, // record = input + generated PK; secondaries: child rows written; deletions: rows a replace removed, and in a bulk upsert the item's delete
189
+ afterUpdate: async ({ db, req, record, secondaries, deletions }) => {}, // inside the transaction: throw = rollback. deletions: rows of delete and of a replace
190
+ beforeDelete: async ({ db, req, id }) => {}, // throw aborts; runs after tenant ownership is verified
191
+ afterDelete: async ({ db, req, id }) => {}, // not called on 404
192
+ beforeBulkDelete: async ({ db, req, ids }) => {}, // once; throw aborts the whole batch. ids: values, or { <field>: value } on a composite PK
193
+ afterBulkDelete: async ({ db, req, ids }) => {}, // once, only the ids actually deleted
194
+ afterRead: async ({ db, req, rows, source, alias }) => { // see afterRead
195
+ for (const row of rows) if (typeof row.ssn === 'string') row.ssn = decrypt(row.ssn);
184
196
  },
185
197
  });
186
198
  ```
@@ -189,34 +201,38 @@ Nullable columns are generated as `Type.Optional(Nullable(T))`, i.e. `{ type: ['
189
201
 
190
202
  Write bodies are closed (`additionalProperties: false`), so a column that is not in the Schema can never be written (no mass assignment). With Fastify's default `removeAdditional: true`, unknown properties are stripped silently. `Fastify({ ajv: { customOptions: { removeAdditional: false } } })` makes them a 400.
191
203
 
192
- Errors the plugin raises itself are 4xx with client-safe messages. Anything else (a constraint violation, a hook throwing without `statusCode`) returns a fixed `{statusCode:500, error, message:"Internal Server Error", requestId}`: the driver error is logged and set as `err.cause`, and no status is remapped. To map it, add a `setErrorHandler` that checks `err.cause.code === '23505'` and returns 409. Errors thrown by `onRequests` are unaffected.
204
+ Every error the routes return has one envelope, `{statusCode, error, message, requestId, fields?}` (AGENTS_FRONTEND.md, "Errors"): `error` is the reason phrase, `requestId` the log's `reqId`, and every 400 carries `fields` as `ValidationField[]`. Errors the plugin raises itself are 4xx with client-safe messages. To answer in the same shape from a hook, throw `httpError(400, 'Order is closed', { code: 'closed', path: 'main.status' })` (exported). A thrown 4xx is answered with its status and message, plus `fields` when `httpError` was given a `code`; a thrown 5xx is a server failure like any other and becomes the fixed 500 below, its message only in the log. Anything else (a constraint violation, a hook throwing without `statusCode`, a stored value the response schema refuses because the Schema predates a column change: regenerate it) returns a fixed `{statusCode:500, error, message:"Internal Server Error", requestId}`: the driver error is logged under that `requestId`. The plugin maps no code of its own (ADR 0006); to answer one with a status, list its driver code in `dbErrors` with a status and a code of yours: the response keeps the envelope, with the reason phrase as `message`, `fields: [{ path: '', code }]` whatever the status, and no driver detail (ADR 0024). An application `setErrorHandler` never sees these errors: the routes' own handler answers first; an application `onError` hook does see them (see Rules). `sqlApi.*` throws the driver error as is. Errors thrown by `onRequests` are unaffected.
193
205
 
194
206
  ## Relations
195
207
 
196
- ```ts
208
+ ```ts signature
197
209
  buildRelation(mainSchema, mainField, joinSchema, joinField, {
198
- alias, // default joinSchema.tableName. Key in requests, responses, secondaries, deletions, dotted notation. Set it only to join one table twice or for a friendlier name. Duplicate alias → throws.
199
- selection, // default '*'. 'id, name, total'
210
+ alias, // default joinSchema.tableName. Key in requests (upsert, delete, replace), responses (secondaries, deletions), dotted notation. Set it only to join one table twice or for a friendlier name. Duplicate alias → throws.
211
+ select, // default fields of the joined rows, e.g. ['id', 'name', 'total']; absent: every readable field. The request's select overrides it. A name the joined schema lacks → throws
200
212
  unique, // false: 1:N child→main (joinField = child FK) → joinMustExist / joinMultiple / joinGroup. true: N:1 parent→main (joinField = parent PK) → joinLeft. joinField is the target's PK → use true.
201
213
  fields, // read-only allowlist of the target's fields. Must include joinField. Not on write joins.
214
+ target, // dbTables key whose config governs the joined table (readExclude, tenantScope, afterRead, computed, write rules). Required when several keys expose that table: startup fails until it is set. With one key, that config applies whatever the key is called.
215
+ upsertKey, // write joins only: the child rows upsert on this key of the joined table, e.g. ['productId', 'lang']. Exactly its PK or one of its uniqueKeys, checked by defineTable (ADR 0021). Absent: plain INSERT, and the alias takes no `replace`. On a read join → throws.
202
216
  });
217
+ ```
203
218
 
204
- allowedReadJoins: [
219
+ ```ts in=defineTable
220
+ readJoins: [
205
221
  buildRelation(SchemaSession, 'createdBy', SchemaUser, 'id', { alias: 'creator', unique: true }),
206
222
  buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true, fields: ['id', 'name'] }),
207
223
  ],
208
224
  ```
209
225
 
210
- - **A read join is a read grant on the target.** It runs inside the host's route: the target's `onRequests` and `operations` do not apply, so a table with `operations: []` is still readable through it. The target's `readExclude`, `tenantScope`, `afterRead` and the relation's schema still apply. `fields` narrows that schema, fail-closed: every other field is a 400 in selection, filters, conditions, orderBy and aggregations, and so is a computed field reaching past it. A column added later is not reachable until listed. Use `readExclude` instead to hide a column from the table's own routes too. (ADR 0010, 0011)
226
+ - **A read join is a read grant on the target.** It runs inside the main table's route: the target's `onRequests` and `operations` do not apply, so a table with `operations: []` is still readable through it. The target's `readExclude`, `tenantScope`, `afterRead` and the relation's schema still apply. `fields` narrows that schema, fail-closed: every other field is a 400 in `select`, filters, conditions, orderBy and aggregations, and so is a computed field reaching past it. A column added later is not reachable until listed. Use `readExclude` instead to hide a column from the table's own routes too. (ADR 0010, 0011)
211
227
  - joinLeft adds a real `LEFT JOIN` only when filters or orderBy need the parent; otherwise it runs a side query.
212
- - **Owned children** (translations, `*_info`, composite PK like `(product_id, lang)`): make them a write join on the parent, not a `dbTables` entry. The child FK is auto-filled, and an `upsertMap` rule on the child key lets clients send only the child's own fields: `PUT /rest/product { main, secondaries: { translations: [{ lang: 'en', name: 'Bike' }] } }`. Expose a composite-PK table standalone only when it stands on its own (M:N links).
213
- - **What a write join runs on the child**: its `excludeFromCreation`, `tenantScope` and `beforeInsert`, then the FK auto-fill, which always wins. Not its `validate` or `afterInsert` (ADR 0014).
228
+ - **Owned child rows** (translations, `*_info`, composite PK like `(product_id, lang)`): make them a write join on the parent, not a `dbTables` entry. The child FK is auto-filled, and an `upsertKey` on the relation (`{ alias: 'translations', upsertKey: ['productId', 'lang'] }`) lets clients send only the child's own fields: `PUT /rest/product { main, upsert: { translations: [{ lang: 'en', name: 'Bike' }] } }`. With that key the client can also send the whole set, `replace: { translations: [...] }`: the rows left out are deleted, in the write's transaction — in a bulk upsert, in the item's own (ADR 0029). Expose a composite-PK table standalone only when it stands on its own (M:N links).
229
+ - **What a write join runs on the child** (rows of `upsert` and `replace`): its `validate` — or its `validateBulk`, once per alias — before any SQL, after the main table's, with `parent: { alias, main }`. It answers in its own grammar, `main.<field>`, `main` or `''` (`validateBulk`: `items.<j>.main.<field>`, `items.<j>` or `''`; anything else is a 500), re-rooted to `upsert.<alias>.<i>.<field>` (`replace.…` for those rows, `<item>.` in front in a bulk upsert); then its `insertExclude`, the FK auto-fill, its `beforeInsert` (which sees the FK), the FK again, so it always wins, and its `tenantScope`. Not its `afterInsert` (ADR 0014, 0030). The child's `validate` sees the FK only when the request names the parent's key: guard a required-FK rule with `!parent`.
214
230
 
215
231
  ## Computed fields
216
232
 
217
- A computed field is a SQL expression usable like a field in `filters`, `conditions`, `orderBy`, `computeMin/Max/Sum/Avg` and `joinGroup.aggregations.by`. It is projected only when requested through `selectComputed`.
233
+ A computed field is a SQL expression usable like a field in `filters`, `conditions`, `orderBy`, `compute` and `joinGroup.<alias>.by`. It is projected only when listed in the request's `select`: `select: ['*', 'fullName']` returns every readable field plus it (ADR 0028).
218
234
 
219
- ```ts
235
+ ```ts in=defineTable
220
236
  computedFields: {
221
237
  statusFromMeta: ({ db, qiCol }) => ({ // db: QueryClient (dialectName, dateTrunc, ...)
222
238
  expr: db.dialectName === 'postgres'
@@ -240,15 +256,15 @@ computedFields: {
240
256
 
241
257
  - Computed fields are per table: a join's side query uses the target table's computed fields. On joinLeft, `qiCol` adds the alias automatically.
242
258
  - A name that collides with a schema field or an extra filter throws in `defineTable`.
243
- - Bound `values` work in WHERE and ORDER BY positions. They are rejected (400) in `selectComputed`, `compute*`, `aggregations.by` and `defaultOrder`.
259
+ - Bound `values` work in WHERE and ORDER BY positions. They are rejected (400) in `select`, `compute`, joinGroup `by` and `defaultOrder`.
244
260
  - Limits: read-only (not writable), no computed field referencing another, not usable as a joinGroup aggregation field (`sum: [...]` takes schema fields). The expression is evaluated once per use.
245
261
 
246
262
  ## afterRead
247
263
 
248
264
  The read-side counterpart of `beforeInsert`/`beforeUpdate`: decrypt, unpack, rescale. Declare it on the table that **owns** the column. It then runs wherever those rows surface: `ctx.source` is `get | search | joinMultiple | joinLeft`, and `ctx.alias` names the relation on joins. It is called once per result set and mutates the rows in place.
249
265
 
250
- - It does not run on joinGroup, compute*, or an empty result. It cannot add or remove rows (the COUNT has already run).
251
- - `filters`, `orderBy` and `compute*` act on the **stored** value, so an encrypted column is searched as ciphertext. With a deterministic cipher, encrypt the search value in `extendedCondition`. With a randomized cipher, the column cannot be searched.
266
+ - It does not run on joinGroup, compute, or an empty result. It cannot add or remove rows (the COUNT has already run).
267
+ - `filters`, `orderBy` and `compute` act on the **stored** value, so an encrypted column is searched as ciphertext. With a deterministic cipher, encrypt the search value in `extendedCondition`. With a randomized cipher, the column cannot be searched.
252
268
  - It changes values, not types: the response is serialized with the generated schema (an object in a `text` column becomes `"[object Object]"`). If the stored type and the API type differ, write a custom route.
253
269
  - For encryption at rest, pair it with `beforeInsert` + `beforeUpdate` (as in the defineTable example). That covers own routes, joins, and writes as a secondary.
254
270
 
@@ -258,53 +274,69 @@ The read-side counterpart of `beforeInsert`/`beforeUpdate`: decrypt, unpack, res
258
274
 
259
275
  - an id → `IN (id)`
260
276
  - an array → `IN (...)`
261
- - `null` / `undefined` → admin, no filter
277
+ - `TENANT_ADMIN` (exported) → admin, no filter. Admin is declared, never inferred.
278
+ - `null` / `undefined` → 401 on any scoped table, before SQL runs: an absent tenant is a missing or failed auth hook, not an admin
262
279
  - `[]` → no tenant at all: 403 on any scoped table, before SQL runs
263
280
 
264
- `0` and `''` are ordinary ids. The tenant belongs to the request, not to the table: a scoped table is also filtered when it is a join target or a secondary of an unscoped host. So `getTenantId` must tolerate an unauthenticated request (`req.user?.x ?? null`). Tables without `tenantScope` are never filtered.
281
+ `0` and `''` are ordinary ids. The tenant belongs to the request, not to the table: a scoped table is also filtered when it is a join target or a secondary of an unscoped main table. `getTenantId` is called only when a scoped table is in reach, so an unauthenticated request still reads unscoped tables; on scoped ones `req.user?.organizationId` is enough, the missing user becomes the 401. Tables without `tenantScope` are never filtered.
265
282
 
266
- ```ts
267
- tenantScope: { column: 'organization_id' } // direct
268
- tenantScope: { column: 'organization_id', // indirect, via parent FK
269
- through: { schema: SchemaCustomer, localField: 'customer_id', foreignField: 'id' } }
270
- tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] } // row owned by either party
283
+ ```ts in=app
284
+ await app.register(fastifyAutoSqlApi, {
285
+ dbTables,
286
+ getTenantId: (req) => (req.user?.isSuperadmin ? TENANT_ADMIN : req.user?.organizationId),
287
+ });
271
288
  ```
272
289
 
273
- All names in a scope are real columns. Naming a camelCase field whose column differs throws at startup. `anyOf` cannot be combined with `column`/`through` (throws). Clients still send the camelCase field.
290
+ ```ts in=app
291
+ const direct: TenantScope = { column: 'organizationId' };
292
+ const indirect: TenantScope = { column: 'organizationId', // via parent FK: column and foreignField are fields of SchemaCustomer
293
+ through: { schema: SchemaCustomer, localField: 'customerId', foreignField: 'id' } };
294
+ const eitherParty: TenantScope = { anyOf: ['requesterAgentId', 'targetAgentId'] }; // row owned by either party
295
+ // on the table: defineTable({ …, tenantScope: direct })
296
+ ```
297
+
298
+ All names in a scope are schema fields: `column`, `anyOf` and `localField` of this table, the indirect `column` and `foreignField` of `through.schema`. The column of a field is accepted too (a 0.x scope naming columns keeps working); any other name fails `defineTable` at startup. The tenant column must therefore be in the schema: hide it with `readExclude`, never `excludeColumns`. `anyOf` cannot be combined with `column`/`through` (throws).
274
299
 
275
300
  | | direct | indirect | anyOf |
276
301
  |---|---|---|---|
277
302
  | read, get, delete | `AND col IN (...)` | INNER JOIN parent + WHERE | `AND (a IN (...) OR b IN (...))`; NULL never matches; all-NULL row = admin only; outside scope → 404 |
278
303
  | insert | single tenant: injected; mismatch → 403; multi-tenant without value → 400. Column is optional in the body | FK must belong to tenant (1 query) → 403 | no injection: at least one listed column must hold a tenant id (400 none, 403 all foreign) |
279
304
  | update | column stripped from SET, added to WHERE | pre-check → 404; changing the FK to another tenant → 403 | all listed columns stripped from SET; outside scope → 404 |
280
- | bulk upsert | injected on every row; `upsertMap` conflict key owned by another tenant → 403 | as insert | anchor rule per item, even for updates; listed columns never in UPDATE SET; conflict with a row outside scope → 403 |
305
+ | bulk upsert | injected on every row; `upsertKey` conflict owned by another tenant → 403 | as insert | anchor rule per item, even for updates; listed columns never in UPDATE SET; conflict with a row outside scope → 403 |
281
306
  | joins | filtered | filtered | predicate applied in every join family (joinLeft: in the ON clause) |
282
307
 
283
- `anyOf` children written as secondaries follow the anchor rule: the auto-filled parent FK is not an owner.
308
+ `anyOf` child rows written as secondaries follow the anchor rule: the auto-filled parent FK is not an owner.
284
309
 
285
310
  ## sqlApi (application code)
286
311
 
287
- Same code path, bodies and results as the HTTP routes (AGENTS_FRONTEND.md). Validation, hooks, computed fields and tenant scope all run.
312
+ Same code path, bodies and results as the HTTP routes (AGENTS_FRONTEND.md): a request body can be handed over as is. Validation, hooks, computed fields and tenant scope all run.
288
313
 
289
- ```ts
290
- app.get('/billing/:customerId', async (request) =>
314
+ ```ts in=app
315
+ app.get<{ Params: { customerId: string } }>('/billing/:customerId', async (request) =>
291
316
  app.sqlApi.search('subscription', {
292
317
  filters: { customerId: Number(request.params.customerId), status: 'active' },
293
318
  joinMustExist: { orders: { filters: { status: 'pending' } } },
294
319
  paginator: { page: 1, itemsPerPage: 50 },
295
320
  }, request)); // pass `request` for tenant + hooks; without it: no tenant filter, hooks get undefined
321
+ ```
296
322
 
297
- sqlApi.search(table, { filters, conditions, joinMustExist, joinMultiple, joinGroup, joinLeft, selectComputed, orderBy, paginator, computeMin, computeMax, computeSum, computeAvg, maxRows }, req?)
323
+ ```ts signature
324
+ sqlApi.search(table, { filters, conditions, joinMustExist, joinMultiple, joinGroup, joinLeft, select, orderBy, paginator, compute, maxRows }, req?)
325
+ // select: main fields to project, '*' for every readable one; the PK, the requested joins' keys and (with distinctResults) the ORDER BY fields are always added
326
+ // compute: { sum: ['total'], count: ['id'] } → result.computed, over every matching row; min|max|sum|avg|count|distinctCount; no paginator needed
298
327
  sqlApi.get(table, id, req?)
299
- sqlApi.insert(table, { record, secondaries? }, req?)
300
- sqlApi.update(table, { record, secondaries?, deletions? }, req?)
328
+ sqlApi.insert(table, { main, upsert?, replace? }, req?) // the POST /rest body: app.sqlApi.insert('customer', req.body, req)
329
+ sqlApi.update(table, { main, upsert?, delete?, replace? }, req?) // the PUT /rest body, PK in main
301
330
  sqlApi.delete(table, id, req?)
302
331
  sqlApi.bulkUpsert(table, items, req?) // each item writes only its own fields; items need not share keys
303
- sqlApi.bulkDelete(table, ids, req?)
332
+ sqlApi.bulkDelete(table, { ids }, req?) // the POST /bulk/:table/delete body; composite PK: ids are { <field>: value } objects
333
+ // table: a key of dbTables. createSqlApi infers them, so a typo fails at compile time; at runtime an unknown name throws (a programming error, not a 400)
334
+ ```
304
335
 
305
- // Standalone (jobs, scripts, tests). Always pass dialect, default is postgres syntax.
306
- const sqlApi = createSqlApi(mysqlQueryable(pool), dbTables, { dialect: 'mysql' });
307
- const sqlApi2 = createSqlApi(createQueryClient(pgQueryable(pgPool), 'postgres'), dbTables, { dialect: 'postgres' });
336
+ ```ts in=app
337
+ // Standalone (jobs, scripts, tests). Tenant scope needs its own getTenantId, as on the plugin: without it a request passed in scopes nothing. One source for the dialect:
338
+ const sqlApi = createSqlApi(mysqlQueryable(pool), dbTables, { dialect: 'mysql', getTenantId: (req) => req.user?.organizationId }); // raw pool: the option, postgres when omitted
339
+ const sqlApi2 = createSqlApi(createQueryClient(mysqlQueryable(pool), 'mysql'), dbTables); // QueryClient: its own dialect; a `dialect` option beside it throws
308
340
  ```
309
341
 
310
342
  Limits: the engine enforces at most 100 `conditions` per section, 20 `orderBy` parts and an integer `paginator`, for sqlApi too. `maxItemsPerPage` and `maxBulkItems` belong to the routes only: pass `maxRows` to `search`, and cap your own bulk arrays.
@@ -313,11 +345,11 @@ Limits: the engine enforces at most 100 `conditions` per section, 20 `orderBy` p
313
345
 
314
346
  `db` is the hook parameter, or `createQueryClient(pgQueryable(pool) | mysqlQueryable(pool), dialect)`. Use it only for what sqlApi cannot express. It takes real table and column names (`Schema.tableName`, `Schema.col()`), and a camelCase name here is a runtime SQL error. It runs no hooks, no validation and no tenant scope.
315
347
 
316
- ```ts
348
+ ```ts signature
317
349
  db.insert(table, record, pkCol) // → PK row
318
- db.insertOrUpdate(table, record, conflictKeys, pkCol) // → PK row
350
+ db.upsert(table, record, conflictKeys, pkCol) // → { pk, action: 'inserted' | 'updated' }
319
351
  db.bulkInsert(table, records, pkCol, chunkSize?) // → PK rows in input order
320
- db.bulkInsertOrUpdate(table, records, conflictKeys, pkCol, chunkSize?)
352
+ db.bulkUpsert(table, records, conflictKeys, pkCol, { chunkSize?, immutableCols? }?) // → [{ pk, action }] in input order. immutableCols: written on insert, never on update
321
353
  db.update(table, record, where, extraCondition?) // → affected rows (number)
322
354
  db.delete(table, where) // → affected rows
323
355
  db.select({ tableName, columns?, where, values, limit?, orderBy?, joins?, distinct? })
@@ -327,10 +359,12 @@ db.qi(name); db.dialectName; db.cbDialect // quoting, dialect, ConditionBuilder
327
359
  ```
328
360
 
329
361
  - `pkCol` is a string or an array. Bulk methods issue one statement per distinct column set.
362
+ - Values: string, number, boolean, null, `Date` (bound as a timestamp), `db.expression(...)`. `JSON.stringify` a JSON value first: the drivers do not serialize objects as JSON.
330
363
  - `conflictKeys` must be a unique key enforced by the DB. PG uses `ON CONFLICT (keys)`. MySQL/MariaDB upsert by key (a probe SELECT per chunk, then INSERT new and UPDATE existing), because `ON DUPLICATE KEY` fires on any unique index. A key matching several rows is refused.
364
+ - `action` comes from the statement on PG (`(xmax = 0)` in RETURNING; on `DO NOTHING`, the rows RETURNING names are the inserted ones) and from the probe on MySQL/MariaDB. No extra statement either way.
331
365
  - Called directly, none of the `defineTable` checks apply.
332
366
 
333
- ```ts
367
+ ```ts signature
334
368
  const cb = new ConditionBuilder('AND', db.cbDialect); // or 'OR'. Operands are raw SQL: db.qi() them.
335
369
  cb.isEqual(col, v); // also isNotEqual, is[Not]Greater[OrEqual], is[Not]Less[OrEqual]
336
370
  cb.isLike(col, '%v%'); // also isNotLike, isILike, isNotILike
@@ -344,10 +378,11 @@ cb.append(otherBuilder); // nesting; backend only
344
378
 
345
379
  Example: atomically claiming a row, i.e. a guarded state transition or optimistic lock. There is no auto route for this (ADR 0020). The check and the write must be one UPDATE:
346
380
 
347
- ```ts
381
+ ```ts in=app
348
382
  const db = createQueryClient(pgQueryable(fastify.pg), 'postgres');
349
- fastify.post('/requests/:id/claim', async (req, reply) => {
350
- const col = (f: string) => SchemaRequest.col(f);
383
+ fastify.post<{ Params: { id: string } }>('/requests/:id/claim', async (req, reply) => {
384
+ if (!req.user) return reply.code(401).send(); // never let an undefined tenant reach the guard: isEqual would skip it
385
+ const col = SchemaRequest.col;
351
386
  const guard = new ConditionBuilder('AND', db.cbDialect)
352
387
  .isNull(db.qi(col('inProgressSince')), true) // the precondition
353
388
  .isEqual(db.qi(col('organizationId')), req.user.orgId); // tenant: db applies none
@@ -374,27 +409,28 @@ A view (materialized ones included) is an ordinary table config (ADR 0016).
374
409
 
375
410
  A read-only surface for LLM agents, with the plugin as the enforcement layer:
376
411
 
377
- ```ts
378
- await app.register(async (instance) => {
379
- const opts = { DbTables: dbTables, onRequests: [agentAuth] };
380
- await instance.register(searchRoutes, opts);
381
- await instance.register(getRoutes, opts);
382
- await instance.register(agentManifestRoutes, opts); // GET /agent/manifest(.md)
383
- }, { prefix: '/agent' });
412
+ ```ts in=app
413
+ await app.register(fastifyAutoSqlApi, {
414
+ dbTables, prefix: '/ai', decorate: false, onRequests: [agentAuth],
415
+ operations: ['search', 'get'],
416
+ agentManifest: true, // GET /ai/agent/manifest(.md), listing this registration's operations
417
+ });
384
418
  ```
385
419
 
386
- - **System prompt**: AGENTS_FRONTEND.md (grammar, shipped in the package) + the output of `GET /agent/manifest.md` (this deployment's tables, fields and aliases).
387
- - **Tools**: either a loose generic tool, retrying on the structured 400 `fields[]`, or strict per-table tools from `agentToolSchemas(dbTables, table)`.
420
+ - **System prompt**: AGENTS_FRONTEND.md (grammar, shipped in the package) + the output of `GET {prefix}/agent/manifest.md` (this registration's tables, fields and aliases).
421
+ - **Tools**: either a loose generic tool, retrying on the structured 400 `fields[]`, or strict per-table tools from `agentToolSchemas(dbTables, table, { operations })` (pass the registration's `operations` and caps).
388
422
 
389
423
  ## Exports
390
424
 
391
425
  Everything is imported from `fastify-auto-sqlapi`, so there is nothing else to install:
392
426
 
393
- - `Type`, `Static`, `ConditionBuilder`, `Expression`, `Nullable`
394
- - `defineTable`, `exportTableInfo`, `buildRelation`, `buildUpsertRule(s)`
395
- - `fastifyAutoSqlApi`, `*Routes`, `agentManifestRoutes`, `setupSwagger`
396
- - `SqlApi`, `createSqlApi`, `QueryClient`, `createQueryClient`, `pgQueryable`, `mysqlQueryable`
397
- - `agentToolSchemas`
398
- - Types: `ValidationError`, `ValidatorFn`, `BulkValidatorFn`, `JoinDefinition`, `SearchCondition`, `ConditionMethod`, `DbTables`
427
+ - `fastifyAutoSqlApi` (the one way to mount the routes), `SqlApi`, `createSqlApi`
428
+ - `defineTable`, `buildRelation`, `Nullable`, `Type`, `Static`, and the TypeBox types the signatures name: `TSchema`, `TObject`, `TUnsafe`
429
+ - for hooks: `httpError`, `TENANT_ADMIN`, `ConditionBuilder`, `Expression`, `ConditionValueOrUndefined`
430
+ - `QueryClient`, `createQueryClient`, `pgQueryable`, `mysqlQueryable`, and their parameter types `PgQueryable`, `MysqlQueryable`
431
+ - `agentToolSchemas`, `buildAgentManifest`, `renderAgentManifestMd`
432
+ - Types: those of the config (`DbTables`, `TableDefinition`, `TableConfig`, `JoinDefinition`, `BuildRelationOptions`, `TenantScope`…), of the hooks (`ApiRequest`, `ApiReply`, `ValidationField`, `ValidatorFn`, `ValidatorResult`, `BulkValidatorFn`, `WriteHookContext`, `PrimaryKeyValue`…), of `sqlApi` (`SqlApi*Params`, `JoinFetchRequest`, `JoinRefFilter`, `SearchResult`…), of the QueryClient (`BulkUpsertOptions`…), of the agent manifest (`AgentManifest`, `ManifestTable`, `ManifestField`, `ManifestJoin`) and of the CLI (`CliConfig`). Every type a public signature names is exported, except the building blocks of an exported one
433
+
434
+ Nothing else is public: the engines, route plugins, schema builders, naming helpers, dialect table and tenant resolution are internals.
399
435
 
400
436
  Dialects: PG uses `"id"`, `$1` and `RETURNING`. MySQL uses backticks, `?` and `insertId`. MariaDB is like MySQL but has `RETURNING` (10.5+). The CLI uses `pg` / `mysql2`.