fastify-auto-sqlapi 0.2.1 → 0.2.2

package/AGENTS.md

@@ -6,6 +6,56 @@ 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:
+
+- 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.
+
+## Start here
+
+These files are the **contract**. Everything a consumer can rely on is documented here; find
+the answer in the table below and stop there.
+
+| I need to… | Read |
+|---|---|
+| Call the API from a client (fetch, list page, form, agent tool) | **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — whole file, it is the complete request grammar |
+| Know *this* deployment's tables, fields and join aliases | `GET {prefix}/agent/manifest.md` (when `agentManifest` is on), or Swagger — the docs give the grammar, the manifest gives the vocabulary |
+| Add or configure a table, joins, tenant scope, hooks, validation | **[AGENTS_BACKEND.md](./AGENTS_BACKEND.md)** — see its section map |
+| Query the data from a custom route, a script or a background job | AGENTS_BACKEND.md → *SqlApi* |
+| Run raw SQL inside a hook | AGENTS_BACKEND.md → *QueryClient API* |
+| Migrate from the old join API (`joinFilters`, `joins`, `joinGroups`) | **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** |
+| Understand why a behavior that looks wrong is intended | **[docs/adr/](./docs/adr/README.md)** |
+
+**Do not read the plugin's own sources.** `node_modules/fastify-auto-sqlapi/dist/` is compiled
+output: internal helpers, no stability guarantee, and no indication of which behaviors are
+deliberate. An answer reverse-engineered from it is right today and wrong at the next release.
+If a question is not answered by the files above, say so and ask — do not infer the API from
+the implementation, and never copy an internal helper into consumer code.
+
+## Naming: camelCase in code, real column names only when you address the DB directly
+
+Everything the plugin exposes is a **camelCase schema field name**. The database is free to name
+its columns however it likes: snake_case columns (`organization_id`) are converted to camelCase
+(`organizationId`) for the code, and columns already in camelCase (e.g. betterauth) are preserved
+verbatim through the `colMap` the CLI generates. Either way `Schema.col('organizationId')` returns
+the real column — the mapping lives in the generated Schema, so no naming convention is imposed on
+the database and none has to be remembered. One rule: **write camelCase everywhere except where
+you name a column to the database yourself.**
+
+| camelCase — schema field names | real column names — whatever the table uses |
+|---|---|
+| every request and response body: `filters`, `conditions`, `orderBy`, `selectComputed`, `main`, secondaries | `db.*` (QueryClient) calls: record keys, `where`, `conflictKeys` — and the real table name (`Schema.tableName`), not the schema variable |
+| `defineTable` keys: `primary`, `excludeFromCreation`, `readExclude`, `schemaOverrides`, `buildUpsertRule(Schema, […])` | `tenantScope`: `column`, `anyOf[…]`, `through.localField` / `through.foreignField` |
+| `buildRelation(Main, mainField, Join, joinField)` | any SQL string you write yourself — `extendedCondition`, `computedFields.expr`: get the column with `Schema.col('field')` or `qiCol('field')`, never type it literally |
+| hooks and validators — `validate`, `beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `afterRead` — receive and mutate camelCase records | |
+| `sqlApi.search / get / insert / update / delete / bulkUpsert / bulkDelete` — same shapes as the HTTP bodies | |
+
+Two consequences worth remembering: a `tenantScope` names the table's own columns (as in
+`{ anyOf: ['requester_agent_id', 'target_agent_id'] }` for a snake_case table) while the client
+still anchors the write by sending `requesterAgentId`; and `sqlApi` and `db` are **not**
+interchangeable — `sqlApi` is the high-level API (camelCase, hooks, tenant, joins), `db` is the SQL
+layer underneath it (real column names, no hooks, no tenant).
+
 ## Documentation
 
 - **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** — **READ FIRST when migrating.** Maps the old join API (`joinFilters`, `joins`, `joinGroups`) to the new alias-based one (`joinMustExist`, `joinMultiple`, `joinGroup`, `joinLeft`). Covers `buildRelation` new options-object signature (alias defaults to `joinSchema.tableName`, plus `selection` and `unique`), request/response key renames, secondaries key renames, dotted notation rules, and validation/400 errors. Common to backend and frontend.

package/AGENTS_BACKEND.md

@@ -4,6 +4,34 @@ How to set up schemas, tables, and configure the plugin.
 
 > ⚠️ **Migrating from a previous version?** The join API was redesigned (no backward compat). See **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)** for the full migration guide — request/response key renames, `buildRelation` signature, and validation rules. Common to backend and frontend.
 
+## Section map
+
+This file is long — jump, don't scan. Every supported behavior is described here or in the
+files [AGENTS.md](./AGENTS.md) links to; the compiled `dist/` is not documentation and must not
+be read to answer a question about the API.
+
+| Section | Answers |
+|---|---|
+| [Setup Workflow](#setup-workflow) | install, `sqlapi.config.ts`, env vars, generating Schemas and tables, registering the plugin |
+| [Plugin Options](#plugin-options) | every `register()` option with its default, and how the connection is picked up (`fastify.pg` / `fastify.mysql`) |
+| [defineTable() — Complete Reference](#definetable--complete-reference) | every table key, composite PKs, `buildRelation`, `extraFilters` + `extendedCondition` |
+| [Computed Fields](#computed-fields-extension-system) | virtual SQL-expression fields usable in filters, conditions, orderBy, `selectComputed` |
+| [ConditionBuilder API](#conditionbuilder-api) | building WHERE fragments by hand |
+| [SqlApi](#sqlapi--programmatic-high-level-api) | **querying from your own routes, scripts and jobs** — `app.sqlApi`, `createSqlApi` |
+| [QueryClient API](#queryclient-api) | the raw SQL layer under SqlApi — `db.*` inside hooks |
+| [Swagger](#swagger) | exposing the generated docs |
+| [Multi-Tenant Filtering](#multi-tenant-filtering) | `tenantScope` direct / indirect / `anyOf`, `getTenantId`, admin bypass |
+| [Views](#views) | views and materialized views as table configs, the primary key a view cannot declare, why writes start off |
+| [Key Conventions](#key-conventions) | casing, nullability, `excludeFromCreation`, `readExclude`, `upsertMap`, `schemaOverrides`, `afterRead`, error shape, request limits |
+| [Common Backend Patterns](#common-backend-patterns) | auth, custom validation, audit fields, encryption at rest, full-text search, per-prefix access levels |
+| [Re-exports](#re-exports) | what the package re-exports, so nothing extra has to be installed |
+| [FAQ / Gotchas](#faq--gotchas) | schema exports, prefix behavior, TypeBox conflicts, dialect differences |
+
+**Casing in one line**: everything you write is camelCase (schema field names) except raw SQL,
+`tenantScope` columns and `db.*` record keys, which name the real columns — in whatever case the
+table uses. Full table in
+[AGENTS.md](./AGENTS.md#naming-camelcase-in-code-real-column-names-only-when-you-address-the-db-directly).
+
 ## Setup Workflow
 
 ### 1. Install
@@ -23,16 +51,19 @@ npm install @fastify/swagger @fastify/swagger-ui
 Create `sqlapi.config.ts` (or `.js`) in the project root. This config is used **only by the CLI** (`sqlapi-generate-schema` / `sqlapi-generate-tables`), NOT at runtime by the Fastify plugin.
 
 ```typescript
