fastify-auto-sqlapi 0.1.9 → 0.1.10

package/AGENTS.md

@@ -14,6 +14,8 @@ The plugin generates REST endpoints (search, get, insert, update, delete, bulk u
 
 - **[AGENTS_FRONTEND.md](./AGENTS_FRONTEND.md)** — Generated endpoints overview, search (POST with body filters, conditions/advanced filters using ConditionBuilder methods, query params for ordering/pagination/aggregation), `joinMustExist` (EXISTS-based filtering by related tables), `joinMultiple` (fetch child rows), `joinGroup` (aggregations), `joinLeft` (embed N:1 parent inline), GET, INSERT (with secondaries), UPDATE (with secondaries + deletions), DELETE, bulk upsert, bulk delete, response shapes (PK-only), **validation errors** (structured field-level 400 responses), pagination, computed values.
 
+- **[docs/adr/](./docs/adr/README.md)** — Architecture Decision Records. **Read before proposing a "fix" to a deliberate behavior**: open-by-default, non-transactional bulk, always-updatable fields, raw DB errors, insert-pipeline ordering. These are recorded decisions with rationale, not gaps.
+
 ## Quick Reference
 
 ### Generated endpoints

package/AGENTS_BACKEND.md

@@ -773,7 +773,7 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 
 - **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()`.
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
-- **`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.
+- **`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.
 - **`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.
@@ -894,6 +894,31 @@ const TableCustomer = defineTable({
 });
 ```
 
+### Protect sensitive fields on update (isAdmin, roles, ownership)
+
+Every Schema field is updatable by default — the plugin does not impose field-level rules
+(see `excludeFromCreation` in Key Conventions). Encode yours in the hooks:
+
+```typescript
+const TableUser = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaUser),
+  // Silent strip: non-admins simply cannot touch the flag
+  beforeUpdate: async (db, req, fields) => {
+    if (!req.user.isAdmin) delete fields.isAdmin;
+  },
+  // Or loud 400 via validate:
+  // validate: async (db, req, main) => {
+  //   if (main.isAdmin !== undefined && !req.user.isAdmin)
+  //     return [['isAdmin', 'forbidden']];
+  //   return [];
+  // },
+});
+```
+
+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`.
+
 ### Full-text search filter
 
 ```typescript

package/CHANGELOG.md

@@ -7,6 +7,37 @@ 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)**.
 
+## [0.1.10]
+
+### Added
+
+- **Architecture Decision Records** in `docs/adr/` (shipped in the npm package so agents
+  consuming the library can read them): no-ORM/raw-SQL, open-by-default, non-transactional
+  bulk operations, always-updatable fields (no `excludeFromUpdate`), insert-pipeline
+  ordering, raw DB errors. Linked from README ("Design Decisions") and AGENTS.md.
+
+### Fixed
+
+- **`excludeFromCreation` no longer strips values set by `beforeInsert`.** The exclusion list
+  was applied after the hook, so a server-generated value assigned in `beforeInsert` (the
+  documented pattern for TEXT primary keys, `createdAt`, audit columns) was silently removed
+  from the INSERT — a table with `excludeFromCreation: ['id']` and an id-generating hook
+  failed with a not-null violation. The client payload is now sanitized *before* the hook
+  runs, in both the single insert and the bulk upsert path: client-supplied values on
+  excluded fields are still ignored, hook-assigned ones reach the SQL. For the same reason,
+  secondary records now drop excluded fields *before* the engine's FK auto-fill, so listing
+  the FK column in a secondary table's `excludeFromCreation` no longer erases the injected
+  parent key.
+
+### Documentation
+
+- Clarified that `excludeFromCreation` is an ergonomics tool for creation, not a field-level
+  security mechanism: it deliberately does not apply to updates, where every Schema field is
+  writable by default. Field-level update rules (sensitive flags, roles, ownership/tenant
+  columns) are product logic to enforce via `beforeUpdate`/`validate` or dedicated endpoints —
+  see the new "Field-level update rules" section in the README and the matching pattern in
+  AGENTS_BACKEND.md.
+
 ## [0.1.7]
 
 ### Fixed

package/README.md

@@ -39,48 +39,67 @@ Point it at your database, and get a full REST API with search, advanced conditi
 
 ```bash
 npm install fastify-auto-sqlapi fastify @fastify/postgres
