fastify-auto-sqlapi 0.3.0 → 0.4.1

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

@@ -1,6 +1,18 @@
 import type { ApiRequest } from '../../types/request.js';
 import type { QueryClient } from '../db.js';
-import type { ITable, DbTables, TenantContext } from '../../types.js';
+import type { ITable, DbTables, TenantContext, SchemaDefinition } from '../../types.js';
+/**
+ * Every upserted record must carry its key (ADR 0021), checked on the record as it reaches the
+ * database — after hooks, tenant injection and the FK auto-fill of secondaries:
+ * - a natural key needs every field present and not null: a NULL never conflicts, so the row
+ *   could only be inserted and never found again by its key;
+ * - on the primary key, a record naming no PK field at all is a plain insert with a generated
+ *   key; one naming it only in part, or as null, is refused like a natural key;
+ * - two records of one request with the same key are refused: PostgreSQL cannot affect a row
+ *   twice in one statement, MySQL would let the last one win.
+ * Throws 400 before any SQL runs. Column names and record keys are DB column names.
+ */
+export declare function assertUpsertKeys(schema: SchemaDefinition, conflictCols: string[], pkCols: string[], records: Record<string, unknown>[]): void;
 export declare function findSecondaryTableConf(dbTables: DbTables, joinTableName: string): ITable | undefined;
 /**
  * The context a per-alias write pass runs in. Shared by `processSecondaries` and

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,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAU5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAGR,aAAa,EACd,MAAM,gBAAgB,CAAC;AAmCxB,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,wFAAwF;IACxF,OAAO,EAAE,UAAU,CAAC;CACrB;AAmCD,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;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,CAgB7E;AAkCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,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,CA0DpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,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,CAoBpD"}
+{"version":3,"file":"write-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/write-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAW5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAGR,aAAa,EACb,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GACjC,IAAI,CA0BN;AAmCD,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,wFAAwF;IACxF,OAAO,EAAE,UAAU,CAAC;CACrB;AAmCD,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;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,CAgB7E;AAkCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,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,CA8DpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,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,CAoBpD"}

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

@@ -1,7 +1,41 @@
 import { camelcaseObject, snakecaseRecord } from '../naming.js';
 import { runValidation } from './validate.js';
 import { removeWriteExcluded } from '../write-access.js';
+import { httpError } from '../errors.js';
 import { tenantForTable, buildTenantRowGuard, enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../tenant.js';
+/**
+ * Every upserted record must carry its key (ADR 0021), checked on the record as it reaches the
+ * database — after hooks, tenant injection and the FK auto-fill of secondaries:
+ * - a natural key needs every field present and not null: a NULL never conflicts, so the row
+ *   could only be inserted and never found again by its key;
+ * - on the primary key, a record naming no PK field at all is a plain insert with a generated
+ *   key; one naming it only in part, or as null, is refused like a natural key;
+ * - two records of one request with the same key are refused: PostgreSQL cannot affect a row
+ *   twice in one statement, MySQL would let the last one win.
+ * Throws 400 before any SQL runs. Column names and record keys are DB column names.
+ */
+export function assertUpsertKeys(schema, conflictCols, pkCols, records) {
+    const isPrimaryKey = conflictCols.length === pkCols.length
+        && conflictCols.every((c) => pkCols.includes(c));
+    const fieldOf = (col) => Object.keys(schema.fields).find((f) => schema.col(f) === col) ?? col;
+    const rule = `Upsert on "${schema.tableName}" by (${conflictCols.map(fieldOf).join(', ')})`;
+    const seen = new Map();
+    records.forEach((record, i) => {
+        if (isPrimaryKey && conflictCols.every((c) => record[c] === undefined))
+            return;
+        const missing = conflictCols.filter((c) => record[c] == null);
+        if (missing.length) {
+            throw httpError(400, `${rule}: the row at index ${i} has no value for ${missing.map(fieldOf).join(', ')} — ` +
+                `an upserted row must carry its whole key`);
+        }
+        const key = JSON.stringify(conflictCols.map((c) => record[c]));
+        const first = seen.get(key);
+        if (first !== undefined) {
+            throw httpError(400, `${rule}: the rows at index ${first} and ${i} have the same key`);
+        }
+        seen.set(key, i);
+    });
+}
 /**
  * Resolve the write join an alias names, or undefined when the table does not declare it.
  *
@@ -144,6 +178,7 @@ export function processSecondaries(pass, secondaries) {
         let pkRows;
         if (upsertKeys) {
             const conflictCols = upsertKeys.map((k) => joinSchema.col(k));
+            assertUpsertKeys(joinSchema, conflictCols, (joinSchema.primaryKey ?? [childPk].flat()).map((f) => joinSchema.col(f)), preparedRecords);
             // A conflicting upsert must not overwrite — or re-parent — a child row owned by
             // another tenant, which the ON CONFLICT key alone would happily match.
             await assertTenantOwnsConflicts(db, childTenant, joinSchema.tableName, conflictCols, preparedRecords);

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;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"}
+{"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,CAYX;AAmVD,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

@@ -55,6 +55,7 @@ export function defineTable(config) {
     validateWriteExclude(config);
     validateTenantScope(config);
     validateTenantColumnNames(config);
+    validateUpsertMap(config);
     return config;
 }
 /**
@@ -255,6 +256,46 @@ function validateWriteExclude(config) {
         }
     }
 }
+const formatKey = (fields) => `(${fields.join(', ')})`;
+const sameFieldSet = (a, b) => a.length === b.length && a.every((f) => b.includes(f));
+/**
+ * An `upsertMap` rule must name a unique key the database enforces — the Schema's
+ * `primaryKey` or one of its `uniqueKeys`, as a set: same fields, any order, nothing extra
+ * (ADR 0021). Anything else fails every write on PostgreSQL, and on MySQL duplicates rows or
+ * updates a row matched through another key, in silence.
+ *
+ * Fail-closed: a rule the Schema cannot vouch for is refused. The Schema is what is read, not
+ * a table config, so a child written only through a write join needs no `defineTable`.
+ */
+function validateUpsertMap(config) {
+    for (const [schema, keys] of config.upsertMap ?? []) {
+        const problem = upsertKeyProblem(schema, keys);
+        if (problem) {
+            throw new Error(`defineTable: upsertMap rule on '${schema.tableName}' ${formatKey(keys)} ${problem} (ADR 0021).`);
+        }
+    }
+}
+/** Why `keys` is not a verified unique key of `schema`, or null when it is one. */
+function upsertKeyProblem(schema, keys) {
+    if (schema.isView)
+        return 'targets a view — a view has no unique key to upsert on';
+    const primaryKey = schema.primaryKey ?? [];
+    if (primaryKey.length && sameFieldSet(keys, primaryKey))
+        return null;
+    if (schema.uniqueKeys === undefined) {
+        return (`cannot be verified: the Schema of '${schema.tableName}' carries no uniqueKeys` +
+            `${primaryKey.length ? '' : ' and no primaryKey'} — regenerate the schemas with ` +
+            `sqlapi-generate-schema, an upsert must target a unique key the database enforces`);
+    }
+    if (schema.uniqueKeys.some((unique) => sameFieldSet(keys, unique)))
+        return null;
+    const available = [
+        ...(primaryKey.length ? [`${formatKey(primaryKey)} primary key`] : []),
+        ...schema.uniqueKeys.map(formatKey),
+    ];
+    return (`is not a unique key of the table. An upsert must target exactly one: ` +
+        `${available.length ? available.join(', ') : 'the table has none'}`);
+}
 function validateComputedFields(config) {
     const computed = config.computedFields;
     if (!computed)

package/dist/types/cli.d.ts

@@ -53,6 +53,12 @@ export interface ColumnInfo {
      * simple enough for the engine to make updatable accepts a write.
      */
     is_view?: boolean;
+    /**
+     * Names of the unique indexes (constraints included) this column belongs to, the primary key
+     * excluded. Only indexes over plain columns with no predicate: a partial or expression index
+     * cannot be named by a column list, so it cannot be an upsert key (ADR 0021).
+     */
+    unique_keys?: string[];
 }
 export interface TableMap {
     [schemaName: string]: {
@@ -65,6 +71,11 @@ export interface TableMap {
         generated: string[];
         /** True when this relation is a view (or a materialized view), not a base table. */
         isView: boolean;
+        /**
+         * Unique keys other than the primary key, each as its fields (camelCase). Always set by
+         * `buildTableMap`; absent only on a map built by hand.
+         */
+        uniqueKeys?: string[][];
     };
 }
 //# sourceMappingURL=cli.d.ts.map

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;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"}
+{"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;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;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;QAChB;;;WAGG;QACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;KACzB,CAAC;CACH"}

package/dist/types/schema.d.ts

@@ -15,6 +15,13 @@ export interface SchemaDefinition<T = Record<string, TSchema>> {
      * turn a client mistake into a driver error.
      */
     generatedFields?: string[];
+    /**
+     * The table's unique keys other than the primary key, each as its fields (camelCase), as
+     * introspected from the DB. Set by generated schemas — always, even when empty, so an absent
+     * property means "not known" rather than "none". `defineTable` verifies every `upsertMap`
+     * rule against `primaryKey` and these (ADR 0021).
+     */
+    uniqueKeys?: string[][];
     /**
      * True when the underlying relation is a view. Set by generated schemas.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC;IACV,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/docs/adr/0021-upsert-targets-a-verified-unique-key.md

@@ -0,0 +1,153 @@
+# 0021. An upsert targets a unique key verified at startup — MySQL and MariaDB upsert by key, not by `ON DUPLICATE KEY`
+
+- **Status**: accepted
+- **Date**: 2026-09-27
+
+## Context
+
+`upsertMap` turns an insert — main row, secondaries, every bulk item — into an upsert on the
+columns it names. Nothing checked those columns. `buildUpsertRule` accepts any field list, and
+the README's headline example relies on that freedom: a client that knows no ids syncs
+customers by `email` and their tags by `(customerId, tag)`.
+
+Investigating a bug report on bulk upserts showed that the two dialects do not agree on what
+such a rule means, and that MySQL can write to the wrong row without any error:
+
+| Declared key | PostgreSQL (`ON CONFLICT (key)`) | MySQL (`ON DUPLICATE KEY UPDATE`) |
+|---|---|---|
+| has no unique index | every write fails: *no unique or exclusion constraint matching the ON CONFLICT specification* | never conflicts: every upsert inserts, duplicates pile up in silence |
+| is unique, and the row carries another unique key matching a **different** row | unique violation on the other key | updates whichever row conflicts first — possibly the other one, in silence |
+| is unique, row updated through it, key is not the PK | `RETURNING` names the row | `insertId` names no updated row; the PK returned was `insertId + n`, a wrong or non-existent id, and secondaries were attached to it |
+
+MySQL's `ON DUPLICATE KEY UPDATE` has no conflict target at all: it fires on **any** unique
+index of the table, the primary key included. The columns declared in `upsertMap` do not
+select what MySQL matches on. A PK lookup by the declared key (the first fix attempted) is
+itself ambiguous when the key is not actually unique.
+
+The two failure modes that matter are the silent ones — duplicates and wrong-row writes on
+MySQL. PostgreSQL already fails loudly in every case above, just late (at the first write) and
+opaquely (a raw 500).
+
+## Decision
+
+**1. The Schema records the table's unique keys.** The CLI introspects every unique
+constraint and unique index — `pg_index.indisunique` on PostgreSQL,
+`information_schema.STATISTICS` with `NON_UNIQUE = 0` on MySQL — and emits them in the
+generated Schema as `uniqueKeys: [['email'], ['customerId', 'tag']]` (camelCase fields, the
+primary key excluded: it is `primaryKey`). The property is emitted even when empty, so its
+absence means "not generated by a CLI that knows about unique keys", never "no unique keys".
+Left out:
+
+- **partial and expression indexes** (`WHERE deleted_at IS NULL`, `lower(email)`): a column
+  list cannot express them, and PostgreSQL does not accept one as the target of
+  `ON CONFLICT (cols)`;
+- **keys with a column removed by `excludeColumns`**: the API can never write that column, so
+  it can never name the key.
+
+**2. `defineTable` refuses an `upsertMap` rule that is not a verified unique key.** For every
+rule — the table's own schema and every write-join schema — the declared field set must equal
+the Schema's `primaryKey` or one of its `uniqueKeys`, as a set: same fields, any order, nothing
+extra (the rule PostgreSQL itself applies to a conflict target). It is **fail-closed**: a rule
+that cannot be verified — a hand-written Schema, or one generated before `uniqueKeys` existed,
+whose rule is not its `primaryKey` — is refused with a message naming the table and telling to
+regenerate. The check reads the **Schema**, not a table config: a child table written only
+through a write join — `content_info(content_id, lang_id, …)` under `content` — needs no
+`defineTable` of its own; its rule sits in the parent's `upsertMap` and is verified against
+the child Schema's `primaryKey` / `uniqueKeys`. A view has no keys, so a view never takes an
+upsert rule. The check lives in
+`defineTable` with every other config check; a `DbTables` entry written as a plain object does
+not go through it, as it already skips the others.
+
+**3. Every upserted record must carry its key — `400` otherwise.**
+
+- *The key is a natural key* (not the primary key): every key field must be present and not
+  `null`. A `NULL` never conflicts, so such a record could only insert, and could not be found
+  again by its key.
+- *The key is the primary key*: a record **without** any PK field is a plain insert with a
+  generated key — the normal way to mix new and existing rows in one bulk. A PK present only
+  in part, or `null`, is a `400`.
+- **Two items of one request with the same key** are a `400`: PostgreSQL refuses to affect a
+  row twice in one statement, MySQL would let the last one win. Neither is a meaningful
+  request.
+
+The check runs on the record as it reaches the database — after hooks, tenant injection and
+the FK auto-fill of secondaries.
+
+**4. Execution: the same contract, one implementation per dialect.**
+
+- **PostgreSQL** keeps `INSERT … ON CONFLICT (key) DO UPDATE`: once the key is a verified
+  unique key, it targets exactly that key, and a collision on any other unique index is an
+  error — which is the contract. One statement per chunk, as before.
+- **MySQL and MariaDB** stop using `ON DUPLICATE KEY UPDATE` — it has no conflict target on
+  either — and upsert by key explicitly, per chunk:
+  1. **probe**: which items already exist, one `SELECT` for the chunk (a `UNION ALL` part per
+     item, tagged with its position, so value comparison stays the database's). More than one
+     row for one key means the key is not unique in the database (the index was dropped after
+     generation): the chunk is refused before anything is written. The tenant conflict guard
+     stays its own query, as on PostgreSQL: it lives in the engine, which owns the tenant;
+  2. **insert** the new items in one multi-row `INSERT`;
+  3. **update** the existing items by their key in one statement — each column a `CASE` over
+     the keys, the `WHERE` naming the same keys — so it can only reach the rows those keys
+     name. The number of rows matched must equal the number of items; a row deleted since the
+     probe is an error, not a silently skipped write. This relies on the driver reporting
+     matched rows, which `mysql2` does by default (`CLIENT_FOUND_ROWS`).
+
+  A collision on another unique index is then a duplicate-key error there too. PKs come from
+  the probe for existing rows and from the insert for new ones, so no PK lookup after the
+  write is needed.
+
+The observable behaviour is the same on both dialects, and one set of integration tests, run
+against both, is what pins it.
+
+## Alternatives considered
+
+- **Document the pitfalls, change nothing** — rejected: the MySQL failure modes are silent
+  data corruption, which no amount of documentation makes acceptable for a library that
+  advertises upsert-by-natural-key as a feature.
+- **Error only when the PK lookup finds several rows** — rejected as insufficient: it catches
+  a non-unique key after the write, and does nothing for `ON DUPLICATE KEY` matching a row
+  through another unique key.
+- **Reject any record carrying the columns of another unique key** — rejected: it forbids the
+  most common upsert of all, by `id` on a table with a unique `email`.
+- **Probe every other unique key and answer `409` when one matches a different row** — works on
+  both dialects, but adds a query per key per chunk on PostgreSQL, which needs none: its
+  `ON CONFLICT (key)` already errors on those collisions.
+- **Change the signature to `upsert(key, fields)`** — clearer intent, and it would make the
+  key checks of point 3 schema validation. It does not make anything safer on its own: MySQL
+  still matches on any unique index while `ON DUPLICATE KEY` is used, the key must still be a
+  verified unique key, and new rows with a generated PK still have no key to pass. A breaking
+  change for every client, for clarity only — deferred; it can come in a major release on top
+  of this decision without changing it.
+- **Explicit upsert on PostgreSQL too** — one implementation instead of two, but one or two
+  extra queries per chunk on the dialect whose native statement already has the right
+  semantics.
+- **Check the rules at plugin registration** — would also cover plain-object `DbTables`
+  entries, but splits config validation across two places; every other rule is enforced by
+  `defineTable`.
+
+## Consequences
+
+- **Breaking.** An `upsertMap` rule on columns without a unique index now fails at startup,
+  and so does any rule on a Schema that predates `uniqueKeys` unless it names the primary key:
+  regenerate the schemas. Records missing their key, and duplicate keys in one request, become
+  `400`s. Migration notes go in `BREAKING_CHANGES.md`.
+- **MySQL and MariaDB cost more.** An upsert is two to three statements per chunk (probe,
+  insert, update) instead of one, plus the tenant guard where there is one, as before;
+  PostgreSQL is unchanged. The count does not grow with the number of
+  rows in the chunk.
+- **A collision on another unique index is a database error** on both dialects — a sanitized
+  500 ([ADR 0013](./0013-sanitized-db-errors.md)). A descriptive `409` can be added later
+  without changing this decision.
+- **There is a window between probe and write on MySQL and MariaDB.** A concurrent insert of the same key
+  fails with a duplicate-key error; a concurrent delete fails the matched-row check. Both are
+  errors, never a wrong write — consistent with non-transactional bulk
+  ([ADR 0003](./0003-bulk-not-transactional.md)).
+- **A nullable unique column cannot be a natural upsert key for rows where it is `NULL`**: those
+  rows are inserted through a plain insert, or the column made `NOT NULL`.
+- The generated Schema is the source of truth for keys, as it is for columns
+  ([ADR 0017](./0017-the-schema-is-the-contract.md)): an index added or dropped in the database
+  reaches the API when the schemas are regenerated. A dropped index is still caught at runtime
+  by the probe on MySQL/MariaDB and by `ON CONFLICT` itself on PostgreSQL.
+- `QueryClient.bulkInsertOrUpdate` / `insertOrUpdate` get the upsert by key too, so a
+  custom route calling them directly is protected by the probe — but not by the startup check
+  or the `400`s, which need a table config.

package/docs/adr/README.md

@@ -35,6 +35,7 @@ not by editing history.
 | [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 |
+| [0021](./0021-upsert-targets-a-verified-unique-key.md) | An upsert targets a unique key verified at startup — MySQL and MariaDB upsert by key, not by `ON DUPLICATE KEY` |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",