-// sqlapi.config.ts — interface: { outputDir: string; schema?: string; dialect?: DialectName; envFile?: string }
+// sqlapi.config.ts
 export default {
   outputDir: './src/db',       // base directory for generated files (default: './src/db')
   schema: 'public',            // DB schema to introspect (default: 'public', PostgreSQL only)
   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)
 };
 ```
 
-That's it — only these four 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 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.
+
+**`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).
 
 ### 3. Configure database connection (env vars)
 
@@ -69,7 +100,7 @@ npx sqlapi-generate-schema                # PostgreSQL (default)
 npx sqlapi-generate-schema --dialect mysql # MySQL/MariaDB
 ```
 
-This introspects the database and generates one `Schema*.ts` file per table in `outputDir/schemas/`. These files are auto-generated and should not be manually edited. They contain TypeBox field definitions, `col()` for camelCase→snake_case mapping, and validation schemas. MySQL/MariaDB requires `mysql2` as a peer dependency.
+This introspects the database and generates one `Schema*.ts` file per table in `outputDir/schemas/`. These files are auto-generated and should not be manually edited. They contain TypeBox field definitions, `col()` mapping each camelCase field to its real column, and validation schemas. MySQL/MariaDB requires `mysql2` as a peer dependency.
 
 ### 5. Generate tables template
 
@@ -188,6 +219,52 @@ await app.register(async (instance) => {
 
 ---
 
+## Plugin Options
+
+```typescript
+await app.register(fastifyAutoSqlApi, {
+  DbTables: dbTables,           // Required — your table definitions
+  dialect: 'postgres',          // Optional — 'postgres' | 'mysql' | 'mariadb' (default: 'postgres')
+  prefix: '/api',               // Optional — URL prefix for all routes
+  swagger: true,                // Optional — enable Swagger UI (or pass SwaggerOptions)
+  onRequests: [authMiddleware],  // Optional — global hooks applied to every route
+  getTenantId: (req) => id,     // Optional — multi-tenant function
+  maxItemsPerPage: 1000,        // Optional — cap on search page size (default: 1000)
+  maxBulkItems: 1000,           // Optional — cap on bulk array length (default: 1000)
+  debug: true,                  // Optional — log all SQL queries and params
+});
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `DbTables` | `Record<string, ITable>` | Yes | Table configurations |
+| `dialect` | `'postgres' \| 'mysql' \| 'mariadb'` | No | DB dialect (default: `'postgres'`) |
+| `prefix` | `string` | No | URL prefix (e.g. `/api`) |
+| `swagger` | `boolean \| SwaggerOptions` | No | Enable Swagger UI |
+| `onRequests` | `Function[]` | No | Global auth/middleware hooks |
+| `getTenantId` | `(req) => id \| null` | No | Tenant resolver for multi-tenant |
+| `maxItemsPerPage` | `number` | No | Max search page size, and the row `LIMIT` applied when no paginator is sent (default: `1000`) |
+| `maxBulkItems` | `number` | No | Max number of items accepted by the bulk endpoints (default: `1000`) |
+| `debug` | `boolean` | No | Log all SQL queries to console (server-side only — it never changes a response) |
+| `exposeDebugInfo` | `boolean` | No | **Development only.** Attach the driver error (message, `code`, `constraint`, stack) to `500` responses as `debugInfo` (default: `false`) |
+
+The plugin picks up the connection from the Fastify instance: `fastify.pg` for PostgreSQL
+(what `@fastify/postgres` decorates) or `fastify.mysql` for MySQL/MariaDB. For MySQL,
+decorate a `mysql2/promise` pool (e.g. via `@fastify/mysql` with `promise: true`, or manually)
+and pass `dialect: 'mysql'` or `'mariadb'`:
+
+```typescript
+import mysql from 'mysql2/promise';
+
+const pool = mysql.createPool({ host: '127.0.0.1', user: 'myuser', password: '...', database: 'mydb' });
+app.decorate('mysql', pool);
+app.addHook('onClose', async () => { await pool.end(); });
+
+await app.register(fastifyAutoSqlApi, { DbTables: dbTables, dialect: 'mysql' });
+```
+
+---
+
 ## defineTable() — Complete Reference
 
 ```typescript
@@ -332,6 +409,14 @@ export const TableCustomer = defineTable({
   afterBulkDelete: async (db, req, deletedIds) => {
     // Called ONCE with the ids ACTUALLY deleted (may be a subset of the requested ids).
   },
+  afterRead: async (db, req, rows, ctx) => {
+    // The read-side hook: turn the stored representation back into the API one.
+    // Called ONCE per result set (batch), with camelCase rows mutated IN PLACE.
+    // Runs for get, search, joinMultiple and joinLeft — including when THIS table's rows
+    // arrive through a join declared on another table (ctx.source / ctx.alias say which).
+    // Not called on joinGroup (aggregates, not rows) nor when the read returned nothing.
+    for (const row of rows) row.ssn = decrypt(row.ssn);
+  },
 
   // OPERATIONS — whitelist of auto-generated HTTP routes for this table.
   // Omitted = ALL operations exposed (default-open!). Does not affect programmatic sqlApi.*.
@@ -589,6 +674,13 @@ All values are parameterized (`$1, $2, ...`), never interpolated.
 
 Use `SqlApi` to perform CRUD operations from custom routes with the same capabilities as the auto-generated endpoints. The internal auto-generated routes also use `SqlApi`, guaranteeing a single code path.
 
+It takes and returns **camelCase schema field names**, exactly like the HTTP bodies documented in
+[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md) — `sqlApi.search('order', { filters: { customerId: 3 } })`,
+never `customer_id`. Hooks, validation, computed fields and tenant scoping all run, so this is the
+right entry point for application code. Drop to [`QueryClient`](#queryclient-api) only for SQL that
+has no equivalent here — it is the layer underneath, with none of that behavior and with real DB
+column names.
+
 ### Using `app.sqlApi` (recommended)
 
 After registering the plugin, `app.sqlApi` is available everywhere — no extra configuration needed:
@@ -671,6 +763,15 @@ The `request` parameter is optional. Pass it when you need tenant resolution or
 
 ## QueryClient API
 
+The SQL layer **underneath** [`SqlApi`](#sqlapi--programmatic-high-level-api): it executes what you
+give it and nothing else — no hooks, no validation, no computed fields, no tenant scoping. Reach for
+it only when the operation has no `sqlApi` equivalent; anything expressed as CRUD belongs there.
+
+It speaks the **database's own names**: real table names (`Schema.tableName`, not the schema
+variable) and real column names — get them from `Schema.col('customerId')` rather than assuming a
+convention, since the columns may be snake_case or already camelCase. Passing a schema field name
+the mapping would have translated produces a SQL error at runtime, not a validation error.
+
 Available in hooks via the `db` parameter:
 
 ```typescript