+# MySQL/MariaDB: npm install fastify-auto-sqlapi fastify mysql2
 ```
 
 ### 2. Create the config file
 
-Create `sqlapi.config.ts` in your project root. This is used only by the CLI generators, not at runtime.
+Create `sqlapi.config.ts` (or `.mjs`/`.js`) in your project root. This is used only by the
+CLI generators, not at runtime.
 
 ```typescript
 export default {
-  outputDir: './src/schemas',  // where to generate Schema files
-  schema: 'public',            // PostgreSQL schema to introspect
+  outputDir: './src/db',       // base dir for generated files (default: './src/db')
+  schema: 'public',            // PostgreSQL schema to introspect (default: 'public')
+  // dialect: 'mysql',         // 'postgres' (default) | 'mysql' | 'mariadb'
+  // envFile: '.env.local',    // env file to load (default: '.env')
 };
 ```
 
-The DB connection is read from environment variables:
+The DB connection is read from environment variables (a `.env` file in the project root is
+loaded automatically, without overriding variables already set):
 
 ```bash
 # Either a full connection string:
-DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb   # or mysql://...
 
-# Or individual vars:
+# Or individual vars (PostgreSQL):
 POSTGRES_HOST=127.0.0.1
 POSTGRES_PORT=5432
 POSTGRES_USER=myuser
 POSTGRES_PASSWORD=mypassword
 POSTGRES_DB=mydb
+
+# Or individual vars (MySQL/MariaDB):
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306
+MYSQL_USER=myuser
+MYSQL_PASSWORD=mypassword
+MYSQL_DB=mydb
 ```
 
 ### 3. Generate schemas from your database
 
 ```bash
-npx sqlapi-generate-schema
+npx sqlapi-generate-schema                  # all tables
+npx sqlapi-generate-schema --tables customer,order   # only some
+npx sqlapi-generate-schema --dialect mysql  # override the config dialect
 ```
 
-This introspects your tables and generates one TypeBox schema file per table (e.g. `SchemaCustomer.ts`, `SchemaOrder.ts`). These files are auto-generated — don't edit them.
+This introspects your tables and generates one TypeBox schema file per table in
+`<outputDir>/schemas/` (e.g. `SchemaCustomer.ts`, `SchemaOrder.ts`). These files are
+auto-generated — don't edit them; re-run the command after a DB change.
 
 ### 4. Generate the tables template
 
 ```bash
-npx sqlapi-generate-tables
+npx sqlapi-generate-tables --all            # or: npx sqlapi-generate-tables customer order
 ```
 
-This creates a `tables.ts` file with a `defineTable()` call for each table. It auto-detects primary keys, foreign key relations, and lays out all available options as commented code. **This file is yours to customize.**
+This creates in `<outputDir>/tables/` one `Table*.ts` file per table — a `defineTable()`
+call with auto-detected primary keys, foreign key relations, and all available options as
+commented code — plus a `dbTables.ts` index. **These files are yours to customize**: the
+generator never overwrites an existing file, so re-running it only adds files for new tables.
 
 ### 5. Register the plugin
 
@@ -88,7 +107,7 @@ This creates a `tables.ts` file with a `defineTable()` call for each table. It a
 import Fastify from 'fastify';
 import fastifyPostgres from '@fastify/postgres';
 import { fastifyAutoSqlApi } from 'fastify-auto-sqlapi';
-import { dbTables } from './src/schemas/tables.js';
+import { dbTables } from './src/db/tables/dbTables.js';
 
 const app = Fastify();
 
@@ -156,7 +175,8 @@ const TableCustomer = defineTable({
 
   // Ordering & filtering
   defaultOrder: 'name',                     // default ORDER BY (camelCase fields map to DB columns)
-  excludeFromCreation: ['id'],              // omit from INSERT (e.g. auto-increment)
+  excludeFromCreation: ['id'],              // client-sent values ignored on INSERT (auto-increment,
+                                            // DB defaults); beforeInsert can still set them
   readExclude: ['passwordHash'],            // hide from all reads (writes unaffected)
   distinctResults: true,                    // SELECT DISTINCT
 
@@ -269,7 +289,20 @@ await app.register(fastifyAutoSqlApi, {
 | `maxBulkItems` | `number` | No | Max number of items accepted by the bulk endpoints (default: `1000`) |
 | `debug` | `boolean` | No | Log all SQL queries to console |
 
-For MySQL/MariaDB, register `mysql2/promise` pool instead of `@fastify/postgres` and pass `dialect: 'mysql'` or `'mariadb'`.
+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' });
+```
 
 ## Security
 
