fastify-auto-sqlapi 0.2.3 → 0.3.0

package/AGENTS.md

@@ -6,7 +6,7 @@ You are configuring a Fastify server that uses `fastify-auto-sqlapi` to auto-gen
 
 The plugin generates REST endpoints (search, get, insert, update, delete, bulk upsert, bulk delete) from database table definitions. No ORM — raw SQL. Supports **PostgreSQL**, **MySQL**, and **MariaDB**. The consumer defines table configurations, and the plugin handles routing, validation, and query execution.
 
-**The database schema is the API contract, on purpose.** The exposed shape follows the stored shape *by default*, and every part of that default is overridable — `readExclude`, `writeExclude`, a trimmed Schema, `schemaOverrides`, `computedFields`, `afterRead`, `operations`, relation `alias`/`fields`, `extraFilters`. Two consequences for how you work:
+**The database schema is the API contract, on purpose.** The exposed shape follows the stored shape *by default*, and every part of that default is overridable — `readExclude`, `writeExclude`, `excludeColumns` (CLI config), `schemaOverrides`, `computedFields`, `afterRead`, `operations`, relation `alias`/`fields`, `extraFilters`. Two consequences for how you work:
 
 - Do not propose a DTO or mapping layer, and do not reshape a response by hand in a route wrapper. Reach for the lever that matches the concern (the table is in [ADR 0017](./docs/adr/0017-the-schema-is-the-contract.md)); when none fits, the operation is not CRUD — write a custom route and call `app.sqlApi.*` inside it, which keeps filters, joins, tenant scoping, hooks and validation.
 - The target surface is internal: back-office and admin tools where the schema *is* the domain model. If the user is building a **public or third-party API** — consumers they cannot redeploy with their schema, a versioned contract — say so, and keep those tables off the auto routes via `operations` rather than generating the surface from the schema.

package/AGENTS_BACKEND.md

@@ -58,13 +58,16 @@ export default {
   dialect: 'postgres',         // 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
   // envFile: '../../.env',    // path to .env file, relative to cwd (default: '.env')
   // excludeTables: ['knex_*'],// tables invisible to schema generation (see below)
+  // excludeColumns: ['*.password_hash'], // columns invisible to schema generation (see below)
 };
 ```
 
-That's it — only these five fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`. The `envFile` is useful in monorepo setups where the `.env` lives at the repo root.
+That's it — only these six fields exist. **No connection string, no migration path.** If the file is missing, defaults are used. The `dialect` can also be passed via CLI flag `--dialect mysql`. The `envFile` is useful in monorepo setups where the `.env` lives at the repo root.
 
 **`excludeTables`** keeps migration bookkeeping, PostGIS internals and the like out of generation: exact table names or `*` globs, matched against the **DB table name** (not the generated schema name), with everything else literal. An excluded table is invisible to the generator — its schema file is not created, and one generated by an earlier run is removed as an orphan on the next full run, exactly like the schema of a dropped table. See [ADR 0009](./docs/adr/0009-schema-exclusion-config-blacklist.md).
 
+**`excludeColumns`** does the same for single columns: `"<table>.<column>"` entries matched against the **DB names** (not the generated field names), with `*` as a wildcard on either side — `'user.password_hash'`, `'*.internal_*'`, `'audit_*.raw_payload'`. An excluded column does not exist for the API at all: it is not in the Schema, so no route reads, writes, filters or orders by it, and the manifest never lists it. This is the lever for *"this column must not exist for the API"*; `readExclude` / `writeExclude` on the table config are for a column that stays in the Schema and loses one side. A primary key column cannot be excluded (every route identifies rows with it), and a pattern that would leave a table with no columns fails the run: that is `excludeTables`' job. Never edit a generated Schema file by hand — it is overwritten on the next run. See [ADR 0019](./docs/adr/0019-column-exclusion-is-generation-time-config.md).
+
 ### 3. Configure database connection (env vars)
 
 The CLI reads DB connection from environment variables (NOT from the config file). `DATABASE_URL` takes priority for all dialects.