@@ -687,7 +788,7 @@ db.expression(value);                                                   // Raw S
 
 `pkCol` can be a string (`'id'`) or an array (`['agent_id', 'team_id']`) for composite PKs. PostgreSQL/MariaDB use `RETURNING`, MySQL uses `insertId`.
 
-Record keys are snake_case column names. Values are parameterized.
+Record keys are real column names (`Schema.col('field')`). Values are parameterized.
 
 ---
 
@@ -733,6 +834,26 @@ await app.register(fastifyAutoSqlApi, {
 });
 ```
 
+Every column named in a `tenantScope` — `column`, the entries of `anyOf`, `through.localField`
+and `through.foreignField` — is a **real DB column name**, not a camelCase schema field. This is
+the one key of `defineTable` where the convention flips, and it is deliberate: a scope is applied
+to the SQL, *after* the payload has been converted, and `through.foreignField` belongs to a parent
+table that may have no config, no `colMap`, or no generated schema at all. Same category as `db.*`
+and `extendedCondition` — names that go straight to the database.
+
+Write them as the table declares them (`organization_id` below, but `organizationId` on a
+camelCase table); clients keep sending the camelCase field name either way, including when
+anchoring an `anyOf` write.
+
+`defineTable` catches the mistake this exception invites: naming the schema **field** whose real
+column is something else (`organizationId` where the column is `organization_id`) throws at
+startup, on all four positions, checking `through.foreignField` against the parent schema. It
+cannot check that a column *exists* — a hand-written schema may legitimately omit it — but it can
+tell you that you named a field. Without it the mistake surfaces as
+`column "organizationId" does not exist` on every request to the table: an opaque `500` that fails
+closed and says nothing. On a camelCase database the check raises nothing, since `col()` is the
+identity there.
+
 ### Direct tenant (column on the table itself)
 
 ```typescript
