fastify-auto-sqlapi 0.2.4 → 0.3.0

package/AGENTS_BACKEND.md

@@ -291,7 +291,18 @@ export const TableCustomer = defineTable({
 
 `exportTableInfo(Schema)` returns `{ Schema, filters, extraFilters }`. The `filters` function auto-builds WHERE conditions from any schema field present in the request.
 
-**Important**: there is no `tableName` key in `defineTable()`. The SQL table name comes from `Schema.tableName` (set by the CLI). The route URL name is the key you use in the `dbTables` record (e.g. `{ customer: TableCustomer }` → `/search/customer`).
+**Important**: there is no `tableName` key in `defineTable()`. The SQL table name comes from `Schema.tableName` (set by the CLI). The route URL name is the key you use in the `dbTables` record (e.g. `{ customer: TableCustomer }` → `/search/customer`). The key also names the table in search responses (`table`) and in the agent manifest.
+
+Because routes follow the key, the same physical table can be exposed by several table configs, each with its own `operations`, `onRequests`, `tenantScope`, `readExclude` and joins:
+
+```typescript
+export const dbTables: DbTables = {
+  conversation: TableConversation,             // owner: list, rename, delete
+  sharedConversation: TableSharedConversation, // anyone with the link: search only, shared rows only
+  conversationHistory: TableConversationHistory, // server-side only: operations: []
+};
+// → /search/conversation, /rest/conversation, /search/sharedConversation — all SQL on "conversation"
+```
 
 ### Composite primary key (link/junction tables)
 
@@ -869,7 +880,7 @@ const TableCustomer = defineTable({
 
 Behavior:
 - **Read** (search, get, delete, bulk-delete): adds `AND organization_id IN ($N)` to WHERE
-- **Insert**: auto-injects `organization_id` if single tenant; validates if already present (403 if mismatch); 400 if multi-tenant without explicit value
+- **Insert**: auto-injects `organization_id` if single tenant; validates if already present (403 if mismatch); 400 if multi-tenant without explicit value. The insert body (main and secondaries items) offers the column as **optional**, whatever the generated schema says: a single-tenant client omits it, a multi-tenant client names it. An admin (`getTenantId` → `null`) who omits it reaches the database's own `NOT NULL`, like any other column.
 - **Update**: strips `organization_id` from SET (can't change tenant), adds to WHERE condition
 - **Bulk upsert**: auto-injects on all records
 - **Upsert conflict guard** (`upsertMap` set): before the `ON CONFLICT DO UPDATE`, a probe rejects (403) any incoming conflict key that matches a row owned by another tenant — an upsert cannot overwrite or re-assign a foreign tenant's row.
@@ -922,7 +933,8 @@ Behavior:
 - **Insert**: no auto-injection. The payload must **anchor** the row: at least one listed column
   present and holding a tenant id → `400` if none is present, `403` if present but all foreign.
   The other parties are stored exactly as sent. A multi-id caller is never ambiguous here,
-  because nothing is being guessed.
+  because nothing is being guessed. Every listed column is **optional** in the insert body, so
+  the anchor rule is the runtime's to enforce, not the schema's.
 - **Update**: strips **every** listed column from the `SET` — neither party can be re-assigned —
   and adds the OR predicate to the `WHERE`. A row outside the scope answers `404`.
 - **Bulk upsert**: the anchor rule applies to every item (so an upsert must name a party even
@@ -948,9 +960,14 @@ getTenantId: (request) => {
 
 Uses `IN ($N, $M, ...)` for all WHERE clauses (same as single tenant, just with more values).
 
+An **empty array** is a caller who belongs to no tenant, not an admin: every request that
+reaches a scoped table (directly or through a relation) is refused with `403` before any SQL
+runs. `0` and `''` are ordinary tenant ids and filter like any other value.
+
 ### Admin bypass
 
-When `getTenantId` returns `null` or `undefined`, no filtering is applied (full access).
+When `getTenantId` returns `null` or `undefined`, no filtering is applied (full access). Only
+these two values bypass; `[]`, `0` and `''` do not.
 
 ### Tables without tenant
 
@@ -958,7 +975,8 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 ### Error codes
 
-- **403** — Record doesn't belong to tenant, or explicit tenant value doesn't match
+- **403** — Record doesn't belong to tenant, explicit tenant value doesn't match, or
+  `getTenantId` returned an empty array (a caller with no tenant at all)
 - **400** — Multi-tenant user on insert without explicit tenant value (ambiguous), or an
   `anyOf` write naming no owner column at all
 - **404** — Update with indirect tenant, record not found for this tenant; get/update/delete of
@@ -1214,6 +1232,48 @@ const TableUser = defineTable({
 For privileged transitions (promote to admin, move across tenants) prefer a dedicated
 endpoint with its own auth/audit, and keep the operation off the auto routes via `operations`.
 
+### Conditional update — claim a row atomically
+
+The `update` route matches the primary key (plus the tenant scope) and nothing else, so it
+cannot express "update only if the row is still in the state I saw": claiming a row that two
+clients must not both claim, a guarded state transition, optimistic locking on a `version`
+column. There is deliberately no auto route for that, nor for updating every row matching a
+filter ([ADR 0020](./docs/adr/0020-no-conditional-or-mass-update-route.md)). Write it as a
+custom route: the check and the write must be **one** `UPDATE`, which `db.update()` does with
+an `extraCondition`, returning how many rows it changed.
+
+```typescript
+import { ConditionBuilder, createQueryClient, pgQueryable, Type } from 'fastify-auto-sqlapi';
+import { SchemaRequest } from './schemas/SchemaRequest';
+
+const db = createQueryClient(pgQueryable(fastify.pg), 'postgres');
+
+fastify.post('/requests/:id/claim', {
+  schema: { params: Type.Object({ id: Type.Integer() }) },
+}, async (req, reply) => {
+  const { id } = req.params as { id: number };
+  const col = (f: string) => SchemaRequest.col(f);   // real column names: QueryClient speaks the DB's
+
+  const guard = new ConditionBuilder('AND', db.cbDialect)
+    .isNull(db.qi(col('inProgressSince')), true)              // the precondition — second arg enables it
+    .isEqual(db.qi(col('organizationId')), req.user.orgId);   // tenant: QueryClient applies none for you
+  // Record/where keys are quoted by db.update(); ConditionBuilder operands are raw SQL, so qi() them.
+
+  const affected = await db.update(
+    SchemaRequest.tableName,
+    { [col('inProgressSince')]: new Date(), [col('inProgressBy')]: req.user.id },
+    { [col('id')]: id },
+    guard
+  );
+  if (affected === 0) return reply.code(409).send({ message: 'Already claimed, or not found' });
+  return { claimed: true };
+});
+```
+
+`QueryClient` runs no hooks, no validation and **no tenant scoping**: the route owns all three.
+Keep the predicate server-chosen, as above. Letting the client name the column it compares on
+turns `affected` into an oracle on values it cannot read.
+
 ### Encrypt a column at rest (storage representation ≠ API representation)
 
 Three declarations on the table that owns the column — in on the write hooks, out on the read

package/AGENTS_FRONTEND.md

@@ -3,7 +3,7 @@
 This file is the request GRAMMAR. For this deployment's tables/fields/aliases (the
 vocabulary), fetch `GET {p}/agent/manifest.md` if available, or consult Swagger.
 
-Rules: all request/response fields are camelCase schema field names — how the database names its columns is invisible here and irrelevant, the server maps them. `{p}` = deployment prefix (e.g. `/api`). Join keys are backend-declared ALIASES (default = joined table name; list per table in Swagger). Write responses are PK-only. Write bodies reject unknown properties (400) — send only real schema fields. Arrays for bulk are capped (default 1000/request; chunk client-side). Composite-PK tables have no get/delete/bulk-delete (404) — use search / update.
+Rules: all request/response fields are camelCase schema field names — how the database names its columns is invisible here and irrelevant, the server maps them. `{p}` = deployment prefix (e.g. `/api`). `{table}` = the table's key in the manifest, which may differ from the database table name (one table can be exposed under several keys, each with its own rules). Join keys are backend-declared ALIASES (default = joined table name; list per table in Swagger). Write responses are PK-only. Write bodies reject unknown properties (400) — send only real schema fields. Arrays for bulk are capped (default 1000/request; chunk client-side). Composite-PK tables have no get/delete/bulk-delete (404) — use search / update.
 
 ## Endpoints
 

package/BREAKING_CHANGES.md

@@ -692,3 +692,55 @@ beforeInsert: async (db, req, record) => {
   if (req.routeOptions?.url?.startsWith('/rest/')) await notify(record);  // side effect: narrow it
 },
 ```
+
+---
+
+# Breaking Change — the route URL is the `DbTables` key
+
+*Landed in **0.3.0**.*
+
+## Why this changed
+
+The documentation always said *"the route URL name is the key you use in the `dbTables`
+record"*, and everything but the URL agreed: the handler, `operations`, `onRequests`, the
+Swagger tags and the agent manifest all resolved the table config by its key. The URL alone was
+built from `Schema.tableName`. Two consequences:
+
+- **Several table configs over one physical table could not coexist.** Exposing
+  `conversation` once for its owner and once for whoever holds a share link — each key with its
+  own `operations`, guards and joins — put both on `/search/conversation`, and Fastify refused
+  to start: `Method 'POST' already declared for route '/search/conversation'`.
+- **A renamed key was served under the wrong name.** `{ orders: TableCustomerOrder }` started
+  fine, but answered on `/search/customer_order` while the manifest told agent clients to call
+  `orders`.
+
+## What changed
+
+- Every auto route is named after the key: `/search/<key>`, `/rest/<key>`, `/rest/<key>/:id`,
+  `/bulk/<key>`, `/bulk/<key>/delete`.
+- The search response's `table` is the key, so it matches the URL that was called and the
+  manifest entry.
+- SQL is unchanged: it still targets `Schema.tableName`.
+
+## Who is affected
+
+- **A `DbTables` key of yours differs from its schema's `tableName`.** Its routes move from the
+  table name to the key, and `table` in its search responses changes the same way.
+
+Not affected: configs generated by `sqlapi-generate-tables`, whose keys are the table names, and
+any hand-written config that kept that convention.
+
+## Migration
+
+Either call the new URLs, or rename the key back to the table name to keep the old ones:
+
+```typescript
+// before: routes answered on /search/customer_order
+export const dbTables: DbTables = { orders: TableCustomerOrder };
+
+// keep the old URLs
+export const dbTables: DbTables = { customer_order: TableCustomerOrder };
+```
+
+A client that read `table` from a search response to recover the physical table name should
+use the key it called instead — that is now what `table` returns.

package/CHANGELOG.md

@@ -7,6 +7,71 @@ All notable changes to this project are documented here. This project follows
 
 Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)**.
 
+## [Unreleased]
+
+## [0.3.0]
+
+### Changed
+
+- **BREAKING: the route URL is the `DbTables` key, as documented.** Every auto route built its
+  URL from `Schema.tableName` while the handler, `operations`, the Swagger tags and the agent
+  manifest all used the key. Two table configs over the same physical table (an owner view and
+  a shared-link view of `conversation`) collided on `/search/conversation` and the app refused
+  to start; a single renamed key started fine but was served under the table name, so the
+  manifest advertised a URL that did not exist. Routes are now `/search/<key>`,
+  `/rest/<key>`, `/bulk/<key>`, and the search response's `table` names the key too. Configs
+  generated by `sqlapi-generate-tables` use the table name as key and are unaffected. See
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--the-route-url-is-the-dbtables-key).
+- **`fastify-plugin` 5 → 6.** The only runtime dependency bump: v6 renames its entry files and
+  drops the long-deprecated `PluginOptions` type (now `PluginMetadata`), neither of which this
+  library uses. No change for consumers; still Fastify 5.
+- **Development dependencies updated** — `@fastify/swagger-ui` 6 (still covered by the
+  `>=5.0.0` peer range), `fastify` pinned to 5.12.4, and the latest minors of the lint and
+  gate tooling. TypeScript stays on 5.9: `typescript-eslint` does not support TypeScript 7 yet.
+
+### Fixed
+
+- **An empty tenant list is refused, not executed.** `getTenantId` returning `[]` (a caller
+  who belongs to no tenant) used to reach the database as `organization_id IN ()` — a syntax
+  error on both dialects, so a `500` that failed closed only by accident, and one step away
+  from a leak had any builder dropped the empty predicate. `resolveTenant` now answers `403`
+  before any SQL exists, on every operation and through relations from an unscoped host.
+  `null`/`undefined` remain the only admin values; `0` and `''` remain ordinary tenant ids.
+- **The tenant column is optional in the insert body.** The engine injects it for a
+  single-tenant caller and validates it for a multi-tenant or `anyOf` one, yet the body schema
+  still required it whenever the generated schema did — so the documented injection answered
+  `400 must have required property` over HTTP, and the only way out was a `schemaOverrides`
+  workaround (or `excludeFromCreation`, which silently broke multi-tenant callers by stripping
+  the value they must send). The own column of a direct scope and every column of an `anyOf`
+  scope are now `Optional` on insert `main` and on secondaries items of every write body — the
+  same rule that already made a secondary's FK optional. Indirect scopes are untouched: their
+  FK is an ordinary field.
+
+### Documentation
+
+- **[ADR 0020](./docs/adr/0020-no-conditional-or-mass-update-route.md): no conditional or mass
+  update route.** A conditional `updateWhere` operation was designed and rejected: it would be
+  the first route writing N rows chosen by the client, and it cuts across `QueryClient.update`,
+  the search condition builder, the tenant guards and the hook contract. Compare-and-set
+  (claiming a row two clients must not both claim) is a custom route on
+  `db.update(table, fields, where, extraCondition)`; `AGENTS_BACKEND.md` carries the pattern
+  ("Conditional update — claim a row atomically").
+
+### Internal
+
+- **Tenant isolation test audit.** New specs pin what was enforced but unproven: the tenant
+  reaches every HTTP route and every `SqlApi` method; `deletions` bind the child to the main
+  row FK (an unscoped child under a scoped parent included) and follow indirect and `anyOf`
+  child scopes; a secondary cannot be re-parented by a payload FK; upserted secondaries are
+  conflict-guarded on update and bulk upsert; a multi-tenant caller cannot write an unanchored
+  secondary; direct-scope update and bulk upsert; indirect-scope delete and bulk delete; request
+  predicates on the tenant column never widen the scope; an indirect join-table scope through a
+  third table is enforced inside `joinMustExist`, `joinGroup` and aggregation subqueries.
+- **`swagger: true` is now tested.** `setupSwagger` swallows a failed import of
+  `@fastify/swagger`/`@fastify/swagger-ui` and only logs a warning, so a dependency bump that
+  broke the documentation would have passed every test. Unit tests now assert the served
+  OpenAPI spec and UI — default path, custom `SwaggerOptions`, and under the plugin `prefix`.
+
 ## [0.2.4]
 
 ### Added
@@ -620,6 +685,18 @@ the join API redesign (documented in [BREAKING_CHANGES.md](./BREAKING_CHANGES.md
 primary key support in updates, transactional insert/update with secondaries, the hook matrix,
 and bulk operations.
 
+[Unreleased]: https://github.com/LucaRainone/fastify-auto-sqlapi/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.3.0
+[0.2.4]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.4
+[0.2.3]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.3
+[0.2.2]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.2
+[0.2.1]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.1
+[0.2.0]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.2.0
+[0.1.14]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.14
+[0.1.13]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.13
+[0.1.12]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.12
+[0.1.11]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.11
+[0.1.10]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.10
 [0.1.7]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.7
 [0.1.6]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.6
 [0.1.5]: https://github.com/LucaRainone/fastify-auto-sqlapi/releases/tag/v0.1.5

package/dist/lib/schema/helpers.d.ts

@@ -5,6 +5,13 @@ import type { ITable, SchemaDefinition, DbTables, JoinDefinition } from '../../t
  * Falls back to `fallback` field if tableConf is undefined.
  */
 export declare function pkSchema(tableConf: ITable | undefined, schema: SchemaDefinition, fallback: string): Record<string, TSchema>;
+/**
+ * Make the tenant column(s) of a scoped table Optional in a write body. The engine injects the
+ * value for a single-tenant caller and validates the one a multi-tenant or `anyOf` caller sends,
+ * so the body must offer the field without demanding it — the same reason a secondary's FK is
+ * Optional. `tenantScope` names real DB columns; the schema field is found through `col()`.
+ */
+export declare function relaxTenantColumns(fields: Record<string, TSchema>, tableConf: ITable | undefined, schema: SchemaDefinition): void;
 /** The same schema without the Optional modifier, i.e. as a required property. */
 export declare function asRequired(schema: TSchema): TSchema;
 /**

package/dist/lib/schema/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAKzF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3H;AAiCD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,KAAK,iBAAiB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,MAAM,GAAG,SAAS,KAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwB7B;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7F,IAAI,CA8BN;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,iBACmB,CAAC;AAEtD,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,iBACG,CAAC;AAE1C,4DAA4D;AAC5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAMzF;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQ3H;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,GACvB,IAAI,CAMN;AAoCD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAGnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAED,KAAK,iBAAiB,GAAG,CACvB,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,MAAM,GAAG,SAAS,KAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwB7B;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,eAAe,EAAE,iBAAiB,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7F,IAAI,CA8BN;AAED,qGAAqG;AACrG,eAAO,MAAM,mBAAmB,EAAE,iBACmB,CAAC;AAEtD,uDAAuD;AACvD,eAAO,MAAM,uBAAuB,EAAE,iBACG,CAAC;AAE1C,4DAA4D;AAC5D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOzB"}

package/dist/lib/schema/helpers.js

@@ -1,6 +1,7 @@
 import { Type, OptionalKind } from '@sinclair/typebox';
 import { readableFieldNames } from '../read-access.js';
 import { writableFields } from '../write-access.js';
+import { tenantOwnColumns } from '../tenant.js';
 import { findSecondaryTableConf } from '../engine/write-helpers.js';
 /**
  * Build a PK-only schema for response shapes (single or composite PK).
@@ -15,10 +16,26 @@ export function pkSchema(tableConf, schema, fallback) {
     }
     return result;
 }
+/**
+ * Make the tenant column(s) of a scoped table Optional in a write body. The engine injects the
+ * value for a single-tenant caller and validates the one a multi-tenant or `anyOf` caller sends,
+ * so the body must offer the field without demanding it — the same reason a secondary's FK is
+ * Optional. `tenantScope` names real DB columns; the schema field is found through `col()`.
+ */
+export function relaxTenantColumns(fields, tableConf, schema) {
+    const columns = tenantOwnColumns(tableConf?.tenantScope);
+    if (columns.length === 0)
+        return;
+    for (const field of Object.keys(fields)) {
+        if (columns.includes(schema.col(field)))
+            fields[field] = Type.Optional(fields[field]);
+    }
+}
 /**
  * Build secondary table fields for body schemas:
  * - FK field becomes Optional (auto-filled from main)
  * - excludeFromCreation fields become Optional
+ * - tenant column(s) become Optional (injected or validated by the engine)
  */
 function buildSecondaryFields(joinSchema, joinField, secondaryTableConf) {
     const fields = writableFields({ ...joinSchema.fields }, secondaryTableConf, joinSchema);
@@ -32,6 +49,7 @@ function buildSecondaryFields(joinSchema, joinField, secondaryTableConf) {
             }
         }
     }
+    relaxTenantColumns(fields, secondaryTableConf, joinSchema);
     return fields;
 }
 /** The same schema without the Optional modifier, i.e. as a required property. */

package/dist/lib/schema/insert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/insert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAU/C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CA+B9E;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAalF"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/insert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAErE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAW/C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAiC9E;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAalF"}

package/dist/lib/schema/insert.js

@@ -1,7 +1,7 @@
 import { Type } from '@sinclair/typebox';
 import { primaryAsString } from '../../types.js';
 import { writableFields } from '../write-access.js';
-import { pkSchema, applySchemaOverrides, attachWriteJoinSections, writeJoinBodyFields, writeJoinResponseFields, } from './helpers.js';
+import { pkSchema, applySchemaOverrides, attachWriteJoinSections, relaxTenantColumns, writeJoinBodyFields, writeJoinResponseFields, } from './helpers.js';
 export function InsertTableBody(dbTables, tableName) {
     const tableConf = dbTables[tableName];
     const schema = tableConf.Schema;
@@ -15,6 +15,8 @@ export function InsertTableBody(dbTables, tableName) {
                 mainFields[field] = Type.Optional(mainFields[field]);
         }
     }
+    // The tenant column is the engine's to fill or check, never the client's to be forced to send.
+    relaxTenantColumns(mainFields, tableConf, schema);
     const bodyProperties = {
         // additionalProperties:false makes the schema the real write whitelist — unknown keys are
         // rejected (400) instead of silently reaching the INSERT as columns (mass assignment).

package/dist/lib/tenant.d.ts

@@ -2,6 +2,12 @@ import type { ApiRequest } from '../types/request.js';
 import type { QueryClient } from './db.js';
 import { ConditionBuilder, type ConditionValue, type ConditionValueOrUndefined } from 'node-condition-builder';
 import type { ITable, SqlApiPluginOptions, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantScopeAnyOf, TenantContext } from '../types.js';
+/**
+ * The columns of a scoped table that the engine fills or validates on insert, i.e. the ones a
+ * write body must offer without requiring: the own column of a direct scope, every column of an
+ * `anyOf` scope. An indirect scope names no column of its own — its FK is an ordinary field.
+ */
+export declare function tenantOwnColumns(scope: TenantScope | undefined): string[];
 export declare function resolveTenant(options: SqlApiPluginOptions, tableConf: ITable, request: ApiRequest): Promise<TenantContext | undefined>;
 /**
  * The read predicate for a scope, as a fragment every caller appends to its own WHERE.

package/dist/lib/tenant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/lib/tenant.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/lib/tenant.ts"],"names":[],"mappings":"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"}

package/dist/lib/tenant.js

@@ -14,6 +14,16 @@ function isAnyOf(scope) {
 function ownColumns(scope) {
     return isAnyOf(scope) ? scope.anyOf : [scope.column];
 }
+/**
+ * The columns of a scoped table that the engine fills or validates on insert, i.e. the ones a
+ * write body must offer without requiring: the own column of a direct scope, every column of an
+ * `anyOf` scope. An indirect scope names no column of its own — its FK is an ordinary field.
+ */
+export function tenantOwnColumns(scope) {
+    if (!scope || isIndirect(scope))
+        return [];
+    return ownColumns(scope);
+}
 /**
  * Whether this request could touch a scoped row at all: the addressed table is scoped, or one of
  * the tables it can reach through a declared relation is.
@@ -44,6 +54,12 @@ export async function resolveTenant(options, tableConf, request) {
     if (raw == null)
         return undefined; // admin
     const ids = Array.isArray(raw) ? raw : [raw];
+    // An empty list is a caller with no tenant at all — not an admin. Every consumer of `ids`
+    // would emit `IN ()` (a syntax error on both dialects) or, worse, a builder could drop the
+    // empty predicate and open the table. Refuse here, once, before any SQL exists.
+    if (ids.length === 0) {
+        throw httpError(403, 'Tenant required: the caller belongs to no tenant');
+    }
     // `scope` stays undefined for an unscoped host: the ids still travel, so the tables it reaches
     // enforce their own scopes, while the host itself keeps no filter.
     return { ids, scope: tableConf.tenantScope };

package/dist/routes/auto/bulk-delete.routes.js

@@ -7,7 +7,7 @@ export default async function bulkDeleteRoutes(fastify, options) {
         operation: 'bulkDelete',
         singlePkOnly: true,
         method: 'POST',
-        url: (tc) => `/bulk/${tc.Schema.tableName}/delete`,
+        url: (tableName) => `/bulk/${tableName}/delete`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: BulkDeleteTableBody(db, table, options.maxBulkItems ?? DEFAULT_MAX_BULK_ITEMS),

package/dist/routes/auto/bulk-upsert.routes.js

@@ -5,7 +5,7 @@ export default async function bulkUpsertRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'bulkUpsert',
         method: 'PUT',
-        url: (tc) => `/bulk/${tc.Schema.tableName}`,
+        url: (tableName) => `/bulk/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: BulkUpsertTableBody(db, table, options.maxBulkItems ?? DEFAULT_MAX_BULK_ITEMS),

package/dist/routes/auto/delete.routes.js

@@ -6,7 +6,7 @@ export default async function deleteRoutes(fastify, options) {
         operation: 'delete',
         singlePkOnly: true,
         method: 'DELETE',
-        url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
+        url: (tableName) => `/rest/${tableName}/:id`,
         successStatus: 200,
         schemas: (_db, _table, tc) => {
             const pkField = primaryAsString(tc.primary);

package/dist/routes/auto/get.routes.js

@@ -6,7 +6,7 @@ export default async function getRoutes(fastify, options) {
         operation: 'get',
         singlePkOnly: true,
         method: 'GET',
-        url: (tc) => `/rest/${tc.Schema.tableName}/:id`,
+        url: (tableName) => `/rest/${tableName}/:id`,
         successStatus: 200,
         schemas: (db, table) => ({
             params: Type.Object({ id: Type.String() }),

package/dist/routes/auto/insert.routes.js

@@ -4,7 +4,7 @@ export default async function insertRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'insert',
         method: 'POST',
-        url: (tc) => `/rest/${tc.Schema.tableName}`,
+        url: (tableName) => `/rest/${tableName}`,
         successStatus: 201,
         schemas: (db, table) => ({
             body: InsertTableBody(db, table),

package/dist/routes/auto/route-helpers.d.ts

@@ -18,8 +18,11 @@ export interface AutoRouteSpec {
      */
     singlePkOnly?: boolean;
     method: 'GET' | 'POST' | 'PUT' | 'DELETE';
-    /** URL builder receiving the table configuration to read `Schema.tableName`. */
-    url: (tableConf: ITable) => string;
+    /**
+     * URL builder receiving the `DbTables` key — never `Schema.tableName`: several table
+     * configs may expose the same physical table, and each key needs its own route.
+     */
+    url: (tableName: string) => string;
     successStatus: 200 | 201;
     /** Build per-table schemas (body, params, querystring, response). Response is wrapped with `{ [successStatus]: ... }` automatically. */
     schemas: (dbTables: DbTables, tableName: string, tableConf: ITable) => RouteSchema;

package/dist/routes/auto/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C;;;OAGG;IACH,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

package/dist/routes/auto/route-helpers.js

@@ -72,7 +72,7 @@ export async function registerForAllTables(fastify, options, spec) {
         const schemas = spec.schemas(DbTables, tableName, tableConf);
         fastify.route({
             method: spec.method,
-            url: spec.url(tableConf),
+            url: spec.url(tableName),
             schema: buildRouteSchema(tableName, tableConf, spec, schemas),
             onRequest: mergeOnRequests(options, tableConf),
             handler: async (request, reply) => {

package/dist/routes/auto/search.routes.js

@@ -6,7 +6,7 @@ export default async function searchRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'search',
         method: 'POST',
-        url: (tc) => `/search/${tc.Schema.tableName}`,
+        url: (tableName) => `/search/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: SearchTableBodyPost(db, table),
@@ -24,7 +24,7 @@ export default async function searchRoutes(fastify, options) {
                 leftAliases.length && `Available joinLeft aliases: ${leftAliases.join(', ')}`,
             ].filter(Boolean).join('. ');
         },
-        handle: async (fastify, tableName, tc, request) => {
+        handle: async (fastify, tableName, _tc, request) => {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const body = request.body;
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -52,7 +52,7 @@ export default async function searchRoutes(fastify, options) {
                 computeAvg: query.computeAvg,
                 maxRows,
             }, request);
-            return { table: tc.Schema.tableName, ...result };
+            return { table: tableName, ...result };
         },
     });
 }

package/dist/routes/auto/update.routes.js

@@ -4,7 +4,7 @@ export default async function updateRoutes(fastify, options) {
     await registerForAllTables(fastify, options, {
         operation: 'update',
         method: 'PUT',
-        url: (tc) => `/rest/${tc.Schema.tableName}`,
+        url: (tableName) => `/rest/${tableName}`,
         successStatus: 200,
         schemas: (db, table) => ({
             body: UpdateTableBody(db, table),

package/docs/adr/0020-no-conditional-or-mass-update-route.md

@@ -0,0 +1,68 @@
+# 0020. No conditional or mass update route — a predicate write is a custom route
+
+- **Status**: accepted
+- **Date**: 2026-09-24
+
+## Context
+
+The `update` route addresses exactly one row: its `WHERE` is every primary key column plus
+the tenant scope, and nothing the client sends can add to it. Two real needs fall outside
+that shape:
+
+- **Compare-and-set.** Claiming a row so that two clients cannot both claim it
+  (`UPDATE … SET in_progress_since = now() WHERE id = ? AND in_progress_since IS NULL`),
+  guarded state transitions (`… AND status = 'draft'`), optimistic locking on a `version`
+  column. Correctness depends on the check and the write being one statement; a
+  `beforeUpdate` that reads first and writes after is exactly the race it is meant to
+  prevent.
+- **Mass update by predicate.** Setting a value on every row matching a filter.
+
+A route was designed to cover both: a new `updateWhere` operation, opt-in (registered only
+when listed in `operations`), `PUT {p}/update/{key}` with `{ where: { filters, conditions },
+fields }` reusing the search grammar, the tenant guard injected, `validate`/`beforeUpdate`
+run on `fields`, `{ affected }` in response. Compare-and-set is then a `where` that includes
+the primary key.
+
+## Decision
+
+The plugin does not expose a conditional or mass update route, and the single-row `update`
+does not accept a precondition. A write whose target is a predicate is built as a custom
+route on `QueryClient.update(table, fields, where, extraCondition)`, which already takes a
+`ConditionBuilder` and returns the number of rows it changed.
+
+The design was sound; the cost was not worth it. It is the first route that writes N rows
+chosen by the client, so a defect in it is destructive and tenant-crossing rather than a
+wrong answer. Building it touches several security-sensitive pieces at once:
+
+- `QueryClient.update`, which today assumes an equality `where` and would emit `WHERE  AND …`
+  for a condition-only one;
+- the search condition builder, shared with every read;
+- the tenant guards, which on update are keyed on a primary key (`assertTenantOwnership`)
+  and would need the row-guard form for indirect scopes instead;
+- the meaning of `validate`, `beforeUpdate` and `afterUpdate`, whose `record` would no longer
+  carry a primary key — breaking any existing hook that reads one.
+
+Against that, the need is narrow and the custom route is a few lines, owned by the consumer
+who knows the predicate it must enforce.
+
+## Alternatives considered
+
+- **`updateWhere` operation, opt-in** — the design above. Rejected for the risk and blast
+  radius described in the decision, not for a flaw in its shape.
+- **`expect` on the single-row `update`** (a precondition next to the primary key, `409` when
+  it fails) — rejected: it narrows the write instead of widening it, so the blast radius is
+  small, but it still reopens the update `WHERE` to client-supplied predicates, and it needs
+  a readability rule to avoid an oracle (see Consequences). One custom route covers it.
+- **Read-then-write in `beforeUpdate`** — not an alternative: two concurrent requests both
+  pass the read.
+
+## Consequences
+
+- Compare-and-set and predicate updates are custom routes. [AGENTS_BACKEND.md](../../AGENTS_BACKEND.md)
+  carries the pattern ("Conditional update — claim a row atomically").
+- Everything the auto routes do for free is the custom route's job there: `QueryClient` runs
+  no hooks, no validation and **no tenant scoping**, so the route must add its own tenant
+  predicate and must not let a client-chosen predicate reach a column the caller cannot read —
+  otherwise `affected: 0 | 1` becomes an oracle on its value.
+- Revisit only with a concrete, repeated need that a custom route serves badly; the design
+  notes above are the starting point.

package/docs/adr/README.md

@@ -34,6 +34,7 @@ not by editing history.
 | [0017](./0017-the-schema-is-the-contract.md) | The database schema is the API contract — by default, and only by default |
 | [0018](./0018-one-seam-to-the-http-framework.md) | The HTTP framework is reachable through one seam — `ApiRequest` |
 | [0019](./0019-column-exclusion-is-generation-time-config.md) | Removing a column from the API is generation-time config — `excludeColumns`, never a Schema edit |
+| [0020](./0020-no-conditional-or-mass-update-route.md) | No conditional or mass update route — a predicate write is a custom route |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",
@@ -83,20 +83,20 @@
   "homepage": "https://github.com/LucaRainone/fastify-auto-sqlapi#readme",
   "dependencies": {
     "@sinclair/typebox": "^0.34.14",
-    "fastify-plugin": "^5.1.0",
+    "fastify-plugin": "^6.0.0",
     "node-condition-builder": "^1.2.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@fastify/postgres": "^6.0.2",
     "@fastify/swagger": "^9.0.0",
-    "@fastify/swagger-ui": "^5.0.0",
+    "@fastify/swagger-ui": "^6.1.1",
     "@types/node": "^22.13.4",
     "@types/pg": "^8.11.11",
     "dependency-cruiser": "^18.1.0",
     "eslint": "^10.8.0",
     "eslint-plugin-sonarjs": "^4.2.0",
-    "fastify": "5.8.5",
+    "fastify": "5.12.4",
     "fuse.js": "^7.5.0",
     "jscpd": "^5.0.14",
     "knip": "^6.31.0",