@@ -288,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)
 
@@ -866,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.
@@ -919,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
@@ -945,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
 
@@ -955,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
@@ -1014,8 +1035,8 @@ output, it is the part that does not depend on anyone opening the generated file
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
 - **Nullable columns use `Nullable(T)` (type-array form)**: the generator emits `Type.Optional(Nullable(T))` for nullable columns — `Nullable` (exported by the package) produces `{ type: ['integer', 'null'] }`. Do NOT replace it with `Type.Union([T, Type.Null()])`: under Fastify's default Ajv `coerceTypes` a union corrupts values through its branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first), while the type array validates and serializes NULL correctly. A bare `Type.Optional(T)` is also wrong: NULL serializes as `0`/`""`. In `filters`, an explicit `null` on a schema field builds `WHERE col IS NULL`.
 - **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks. It strips **client-supplied** values only: the payload is sanitized before `beforeInsert` runs, so a value the hook assigns to an excluded field (e.g. a server-generated TEXT id) DOES reach the INSERT. Same for the engine's FK auto-fill on secondaries — an excluded FK column does not suppress it. It is an **ergonomics tool for creation, NOT a field-level security mechanism**: it does not apply to updates — every Schema field is updatable by default, by design. Field-level update rules (`isAdmin`, roles, owner/tenant columns, state fields) are product logic: enforce them in `beforeUpdate` (silent strip) or `validate` (loud 400), or move the privileged transition to a dedicated endpoint and keep it off the auto routes via `operations`.
-- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes. It is **per table and static**: a column hidden here is hidden from every caller, including admins. To keep a column readable on the table's own routes but not through a relation, trim the Schema the *relation* is declared with instead — see the read-grant warning under [buildRelation](#buildrelation-signature).
-- **`writeExclude`**: the write-side counterpart of `readExclude` — fields removed from the insert, update and bulk-upsert bodies (main *and* secondaries) and dropped again inside the engines, which `sqlApi.*` reaches without those schemas. Reads are untouched: the field is still projected, filterable and orderable. It exists for the columns the database refuses to be told about. **A `GENERATED ALWAYS AS (<expr>)` column is already covered without any config**: the CLI records it in the Schema's `generatedFields`, and both engines reject a statement that so much as names such a column, so offering it as writable could only turn a client mistake into a `500`. The `writeExclude` key is for the rest — a column a trigger owns, one a migration is about to drop. It is **static and applies to everyone**, admins included; a rule that depends on *who* is asking is product logic and belongs in `beforeUpdate` (silent strip) or `validate` (loud 400), per [ADR 0004](./docs/adr/0004-updates-always-open.md). Not to be confused with `excludeFromCreation`, which whitelists **client input on insert only** and deliberately lets a hook assign the field afterwards — `writeExclude` runs **after** the hooks, because the column refuses the value whoever assigned it. `defineTable` rejects a field that is not in the schema, the primary key (the update body identifies the row with it) and a field that is also in `readExclude` (neither readable nor writable means: remove it from the Schema). See [ADR 0015](./docs/adr/0015-non-writable-columns.md), which narrows [ADR 0004](./docs/adr/0004-updates-always-open.md).
+- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to `excludeColumns` in `sqlapi.config.ts`, which removes the column from the Schema, hence from reads *and* writes. It is **per table and static**: a column hidden here is hidden from every caller, including admins. To keep a column readable on the table's own routes but not through a relation, trim the Schema the *relation* is declared with instead — see the read-grant warning under [buildRelation](#buildrelation-signature).
+- **`writeExclude`**: the write-side counterpart of `readExclude` — fields removed from the insert, update and bulk-upsert bodies (main *and* secondaries) and dropped again inside the engines, which `sqlApi.*` reaches without those schemas. Reads are untouched: the field is still projected, filterable and orderable. It exists for the columns the database refuses to be told about. **A `GENERATED ALWAYS AS (<expr>)` column is already covered without any config**: the CLI records it in the Schema's `generatedFields`, and both engines reject a statement that so much as names such a column, so offering it as writable could only turn a client mistake into a `500`. The `writeExclude` key is for the rest — a column a trigger owns, one a migration is about to drop. It is **static and applies to everyone**, admins included; a rule that depends on *who* is asking is product logic and belongs in `beforeUpdate` (silent strip) or `validate` (loud 400), per [ADR 0004](./docs/adr/0004-updates-always-open.md). Not to be confused with `excludeFromCreation`, which whitelists **client input on insert only** and deliberately lets a hook assign the field afterwards — `writeExclude` runs **after** the hooks, because the column refuses the value whoever assigned it. `defineTable` rejects a field that is not in the schema, the primary key (the update body identifies the row with it) and a field that is also in `readExclude` (neither readable nor writable means: `excludeColumns` in `sqlapi.config.ts`). See [ADR 0015](./docs/adr/0015-non-writable-columns.md), which narrows [ADR 0004](./docs/adr/0004-updates-always-open.md).
 - **Database-computed and identity columns are detected by the CLI**: `sqlapi-generate-schema` reads `is_generated` (PostgreSQL) / `GENERATION_EXPRESSION` (MySQL, non-empty only for a real `GENERATED ALWAYS AS (...)` column; `EXTRA` is a fallback matched on `VIRTUAL GENERATED` / `STORED GENERATED`, never on the word alone — MySQL writes `DEFAULT_GENERATED` there for any default *expression*, `DEFAULT CURRENT_TIMESTAMP` included, and such a column is writable) and prints the columns it found, per table, before writing anything — read that output. Generated columns land in the Schema's `generatedFields` and are named in a comment in the generated `Table*.ts`. Separately, `GENERATED ... AS IDENTITY` (PostgreSQL) has no `column_default` to reveal that the database fills it in: it is now flagged like MySQL's `AUTO_INCREMENT`, so the field is Optional and the CLI lists it under `excludeFromCreation` instead of emitting a mandatory primary key the database then refuses.
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
 - **`schemaOverrides`**: narrow an auto-generated field to a stricter TypeBox type (e.g. `{ email: Type.String({ format: 'email' }) }`) where `information_schema` could only report `text`. **Write bodies only** — insert, update, bulk-upsert. An override rules what the API accepts *from now on*, while the rows already stored predate it: a column narrowed to `format: 'email'` today holds whatever was accepted last year, and one made mandatory today is `NULL` on every pre-existing row. Narrowing the response would publish a promise nobody can retroactively make true, so responses and the `filters` map keep the generated type. (Nothing would break at runtime either way — Fastify does not validate responses, and `fast-json-stringify` ignores `format`/`pattern`/`minLength`/`minimum`/`enum` entirely; it acts only on `type`, by coercion.) The override is taken **verbatim**: no `Type.Optional` makes the field mandatory, no `Nullable` rejects an explicit `null`, whatever the column allows — which is how you make a column the DB had to leave nullable (a new column on a populated table) mandatory going forward. The original Schema file is never modified; the primary key is mandatory in the update body (it identifies the row); overrides appear in Swagger.