@@ -842,6 +963,51 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 ---
 
+## Views
+
+A view is a **table config** like any other — same `defineTable`, same `Table*.ts` file, same
+routes. There is no `View*` anything: searching, filtering, ordering, pagination, joins and
+computed fields all work through the same code path as a base table. Materialized views are
+included, PostgreSQL ones read from `pg_catalog` since `information_schema` does not describe
+them.
+
+What differs is what the generator can read from the database, and it is worth knowing before
+you accept the file it writes.
+
+**The primary key is not declared.** A view carries no `PRIMARY KEY` constraint, so
+`sqlapi-generate-schema` has nothing to report and the table generator **will not guess one
+from the column types** — on `SELECT status, count(*) AS order_count ... GROUP BY status` that
+would take the count as the key, and `get/:id`, `update` and `delete` would then address rows
+by it. Instead:
+
+- the view has an `id` column → it is used, and the file says the key was *inferred, not read
+  from the database*. Check that it is really unique in the view before exposing
+  `get`/`update`/`delete`.
+- no plausible column → `primary: 'TODO_pick_a_unique_column'` plus `operations: ['search']`
+  and a real `defaultOrder`. **This config works as generated**: search reads `defaultOrder`,
+  never the primary key. The TODO is what you replace to widen `operations`, not a defect.
+
+`defineTable` enforces that: a `primary` naming a field the schema does not have throws **at
+startup**, unless the table exposes only `search` and declares its own `defaultOrder`.
+
+**Writes start off, but are not forbidden.** A view's generated config is
+`operations: ['search', 'get']`. An aggregating view rejects every INSERT and UPDATE at the
+database (`cannot insert into view ...`, a raw `500`), while a view simple enough for the engine
+to make updatable accepts them on both PostgreSQL and MySQL — using one as a projection or
+permission layer is a supported pattern. The read-only start is the *generated template*, not a
+runtime rule: remove or widen `operations` and the write routes come back.
+
+**Nullability differs between engines** for the same view: PostgreSQL reports every view column
+as nullable, MySQL reports the real nullability of the underlying expression. The generated
+Schema therefore differs by dialect for one and the same view. It affects write bodies only, and
+a view is not usually written to.
+
+`sqlapi-generate-schema` prints the views it found and both assumptions above — read that
+output, it is the part that does not depend on anyone opening the generated file. See
+[ADR 0016](./docs/adr/0016-a-view-is-a-table-config.md).
+
+---
+
 ## Key Conventions
 
 - **camelCase in API, any case in DB**: all request/response fields are camelCase. The plugin converts via `col()` and `colMap`. For snake_case DB columns (default), conversion is automatic. For camelCase DB columns (e.g. betterauth), the CLI generates a `colMap` that preserves the original column names — no conversion needed. Manual schemas without `colMap` fall back to `toUnderscore()`.