@@ -333,6 +366,42 @@ only columns present in the generated Schema (as narrowed by `schemaOverrides` /
 column — the Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`)
 to keep sensitive columns out of it.
 
+### Field-level update rules are product logic — use the hooks
+
+`excludeFromCreation` is an **ergonomics tool for creation**, not a security mechanism: it
+exists so auto-generated values (serial PKs, DB-default timestamps) don't have to be sent —
+or validated — on insert. It deliberately does **not** apply to updates: every field in the
+Schema is updatable by default, because whether a field may change is a product decision the
+plugin cannot make for you (a super admin may legitimately fix an `updatedAt`; in one product
+users may move themselves across tenants, in another nobody may).
+
+So watch out for **sensitive flags and ownership fields** — `isAdmin`, `role`, tenant/owner
+columns, state fields: if they are in the Schema, the auto-generated update route will accept
+them. Encode your rules with the tools made for it:
+
+```typescript
+// Silent strip: non-admins simply cannot touch the flag
+beforeUpdate: async (db, req, fields) => {
+  if (!req.user.isAdmin) delete fields.isAdmin;
+},
+
+// Loud 400: touching the flag without permission is an error
+validate: async (db, req, main) => {
+  if (main.isAdmin !== undefined && !req.user.isAdmin)
+    return [['isAdmin', 'forbidden']];
+  return [];
+},
+```
+
+For privileged state transitions (promoting an admin, moving a record across tenants) consider
+a dedicated endpoint with its own auth and audit instead of the auto-generated CRUD route —
+`operations` lets you keep the sensitive operation off the auto routes entirely.
+
+Note on tenants: when `tenantScope` is active, tenant-scoped callers can never move a record to
+another tenant (the tenant column is enforced server-side); admin callers (`getTenantId` →
+`null`) are unrestricted. That is the isolation contract of the opt-in tenancy feature, not a
+field-level rule.
+
 ### Read visibility
 
 `readExclude` hides columns from every read while leaving writes untouched — the case for a
@@ -491,7 +560,8 @@ Returns `{ main: { ... } }` or 404.
 
 ### DELETE /rest/{table}/:id
 
-Returns the deleted record or 404.
+**Response (200):** `{ main: { <pk>: ... } }` (PK-only, like all write responses), or `404` if
+the record does not exist.
 
 ### PUT /bulk/{table}
 
@@ -621,6 +691,14 @@ await app.register(async (instance) => {
 }, { prefix: '/admin' });
 ```
 
+## Design Decisions
+
+Deliberate, non-obvious choices — open-by-default, non-transactional bulk operations,
+always-updatable fields, raw DB errors, insert-pipeline ordering — are recorded as
+[Architecture Decision Records in `docs/adr/`](./docs/adr/README.md), each with its
+rationale and the alternatives that were rejected. Read them before filing an issue that
+proposes changing one of these behaviors.
+
 ## Conventions
 
 - **camelCase everywhere in the API** — requests, responses, `validate`, and all hooks (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`) use schema field names

package/dist/lib/engine/write-helpers.d.ts

@@ -2,7 +2,20 @@ import type { FastifyRequest } from 'fastify';
 import type { QueryClient } from '../db.js';
 import type { ITable, DbTables, JoinDefinition } from '../../types.js';
 export declare function findWriteJoin(tableConf: ITable, alias: string): JoinDefinition | undefined;
+/**
+ * Drop `excludeFromCreation` columns from a snake_case (DB-format) record.
+ *
+ * Exclusion is a whitelist on CLIENT input: call this on the client payload only,
+ * BEFORE any server-side value is assigned (beforeInsert mutations, FK auto-fill),
+ * so engine/hook-generated values on those fields reach the SQL.
+ */
 export declare function removeExcludedFields(record: Record<string, unknown>, tableConf: ITable): Record<string, unknown>;
+/**
+ * Same whitelist as `removeExcludedFields`, but for a camelCase record (schema
+ * field names) and in place. Used on the client payload before the beforeInsert
+ * hook runs.
+ */
+export declare function removeExcludedFieldsCamel(record: Record<string, unknown>, tableConf: ITable): void;
 export declare function findSecondaryTableConf(dbTables: DbTables, joinTableName: string): ITable | undefined;
 interface PrepareCtx {
     db: QueryClient;
@@ -12,10 +25,11 @@ interface PrepareCtx {
 /**
  * Prepare a single record for INSERT/UPSERT:
  *   1. shallow camelCase copy of `input`
- *   2. runValidation (camelCase)
- *   3. beforeInsert hook (caller can mutate the camelCase copy)
- *   4. snakecaseRecord → DB format
- *   5. removeExcludedFields
+ *   2. runValidation (camelCase — sees the client payload as sent)
+ *   3. drop excludeFromCreation fields (client-input whitelist; applied BEFORE the
+ *      hook so values it assigns — e.g. a server-generated id — reach the INSERT)
+ *   4. beforeInsert hook (caller can mutate the camelCase copy)
+ *   5. snakecaseRecord → DB format
  *
  * Returns both `camel` (input + hook mutations, used for FK auto-fill / afterInsert) and
  * `snake` (DB-ready record). The original `input` is left intact.

package/dist/lib/engine/write-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/write-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EACR,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,cAAc,GAAG,SAAS,CAE5B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACvD,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAe7E;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACrD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CA2DpD;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CA+BpD"}
+{"version":3,"file":"write-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/write-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EACR,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,cAAc,GAAG,SAAS,CAE5B;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GAChB,IAAI,CAKN;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACvD,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAe7E;AAED,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACrD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CA4DpD;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CA+BpD"}

package/dist/lib/engine/write-helpers.js

@@ -3,6 +3,13 @@ import { runValidation } from './validate.js';
 export function findWriteJoin(tableConf, alias) {
     return tableConf.allowedWriteJoins?.find((j) => j.alias === alias);
 }
+/**
+ * Drop `excludeFromCreation` columns from a snake_case (DB-format) record.
+ *
+ * Exclusion is a whitelist on CLIENT input: call this on the client payload only,
+ * BEFORE any server-side value is assigned (beforeInsert mutations, FK auto-fill),
+ * so engine/hook-generated values on those fields reach the SQL.
+ */
 export function removeExcludedFields(record, tableConf) {
     if (!tableConf.excludeFromCreation?.length)
         return record;
@@ -13,6 +20,18 @@ export function removeExcludedFields(record, tableConf) {
     }
     return result;
 }
+/**
+ * Same whitelist as `removeExcludedFields`, but for a camelCase record (schema
+ * field names) and in place. Used on the client payload before the beforeInsert
+ * hook runs.
+ */
+export function removeExcludedFieldsCamel(record, tableConf) {
+    if (!tableConf.excludeFromCreation?.length)
+        return;
+    for (const field of tableConf.excludeFromCreation) {
+        delete record[field];
+    }
+}
 export function findSecondaryTableConf(dbTables, joinTableName) {
     for (const [, conf] of Object.entries(dbTables)) {
         if (conf.Schema.tableName === joinTableName)
@@ -23,10 +42,11 @@ export function findSecondaryTableConf(dbTables, joinTableName) {
 /**
  * Prepare a single record for INSERT/UPSERT:
  *   1. shallow camelCase copy of `input`
- *   2. runValidation (camelCase)
- *   3. beforeInsert hook (caller can mutate the camelCase copy)
- *   4. snakecaseRecord → DB format
- *   5. removeExcludedFields
+ *   2. runValidation (camelCase — sees the client payload as sent)
+ *   3. drop excludeFromCreation fields (client-input whitelist; applied BEFORE the
+ *      hook so values it assigns — e.g. a server-generated id — reach the INSERT)
+ *   4. beforeInsert hook (caller can mutate the camelCase copy)
+ *   5. snakecaseRecord → DB format
  *
  * Returns both `camel` (input + hook mutations, used for FK auto-fill / afterInsert) and
  * `snake` (DB-ready record). The original `input` is left intact.
@@ -39,11 +59,11 @@ export async function prepareInsertRecord(ctx, input, secondaries, options) {
     if (!options?.skipValidate) {
         await runValidation(ctx.db, ctx.request, ctx.tableConf, camel, secondaries);
     }
+    removeExcludedFieldsCamel(camel, ctx.tableConf);
     if (ctx.tableConf.beforeInsert) {
         await ctx.tableConf.beforeInsert(ctx.db, ctx.request, camel);
     }
-    let snake = snakecaseRecord(camel, ctx.tableConf.Schema);
-    snake = removeExcludedFields(snake, ctx.tableConf);
+    const snake = snakecaseRecord(camel, ctx.tableConf.Schema);
     return { camel, snake };
 }
 export async function processSecondaries(db, tableConf, dbTables, mainRecord, secondaries) {
@@ -63,15 +83,16 @@ export async function processSecondaries(db, tableConf, dbTables, mainRecord, se
             : joinSchema.col(secondaryPk);
         const preparedRecords = records.map((rec) => {
             let prepared = snakecaseRecord(rec, joinSchema);
+            // Remove excluded fields from the client payload BEFORE the FK auto-fill:
+            // an excluded FK column must not strip the engine-injected value below.
+            if (secondaryTableConf) {
+                prepared = removeExcludedFields(prepared, secondaryTableConf);
+            }
             // Auto-fill FK from main record
             const mainValue = Array.isArray(mainField)
                 ? mainRecord[mainField[0]]
                 : mainRecord[mainField];
             prepared[joinCol] = mainValue;
-            // Remove excluded fields
-            if (secondaryTableConf) {
-                prepared = removeExcludedFields(prepared, secondaryTableConf);
-            }
             return prepared;
         });
         const secondaryUpsertKeys = tableConf.upsertMap?.get(joinSchema);

package/docs/adr/0001-no-orm-raw-sql.md

@@ -0,0 +1,38 @@
+# 0001. No ORM — raw SQL with minimal dependencies
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (foundational decision, predates this record)
+
+## Context
+
+Auto-generating CRUD APIs from database tables is the territory of ORMs and heavy
+API-builder frameworks. Adopting one would have provided models, migrations and query
+building for free — at the price of a large dependency tree, an abstraction layer between
+the consumer and their SQL, and lock-in to the ORM's schema model.
+
+## Decision
+
+The plugin talks to the database with raw SQL through thin driver adapters (`pg`,
+`mysql2`), composing WHERE clauses with `node-condition-builder` and validating with
+TypeBox. No ORM, no query-builder DSL, no migration system. Runtime dependencies are kept
+to the minimum, and the plugin re-exports its building blocks (TypeBox, ConditionBuilder)
+so consumers build on the same tools instead of adding parallel ones.
+
+## Alternatives considered
+
+- **Build on an ORM (Prisma, Drizzle, Sequelize, …)** — rejected: large dependency
+  surface, a second schema definition to keep in sync with the DB, and the ORM's
+  abstractions leak into the public API. The CLI introspection (`information_schema`)
+  gives the same "schema from the DB" ergonomics without the layer.
+- **Hand-rolled query-builder DSL** — rejected: reinvents an ORM incrementally.
+  `node-condition-builder` covers the one genuinely composable part (conditions);
+  everything else is plain SQL the maintainer can read and debug.
+
+## Consequences
+
+- The engine owns dialect differences (placeholders, quoting, RETURNING vs insertId)
+  explicitly — see `src/lib/dialect.ts` and the adapters.
+- Consumers get a framework approach: tools are provided (SqlApi, QueryClient,
+  ConditionBuilder), product structure is not imposed.
+- Features an ORM would give for free (migrations, lazy relations, identity maps) are
+  intentionally out of scope.

package/docs/adr/0002-open-by-default.md

@@ -0,0 +1,37 @@
+# 0002. Open by default — no imposed auth model
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Registering the plugin with no configuration exposes every operation (read and write,
+including bulk delete) on every table in `DbTables`. Security reviews repeatedly flag this
+as a vulnerability and propose secure-by-default behavior: routes disabled until
+explicitly enabled, or a mandatory auth hook.
+
+## Decision
+
+The plugin stays open by default. Authentication and authorization are the consumer's
+job, wired through the tools provided for it: `onRequests` (global or per-table request
+hooks), `operations` (per-table whitelist of registered routes), and `tenantScope`
+(tenant isolation). The README carries a prominent warning in its Security section.
+
+## Alternatives considered
+
+- **Deny-by-default routes** (`operations` required, empty = nothing exposed) — rejected:
+  it turns the five-minute quick start into configuration boilerplate, and the plugin's
+  primary use case is rapid internal API scaffolding where the consumer adds auth at the
+  Fastify level anyway.
+- **Mandatory auth callback** (refuse to register without an `onRequests`) — rejected:
+  imposes an auth model on consumers who legitimately handle auth outside the plugin
+  (gateway, network isolation, Fastify-level hooks on the parent scope).
+
+## Consequences
+
+- **You must lock it down before exposing it.** The responsibility is documented, not
+  enforced.
+- Security reviews will keep flagging this; the answer is this ADR plus the README
+  Security section, not a behavior change.
+- `operations` gates HTTP routes only — the programmatic `sqlApi.*` methods remain
+  available to consumer code, by design.

package/docs/adr/0003-bulk-not-transactional.md

@@ -0,0 +1,35 @@
+# 0003. Bulk operations are not transactional
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Single insert and update run inside a transaction: main record, secondaries, deletions
+and after-hooks are atomic (`QueryClient.withTransaction`, degrading gracefully when the
+adapter has no `connect()`). Bulk upsert and bulk delete do not — a failure partway
+through leaves the earlier items committed. Reviews periodically report this as an
+inconsistency and propose wrapping bulk operations in a transaction.
+
+## Decision
+
+Bulk operations stay non-transactional. They are a shortcut for issuing many single
+operations efficiently, not an atomic batch primitive: "all or nothing" is explicitly not
+part of their contract.
+
+## Alternatives considered
+
+- **Wrap each bulk request in one transaction** — rejected: changes the semantics from
+  "N independent operations" to "one atomic batch", which is a different feature. Large
+  batches would also hold long transactions with the associated lock footprint.
+- **Opt-in `transactional: true` flag** — rejected for now: adds API surface for a need
+  no consumer has expressed; a consumer needing atomicity can call the programmatic
+  `sqlApi.*` methods inside their own `withTransaction`.
+
+## Consequences
+
+- A failed bulk request may have partially applied. Consumers that care must either
+  retry idempotently (upsert semantics make this natural) or manage their own
+  transaction via the programmatic API.
+- Bulk delete reports the ids actually deleted (`afterBulkDelete` receives the actual
+  subset), which is the honest contract for a non-atomic batch.

package/docs/adr/0004-updates-always-open.md

@@ -0,0 +1,46 @@
+# 0004. Updates are always open — no `excludeFromUpdate`
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+`excludeFromCreation` strips client-supplied fields from inserts. A symmetric
+`excludeFromUpdate` was proposed to statically block fields on the update path (e.g.
+`createdAt`, `isAdmin`), partly to close the asymmetry where a field excluded from
+creation can still be modified via `PUT`.
+
+## Decision
+
+No `excludeFromUpdate`. Every Schema field is updatable by default, and
+`excludeFromCreation` is defined as an **ergonomics tool for creation** (auto-generated
+PKs, DB-default columns — its original purpose was handling autoincrement validation),
+**not** a field-level security mechanism.
+
+Field-level update rules are product logic the plugin must not decide: a super admin may
+legitimately fix an `updatedAt`; in one product users may move themselves across tenants,
+in another an admin moves others, in a third nobody moves anyone. A static list cannot
+express any of this — real authorization is contextual (session, role, record state).
+Consumers encode their rules in `beforeUpdate` (silent strip) or `validate` (loud 400),
+or move privileged transitions to dedicated endpoints and keep them off the auto routes
+via `operations`.
+
+## Alternatives considered
+
+- **`excludeFromUpdate` list** — rejected: the main risk is the *false sense of
+  security*. It only covers "nobody, ever, via API", while the dangerous real-world cases
+  (`isAdmin`, roles, ownership) are session-dependent — someone would use the list for
+  them and believe the problem solved.
+- **`immutable: [...]` / per-field `writable` modes** — rejected: a bigger redesign of
+  the write model for the same limited static semantics.
+
+## Consequences
+
+- Sensitive flags in the Schema are updatable through the auto routes until the consumer
+  adds a hook. This is documented prominently (README Security → "Field-level update
+  rules are product logic", AGENTS_BACKEND.md pattern "Protect sensitive fields on
+  update").
+- The tenant column is the one deliberate exception, and only under opt-in `tenantScope`:
+  tenant-scoped callers cannot re-tenant records (isolation contract), while admin
+  callers (`getTenantId` → `null`) remain unrestricted — consistent with "the plugin does
+  not decide product rules".

package/docs/adr/0005-insert-pipeline-sanitize-before-hooks.md

@@ -0,0 +1,51 @@
+# 0005. Insert pipeline: client payload sanitized before `beforeInsert`
+
+- **Status**: accepted
+- **Date**: 2026-07-23
+
+## Context
+
+Until v0.1.9 the insert pipeline applied `excludeFromCreation` *after* the `beforeInsert`
+hook, so a value the hook assigned to an excluded field was silently stripped from the
+INSERT. This broke the documented server-generated-id pattern (TEXT PK in
+`excludeFromCreation`, id generated in `beforeInsert` → not-null violation) and
+contradicted the documented contract that hook mutations propagate to the SQL. The same
+ordering flaw let an excluded FK column erase the engine's own FK auto-fill on secondary
+records.
+
+## Decision
+
+Exclusion is a whitelist on **client input** and runs at the client boundary. The insert
+pipeline order is, for both single insert and bulk upsert:
+
+1. `validate` — receives the payload **as sent by the client** (documented contract);
+2. `excludeFromCreation` strip;
+3. `beforeInsert` — hook mutations, including on excluded fields, reach the SQL;
+4. conversion to DB column format.
+
+For secondary records, exclusion runs **before** the engine's FK auto-fill, so the
+injected parent key always survives.
+
+Server-side writers are ordered by trust: client input is sanitized first, then hooks
+mutate freely, then engine-enforced values (tenant injection/validation) run last and
+fail loudly on conflict rather than stripping silently.
+
+## Alternatives considered
+
+- **Strip after the hook** (previous behavior) — rejected: silently discards
+  server-generated values; the only thing it "protected" was the ability of a hook to
+  accidentally write an excluded field, which is server code and trusted.
+- **Strip before `validate` too** — rejected: `validate` is documented to receive the
+  record as sent by the client; changing its input would break that contract for no
+  gain.
+
+## Consequences
+
+- The pattern `excludeFromCreation: ['id']` + id-generating `beforeInsert` works as
+  documented; consumers no longer need the `schemaOverrides` workaround.
+- Behavior change (noted in the CHANGELOG): a hook that assigns an excluded field now
+  writes it, where it was previously discarded.
+- `afterInsert` no longer sees client-supplied values on excluded fields — it sees what
+  was actually written.
+- Locked by unit tests (single, bulk, upsert, secondaries, validate-ordering) and by a
+  dialect-parametric integration suite reproducing the original failure.

package/docs/adr/0006-raw-db-errors.md

@@ -0,0 +1,34 @@
+# 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
+
+- **Status**: accepted
+- **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
+
+## Context
+
+Constraint violations (unique, foreign key, not-null) bubble up from the driver and reach
+the client as a `500` carrying the raw database message. A review proposed mapping
+SQLSTATE codes to HTTP semantics — unique violation → `409`, FK/not-null violation →
+`400` — with sanitized messages.
+
+## Decision
+
+No SQLSTATE mapping in the engine. Errors the plugin itself detects (validation, missing
+PK, not found, tenant violations) throw proper `4xx` via `httpError`; everything coming
+from the database is passed through unmapped.
+
+## Alternatives considered
+
+- **SQLSTATE→HTTP mapping layer** — rejected: the mapping is dialect-specific
+  (PostgreSQL SQLSTATE vs MySQL errno), inevitably partial, and encodes product decisions
+  (is a duplicate a conflict to surface or an internal bug?) the plugin should not make.
+- **Sanitizing DB messages** — rejected as a plugin default: hiding details is an
+  environment policy, and Fastify already gives consumers the hook for it.
+
+## Consequences
+
+- Constraint violations look like server errors (`500`) to API clients, and driver
+  messages may leak schema details (table/column/constraint names). Consumers who care
+  set a Fastify `setErrorHandler` — one place, their policy, their status codes.
+- A consumer-facing "friendly duplicate error" is expected to be handled in `validate`
+  (explicit pre-check) or in the consumer's error handler, not by the engine guessing
+  intent from SQLSTATE.

package/docs/adr/README.md

@@ -0,0 +1,49 @@
+# Architecture Decision Records
+
+Deliberate design decisions of `fastify-auto-sqlapi`, with their rationale and the
+alternatives that were considered and rejected.
+
+**If you are an agent or a contributor about to "fix" one of the behaviors below: read the
+matching ADR first.** These are not gaps or oversights — proposals that re-litigate a
+decision recorded here should either reference new arguments the ADR does not address, or
+be dropped.
+
+ADRs are immutable: a decision is changed by adding a new ADR that supersedes the old one,
+not by editing history.
+
+## Index
+
+| # | Decision |
+|---|----------|
+| [0001](./0001-no-orm-raw-sql.md) | No ORM — raw SQL with minimal dependencies |
+| [0002](./0002-open-by-default.md) | Open by default — no imposed auth model |
+| [0003](./0003-bulk-not-transactional.md) | Bulk operations are not transactional |
+| [0004](./0004-updates-always-open.md) | Updates are always open — no `excludeFromUpdate` |
+| [0005](./0005-insert-pipeline-sanitize-before-hooks.md) | Insert pipeline: client payload sanitized before `beforeInsert` |
+| [0006](./0006-raw-db-errors.md) | Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping |
+
+## When to write one
+
+Only when a decision was genuinely debated, or is counter-intuitive enough that a reasonable
+outsider would mistake it for a bug. Plain conventions belong in [AGENTS.md](../../AGENTS.md).
+
+## Format
+
+```markdown
+# NNNN. Title (imperative statement of the decision)
+
+- **Status**: accepted | superseded by NNNN
+- **Date**: YYYY-MM-DD
+
+## Context
+What problem or tension forced a choice.
+
+## Decision
+What was decided, stated plainly.
+
+## Alternatives considered
+Each rejected option and the reason it lost.
+
+## Consequences
+What follows — including the costs accepted knowingly.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "AGENTS.md",
     "AGENTS_BACKEND.md",
     "AGENTS_FRONTEND.md",