@@ -1025,7 +1046,7 @@ output, it is the part that does not depend on anyone opening the generated file
 - **All hooks and validators receive camelCase records**: `validate` and the whole hook matrix (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`, `afterRead`) get records keyed by schema field names (camelCase). Mutations propagate to the SQL (plugin converts to DB column format via `colMap` after the hook). The engine internally uses `snakecaseRecord(..., schema)` after user mutations to map field names to actual DB columns.
 - **Secondaries run the child table's `beforeInsert`**: a child row written alongside a main record is a write like any other — the child's `excludeFromCreation`, its `tenantScope` and its `beforeInsert` all apply, in that order, before the engine auto-fills the FK to main (which always wins over anything the payload or the hook put there). Its `validate` and `afterInsert` deliberately do **not** run: they change when a rejection or a side effect fires, which belongs to the host's write. See [ADR 0014](./docs/adr/0014-what-follows-a-write-join.md).
 - **Filters validation**: TypeBox schemas use `additionalProperties: false`. By default Fastify strips unknown fields silently. For 400 errors on unknown filters: `Fastify({ ajv: { customOptions: { removeAdditional: false } } })`.
-- **Write-body whitelist**: insert/update/bulk-upsert bodies (`main` + secondaries items) are `additionalProperties: false`. Unknown properties are rejected with 400 — only columns in the generated Schema (as narrowed by `schemaOverrides`/`excludeFromCreation`) can be written, so no mass assignment of unexposed columns. Trim the Schema to keep sensitive columns unwritable.
+- **Write-body whitelist**: insert/update/bulk-upsert bodies (`main` + secondaries items) are `additionalProperties: false`. Unknown properties are rejected with 400 — only columns in the generated Schema (as narrowed by `schemaOverrides`/`excludeFromCreation`) can be written, so no mass assignment of unexposed columns. Exclude a sensitive column at generation time (`excludeColumns`) to keep it out of the Schema, hence unwritable and unreadable.
 - **Error responses**: errors the plugin raises itself are `4xx` with messages written for clients (validation, not found, tenant). Anything else — a driver constraint violation, a hook throwing without a `statusCode` — answers a fixed `{"statusCode":500,"error":"Internal Server Error","message":"Internal Server Error"}`: driver messages name tables, columns and constraints, and they stay on the server. **No status code is remapped** (a unique violation is a `500`, not a `409` — that mapping is product logic). The body carries `requestId` (the `reqId` Fastify logs on every line) so the real error is one grep away in the log, where it is also written via `request.log.error` — and attached as `err.cause`, so a consumer `setErrorHandler` can map `err.cause.code === '23505'` to `409` itself. **`exposeDebugInfo: true` is the only way to get the driver detail on the wire** — set it while developing, where a client building against the API cannot always read your log: the `500` then also carries `debugInfo` (`message`, `code`, `constraint`, `detail`, `stack`), additively, so the four fields above keep their production shape. Nothing else flips it: not `debug` (server-side only, and it belongs to whoever registers the plugin), not `NODE_ENV`. Errors thrown by `onRequests` hooks run before the handler and are unaffected.
 - **Request limits**: `maxItemsPerPage` (default 1000) caps the search page size and is applied as the `LIMIT` even when no paginator is sent (so an empty-body search can't dump a whole table); over-limit `itemsPerPage` → 400. `maxBulkItems` (default 1000) caps the bulk array length via schema `maxItems` → 400. Two further caps are **fixed, not configurable**, and bound how much work one search may ask for: at most **100 `conditions`** and **20 comma-separated `orderBy` parts** — each dotted condition and each 3-part `orderBy` token becomes its own correlated subquery, which `maxItemsPerPage` does not bound. Over either limit → 400; the request schema also caps `orderBy` at 1024 characters. Those two live in the **search engine**, not in the route, so they apply to programmatic `sqlApi.search()` as well, together with the `paginator` integer guard. What `sqlApi.*` does *not* inherit are the two configurable caps, which belong to the routes: pass `maxRows` to `sqlApi.search()` for the same `LIMIT` protection, and bound your own arrays before a bulk call.
 - **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause). The tenant belongs to the *request*, not to the table it addresses: a scoped table is filtered even when reached as a join target or written as a secondary of an unscoped host, so `getTenantId` must tolerate a request with no authenticated user (`req.user?.x ?? null`).
@@ -1211,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,96 @@ 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
+
+- **`excludeColumns` config option** — the lever for *"this column must not exist for the API at
+  all"*. [ADR 0017](./docs/adr/0017-the-schema-is-the-contract.md), the README and `AGENTS.md`
+  all pointed at "trim it out of the Schema" for that case, and no such lever existed: Schema
+  files are generated and overwritten on every run, so the only way to drop a column was to
+  re-edit the file after each `sqlapi-generate-schema` — or to pair `readExclude` with
+  `writeExclude`, which `defineTable` refuses. `excludeColumns` in `sqlapi.config.ts` takes
+  `"<table>.<column>"` entries matched against the DB names, with `*` as a wildcard on either
+  side (`'user.password_hash'`, `'*.internal_*'`), and drops the column from the generated Schema
+  — its fields, `colMap` and `generatedFields` — so no route, filter, order or manifest ever
+  sees it. A primary key column is refused (every route identifies rows with it), and so is a
+  pattern that would leave a table with no columns: that is `excludeTables`' job. Applied after
+  `excludeTables`, so a column pattern is never checked against a table the generator does not
+  see. **Regenerate your schemas** after adding entries. See
+  [ADR 0019](./docs/adr/0019-column-exclusion-is-generation-time-config.md).
+
+### Changed
+
+- **The docs no longer say "trim the Schema".** The README lever table, `AGENTS.md`,
+  `AGENTS_BACKEND.md` and the `defineTable` error for a field in both `readExclude` and
+  `writeExclude` now point at `excludeColumns`.
+
 ## [0.2.3]
 
 ### Fixed
@@ -595,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/README.md

@@ -215,7 +215,7 @@ each way they need to differ:
 |---|---|
 | a column must never be read | `readExclude` |
 | a column must never be written | `writeExclude` |
-| a column must not exist for the API at all | trim it out of the Schema |
+| a column must not exist for the API at all | `excludeColumns` in `sqlapi.config.ts` |
 | the API type must be stricter than the column | `schemaOverrides` |
 | the value is derived, not stored | `computedFields` |
 | the stored representation is not the API one | `afterRead` (decrypt, unpack, rescale) |

package/dist/bin/generate-schema.js

@@ -4,7 +4,7 @@ import * as path from 'node:path';
 import { loadConfig } from '../lib/cli/config.js';
 import { buildConnectionString, introspectTables } from '../lib/cli/pg-introspect.js';
 import { buildMysqlConnectionConfig, introspectMysqlTables } from '../lib/cli/mysql-introspect.js';
-import { applyExcludeTables, buildTableMap, generateSchemaFile } from '../lib/cli/schema-codegen.js';
+import { applyExcludeColumns, applyExcludeTables, buildTableMap, generateSchemaFile, } from '../lib/cli/schema-codegen.js';
 import { loadEnvFile, CONSOLE_COLORS, display, displayAsTableRow, parseArgs, runCli } from './utils.js';
 const STATUS_COLOR = {
     created: CONSOLE_COLORS.green,
@@ -157,6 +157,12 @@ await runCli('fastify-auto-sqlapi: generating schemas', async () => {
     if (excluded.length) {
         display(`Excluded by config (excludeTables): ${excluded.join(', ')}`, CONSOLE_COLORS.gray);
     }
+    // Runs after the table blacklist so a column pattern is never checked against a table the
+    // generator will not see anyway (its primary key included).
+    const excludedColumns = applyExcludeColumns(tableMap, config.excludeColumns);
+    if (excludedColumns.length) {
+        display(`Excluded by config (excludeColumns): ${excludedColumns.join(', ')}`, CONSOLE_COLORS.gray);
+    }
     const tableNames = cliArgs.tables;
     if (!keepOnlyRequestedTables(tableMap, tableNames)) {
         display(`No matching tables found for: ${tableNames.join(', ')}`, CONSOLE_COLORS.magenta);

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

@@ -16,5 +16,19 @@ export declare function buildTableMap(rows: ColumnInfo[]): TableMap;
  * Returns the names of the excluded tables, in map order.
  */
 export declare function applyExcludeTables(tableMap: TableMap, excludeTables?: string[]): string[];
+/**
+ * Remove from every table in `tableMap` the columns matching any of the `excludeColumns`
+ * config patterns. A pattern is `<table>.<column>`, both parts matched against the DB names
+ * (not the generated field names) with `*` as the only wildcard on either side.
+ *
+ * An excluded column does not exist for the API at all: it leaves the Schema's fields, its
+ * `colMap` and its `generatedFields`, so every read, write, filter and manifest built from the
+ * Schema is unaware of it. That is also why the primary key is refused — every engine
+ * identifies rows with it — and why a table that would end up empty is refused too: that
+ * is `excludeTables`' job.
+ *
+ * Returns the excluded columns as `table.column`, in map order.
+ */
+export declare function applyExcludeColumns(tableMap: TableMap, excludeColumns?: string[]): string[];
 export declare function generateSchemaFile(schemaName: string, tableName: string, fields: Record<string, string>, colMap: Record<string, string>, primary?: string[], generated?: string[], isView?: boolean): string;
 //# sourceMappingURL=schema-codegen.d.ts.map

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

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

package/dist/lib/cli/schema-codegen.js

@@ -95,6 +95,15 @@ export function buildTableMap(rows) {
         return acc;
     }, {});
 }
+/** Compile a config glob — `*` is the only wildcard, everything else is literal. */
+function globToRegExp(pattern) {
+    return new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replaceAll('\\*', '.*')}$`);
+}
+function assertPatternList(option, value) {
+    if (!Array.isArray(value) || value.some((p) => typeof p !== 'string')) {
+        throw new Error(`Invalid config: "${option}" must be an array of strings.`);
+    }
+}
 /**
  * Remove from `tableMap` the tables matching any of the `excludeTables` config patterns.
  * Patterns are matched against the DB table name (not the generated schema name);
@@ -104,12 +113,10 @@ export function buildTableMap(rows) {
 export function applyExcludeTables(tableMap, excludeTables) {
     if (excludeTables === undefined)
         return [];
-    if (!Array.isArray(excludeTables) || excludeTables.some((p) => typeof p !== 'string')) {
-        throw new Error('Invalid config: "excludeTables" must be an array of strings.');
-    }
+    assertPatternList('excludeTables', excludeTables);
     if (excludeTables.length === 0)
         return [];
-    const regexes = excludeTables.map((pattern) => new RegExp(`^${pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replaceAll('\\*', '.*')}$`));
+    const regexes = excludeTables.map(globToRegExp);
     const excluded = [];
     for (const schemaName of Object.keys(tableMap)) {
         const tableName = tableMap[schemaName].name;
@@ -120,6 +127,62 @@ export function applyExcludeTables(tableMap, excludeTables) {
     }
     return excluded;
 }
+/**
+ * Remove from every table in `tableMap` the columns matching any of the `excludeColumns`
+ * config patterns. A pattern is `<table>.<column>`, both parts matched against the DB names
+ * (not the generated field names) with `*` as the only wildcard on either side.
+ *
+ * An excluded column does not exist for the API at all: it leaves the Schema's fields, its
+ * `colMap` and its `generatedFields`, so every read, write, filter and manifest built from the
+ * Schema is unaware of it. That is also why the primary key is refused — every engine
+ * identifies rows with it — and why a table that would end up empty is refused too: that
+ * is `excludeTables`' job.
+ *
+ * Returns the excluded columns as `table.column`, in map order.
+ */
+export function applyExcludeColumns(tableMap, excludeColumns) {
+    if (excludeColumns === undefined)
+        return [];
+    assertPatternList('excludeColumns', excludeColumns);
+    if (excludeColumns.length === 0)
+        return [];
+    const matchers = excludeColumns.map((pattern) => {
+        const dot = pattern.indexOf('.');
+        if (dot <= 0 || dot === pattern.length - 1) {
+            throw new Error(`Invalid config: excludeColumns entry "${pattern}" must be in the form "table.column" ` +
+                `(a "*" wildcard is allowed on either side, e.g. "*.password_hash").`);
+        }
+        return {
+            table: globToRegExp(pattern.slice(0, dot)),
+            column: globToRegExp(pattern.slice(dot + 1)),
+        };
+    });
+    const excluded = [];
+    for (const schemaName of Object.keys(tableMap)) {
+        const table = tableMap[schemaName];
+        const tableMatchers = matchers.filter((m) => m.table.test(table.name));
+        if (tableMatchers.length === 0)
+            continue;
+        for (const field of Object.keys(table.fields)) {
+            const columnName = table.colMap[field];
+            if (!tableMatchers.some((m) => m.column.test(columnName)))
+                continue;
+            if (table.primary.includes(field)) {
+                throw new Error(`Invalid config: excludeColumns cannot exclude the primary key column ` +
+                    `"${table.name}.${columnName}" — every route identifies rows with it.`);
+            }
+            delete table.fields[field];
+            delete table.colMap[field];
+            table.generated = table.generated.filter((f) => f !== field);
+            excluded.push(`${table.name}.${columnName}`);
+        }
+        if (Object.keys(table.fields).length === 0) {
+            throw new Error(`Invalid config: excludeColumns leaves table "${table.name}" with no columns. ` +
+                `To hide a whole table use excludeTables instead.`);
+        }
+    }
+    return excluded;
+}
 export function generateSchemaFile(schemaName, tableName, fields, colMap, primary, generated, isView) {
     const fieldsStr = JSON.stringify(fields, null, 2).replace(/"(.*?)"\s*:\s*"Type(.*?)"/g, '$1: Type$2');
     const colMapStr = JSON.stringify(colMap, null, 2);

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/table-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EAEP,MAAM,aAAa,CAAC;AAcrB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAWX;AAgSD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAgDD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAWhB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}
+{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EAEP,MAAM,aAAa,CAAC;AAcrB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAWX;AAiSD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAgDD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAWhB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}