@@ -849,11 +1015,15 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 - **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).
+- **Database-computed and identity columns are detected by the CLI**: `sqlapi-generate-schema` reads `is_generated` (PostgreSQL) / `EXTRA` (MySQL, `VIRTUAL GENERATED` and `STORED GENERATED`) 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`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
+- **`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.
+- **`afterRead`**: the read-side counterpart of `beforeInsert`/`beforeUpdate` — the place to decrypt a column, unpack a blob, rescale a stored unit. Called **once per result set** with camelCase rows mutated **in place** (a hook that calls a remote KMS gets one invocation for the page, not one per row), and awaited. Declared on the table that **owns** the column, and it follows a join: the hook runs wherever that table's rows surface, including through a `joinMultiple`/`joinLeft` declared on another table — `ctx.source` (`'get' | 'search' | 'joinMultiple' | 'joinLeft'`) and `ctx.alias` say which. Not called on `joinGroup` (aggregates, not table rows) nor on an empty result. Rows cannot be added or removed — the pagination `COUNT` has already run, so dropping rows would report a `total` that does not match; narrowing what a caller sees is `filters`/`tenantScope`/`readExclude`. On the main table it runs **after** the join side queries, which correlate on the values the database returned: a hook rewriting the column a relation joins on does not break the correlation. Two things it does not reach, by design: `filters`, `orderBy` and `compute*` run in SQL against the **stored** value (searching an encrypted column searches the ciphertext), and it transforms **values, not types** — the response is serialized against the generated schema, so a hook returning an object where the column is `text` yields `"[object Object]"`, and one returning `12.34` on an `integer` column yields `12`. Decrypting `text`→`text` or rescaling `numeric`→`numeric` is what it is for; if the stored and API types genuinely differ, that is a custom route.
 - **Validation receives camelCase**: `validate` receives the original camelCase record (as sent by the client) and secondaries. Field names match the schema definition, with full TypeScript inference (`main.startDate`, not `main.start_date`). It returns `ValidationError[]` — tuples of `[field, code]` or `[field, code, message]`. If any errors are returned, the request is rejected with 400 before hooks or SQL execute.
 - **`validateBulk` replaces `validate` in bulk**: when `validateBulk` is defined, it is called once with all items and per-item `validate` is skipped. This allows optimized batch queries instead of N individual checks. When only `validate` is defined, it runs per-item as fallback.
-- **All hooks and validators receive camelCase records**: `validate` and the whole hook matrix (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`) 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.
+- **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.
 - **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.
@@ -1041,6 +1211,47 @@ 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`.
 
+### 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
+hook — and nothing at the call sites:
+
+```typescript
+const TablePatient = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaPatient),
+
+  beforeInsert: async (db, req, record) => {
+    if (record.ssn != null) record.ssn = encrypt(record.ssn);
+  },
+  beforeUpdate: async (db, req, fields) => {
+    if (fields.ssn != null) fields.ssn = encrypt(fields.ssn);
+  },
+  afterRead: async (db, req, rows) => {
+    for (const row of rows) {
+      if (row.ssn != null) row.ssn = decrypt(row.ssn);
+    }
+  },
+});
+```
+
+`afterRead` covers `GET /rest/patient/:id`, `POST /search/patient`, and every `joinMultiple` /
+`joinLeft` that reaches `patient` from another table's search — the hook belongs to the table
+that owns the column, so a relation declared elsewhere needs no extra wiring. The same holds on
+the way in: a patient written as a **secondary** of another table's insert runs this
+`beforeInsert` too.
+
+What the plugin does *not* do for you, because it cannot know your cipher:
+
+- **searching**: `filters: { ssn: '123-45' }` compares the plaintext against the ciphertext in
+  SQL and matches nothing. With a deterministic cipher, encrypt the value yourself in
+  `extendedCondition`; with a randomized one, that column is not searchable at all. `orderBy`
+  and `computeMin/Max` sort and aggregate the ciphertext.
+- **typing**: the hook transforms values, not types. The response is serialized against the
+  generated schema, so returning an object where the column is `text` yields
+  `"[object Object]"`. `text`→`text` and `numeric`→`numeric` transforms are the supported shape.
+- **aggregates**: `joinGroup` and `compute*` return values the hook never sees.
+
 ### Full-text search filter
 
 ```typescript
@@ -1151,6 +1362,53 @@ loose generic tool (`table` enum from the manifest, free body) with the structur
 
 ---
 
+## Re-exports
+
+The package re-exports commonly needed utilities so you don't need to install them separately:
+
+```typescript
+import {
+  Type,                   // from @sinclair/typebox
+  type Static,            // from @sinclair/typebox
+  ConditionBuilder,       // from node-condition-builder
+  Expression,             // from node-condition-builder
+
+  // Table configuration
+  defineTable,
+  exportTableInfo,
+  buildRelation,
+  buildUpsertRule,
+  buildUpsertRules,
+  Nullable,               // type-array nullable schema (see Conventions)
+
+  // DB layer
+  QueryClient,            // raw SQL query helper
+  createQueryClient,      // factory with dialect string
+  pgQueryable,            // pg pool adapter
+  mysqlQueryable,         // mysql2 pool adapter
+
+  // Programmatic high-level API
+  createSqlApi,           // standalone SqlApi (for scripts/tests)
+  setupSwagger,           // manual Swagger registration
+} from 'fastify-auto-sqlapi';
+
+import type {
+  ValidationError,        // [field, code] | [field, code, message]
+  ValidatorFn,
+  BulkValidatorFn,
+  JoinDefinition,
+  JoinRefFilter,
+  JoinFetchRequest,
+  JoinGroupRequest,
+  SearchCondition,
+  ConditionMethod,
+} from 'fastify-auto-sqlapi';
+```
+
+After registering the plugin, `app.sqlApi` is decorated on the Fastify instance and exposes `search`, `get`, `insert`, `update`, `delete`, `bulkUpsert`, `bulkDelete` for custom routes — same code path as the auto-generated endpoints.
+
+---
+
 ## FAQ / Gotchas
 
 ### Schema files `default export` — do I need to register them?

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 camelCase. `{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`). 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

@@ -536,3 +536,54 @@ getTenantId: (request) => request.user?.organizationId ?? null,
 Then decide, for each open table that relates to a scoped one, whether the relation was meant to
 be a read grant at all. If it was not, remove it from `allowedReadJoins` — a relation is the
 grant, and the scope is only the cap on it.
+
+---
+
+# Breaking Change — secondaries run the child table's `beforeInsert`
+
+## Why this changed
+
+`processSecondaries` consulted the child table's configuration for its `excludeFromCreation` and
+its `tenantScope`, but skipped its `beforeInsert`. A child table whose hook *transformed* a value
+rather than adding one — encrypting a column, normalising a unit — therefore stored the raw
+client value whenever its rows arrived as another table's secondaries, and correctly only through
+its own route. Nothing failed at write time; the row read back as garbage later. See
+[ADR 0014](./docs/adr/0014-what-follows-a-write-join.md).
+
+## What changed
+
+- A child table's **`beforeInsert` now runs** for rows written as `secondaries`, after that
+  table's `excludeFromCreation` strip and before the engine's FK auto-fill (which stays
+  authoritative). The child's `validate` and `afterInsert` still do not run.
+- The **get response schema honours `readExclude`**: it previously advertised fields the engine
+  never selects. `schemaOverrides` is unchanged — still write bodies only.
+- The **update body now requires the primary key**. It identifies the row (`PUT /rest/:table`
+  carries it in `main`), but the generated PK field is `Optional` and that modifier reached the
+  update body unchanged, so a request omitting `main.id` built its `WHERE` on `undefined`
+  instead of being rejected with a 400.
+
+## Who is affected
+
+- **A table of yours declares `beforeInsert` and is also a write-join target.** The hook now runs
+  on that path. If it was written assuming the table's own route — reading `req.params`, counting
+  invocations, calling an external service per record — it now runs where it did not before. It
+  receives the transaction connection, so what it writes rolls back with the host's write.
+- **You send an update without `main.<pk>`.** It never identified a row — the `WHERE` was built
+  on `undefined` — and is now a 400.
+- **A client of yours read a `readExclude`d field out of the get route's Swagger.** It was never
+  returned; only the documentation claimed it.
+
+Not affected: tables with no `beforeInsert`, or none that are write-join targets. Nothing about
+`schemaOverrides` changes.
+
+## Migration
+
+For a `beforeInsert` that must keep running on the table's own route only, guard on the context
+it needs rather than on the path:
+
+```typescript
+beforeInsert: async (db, req, record) => {
+  record.slug = slugify(record.name);           // shaping: correct on both paths, leave it
+  if (req.routeOptions?.url?.startsWith('/rest/')) await notify(record);  // side effect: narrow it
+},
+```