package/dist/lib/table-helpers.js

@@ -250,7 +250,8 @@ function validateWriteExclude(config) {
         }
         if (config.readExclude?.includes(field)) {
             throw new Error(`defineTable: field '${field}' on table '${table}' is in both readExclude and ` +
-                `writeExclude, leaving it neither readable nor writable. Remove it from the Schema instead.`);
+                `writeExclude, leaving it neither readable nor writable. Exclude it at generation time ` +
+                `with excludeColumns in sqlapi.config.ts instead.`);
         }
     }
 }

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/dist/types/cli.d.ts

@@ -10,6 +10,16 @@ export interface SqlApiConfig {
      * Excluded schemas already on disk are removed as orphans on the next full run.
      */
     excludeTables?: string[];
+    /**
+     * Columns to leave out of the generated Schemas (`sqlapi-generate-schema`), as
+     * `"<table>.<column>"` entries matched against the DB names; `*` is a wildcard on either
+     * side (e.g. "user.password_hash", "*.internal_*"). An excluded column does not exist for
+     * the API at all — no read, no write, no filter — unlike `readExclude` / `writeExclude`
+     * on the table config, which hide one side of a column that stays in the Schema. A primary
+     * key column cannot be excluded, and a table left with no columns is refused: use
+     * `excludeTables` for that.
+     */
+    excludeColumns?: string[];
 }
 export interface ColumnInfo {
     table_name: string;

package/dist/types/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/types/cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,UAAU,EAAE,MAAM,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,iFAAiF;QACjF,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,mFAAmF;QACnF,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,oFAAoF;QACpF,MAAM,EAAE,OAAO,CAAC;KACjB,CAAC;CACH"}

package/docs/adr/0017-the-schema-is-the-contract.md

@@ -1,6 +1,7 @@
 # 0017. The database schema is the API contract — by default, and only by default
 
-- **Status**: accepted
+- **Status**: accepted (the "trim it out of the Schema" lever below is `excludeColumns` since
+  [0019](./0019-column-exclusion-is-generation-time-config.md) — the Schema file is never edited)
 - **Date**: 2026-08-28
 
 ## Context

package/docs/adr/0019-column-exclusion-is-generation-time-config.md

@@ -0,0 +1,62 @@
+# 0019. Removing a column from the API is generation-time config — `excludeColumns`, never a Schema edit
+
+- **Status**: accepted
+- **Date**: 2026-09-13
+
+## Context
+
+[ADR 0017](./0017-the-schema-is-the-contract.md) lists one lever per way the exposed shape may
+differ from the stored one. For *"a column must not exist for the API at all"* it said: trim it
+out of the Schema. That lever did not exist. Schema files are disposable mirrors regenerated on
+every run ([ADR 0007](./0007-explicit-table-generation.md), [ADR 0009](./0009-schema-exclusion-config-blacklist.md)),
+so a trimmed Schema survived exactly until the next `sqlapi-generate-schema`. The two runtime
+levers do not cover the case either: `readExclude` hides one side, `writeExclude` the other, and
+`defineTable` refuses a field in both — because a column that is neither readable nor writable
+still sits in the validation schema, the Swagger output and the manifest, where it is a lie.
+
+## Decision
+
+Column exclusion is a generation-time config, next to `excludeTables`: `excludeColumns:
+string[]` in `sqlapi.config.ts`, entries of the form `"<table>.<column>"`, both parts matched
+against the DB names with `*` as the only wildcard. A matched column is removed from the
+generated Schema — its fields, its `colMap`, its `generatedFields` — so everything built from
+the Schema (routes, filters, ordering, joins, Swagger, manifest, TypeScript types) is unaware of
+it. There is nothing to hide at runtime because there is nothing there.
+
+Two refusals, both loud at generation time:
+
+- **A primary key column cannot be excluded.** Every route identifies rows with it; the table
+  generator would either invent a key or write a placeholder, and either is silent damage.
+- **A table cannot be left with no columns.** That is what `excludeTables` is for, and one
+  mechanism per intent keeps the config readable.
+
+`excludeColumns` runs after `excludeTables`, so a column pattern is never checked against a
+table the generator will not see — a `*.id` glob does not trip on the primary key of a table
+that is excluded anyway.
+
+## Alternatives considered
+
+- **Editing the generated Schema file** — the documented answer until now, rejected: the file
+  is overwritten on every run, so the edit is a hand-maintained exception under `schemas/`,
+  exactly what ADR 0009 refused to support for whole tables.
+- **A runtime `exclude` key on `defineTable`** — rejected: the Schema is imported by the
+  consumer's code before `defineTable` runs, so its TypeScript type, its `validation` object and
+  the `$id`-registered JSON Schema would still carry the column. A runtime lever can only hide;
+  the column would remain visible in Swagger, in the manifest and in the `TypeSchema` type, and
+  every reader of those would have to know about the second layer.
+- **Allowing `readExclude` + `writeExclude` on the same field** — rejected for the same reason:
+  it is the runtime lever again, with the added cost of a rule that means "does not exist" but
+  reads as two independent hidings.
+- **A per-column option inside the Schema file** — rejected: the Schema file carries no config,
+  by design; `sqlapi.config.ts` is where the generator's inputs already live.
+
+## Consequences
+
+- Adding an entry to `excludeColumns` changes the generated Schema on the next run and, for
+  TypeScript consumers, fails compilation wherever the column was referenced. Intended: that is
+  ADR 0017's "checked, not implied" at work.
+- The relation-level narrowing described in [ADR 0010](./0010-joins-do-not-run-route-guards.md)
+  — a relation declared with a narrower Schema object — is a different tool for a different
+  scope (per relation, not per API) and is unaffected.
+- An `excludeColumns` entry that is not `table.column`, that reaches a primary key, or that
+  empties a table fails the run with an explicit error rather than being ignored.

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

@@ -33,6 +33,8 @@ not by editing history.
 | [0016](./0016-a-view-is-a-table-config.md) | A view is a table config — the generator refuses to invent its primary key |
 | [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.3",
+  "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",