fastify-auto-sqlapi 0.3.0 → 0.4.0

package/dist/lib/db.js

@@ -4,6 +4,8 @@ import { getDialect } from './dialect.js';
 // PostgreSQL's hard limit of 65535 bind parameters per statement (≈ 130 columns × 500 rows).
 // Override per-call via the `chunkSize` argument when working with extremely wide tables.
 const DEFAULT_CHUNK_SIZE = 500;
+// Column tagging each row of an upsert key lookup with its record's position in the chunk
+const LOOKUP_POSITION = 'sqlapi_lookup_position';
 /** @deprecated Use db.qi() instead */
 export const escapeIdent = (f) => f.replace(/"/g, '""');
 export class QueryClient {
@@ -90,39 +92,34 @@ export class QueryClient {
     #q(fields) {
         return fields.map((f) => this.dialect.qi(f)).join(', ');
     }
+    // The SQL for one value: a raw Expression inline, anything else bound as the next placeholder
+    #bind(val, values) {
+        if (val instanceof Expression)
+            return val.value;
+        values.push(val);
+        return this.dialect.ph(values.length);
+    }
     // Appends record fields/values to a shared values array, auto-indexing placeholders
     #params(record, values) {
         const fields = [];
         const placeholders = [];
         for (const [field, val] of Object.entries(record)) {
             fields.push(field);
-            if (val instanceof Expression) {
-                placeholders.push(val.value);
-            }
-            else {
-                values.push(val);
-                placeholders.push(this.dialect.ph(values.length));
-            }
+            placeholders.push(this.#bind(val, values));
         }
         return { fields, placeholders };
     }
+    // Builds `col = placeholder` pairs joined by `separator` (', ' for SET, ' AND ' for WHERE)
+    #equalities(record, values, separator) {
+        const { fields, placeholders } = this.#params(record, values);
+        return fields.map((f, i) => `${this.dialect.qi(f)} = ${placeholders[i]}`).join(separator);
+    }
     // Builds multi-row VALUES string for bulk operations
     #bulkValues(fields, records) {
         const values = [];
         const rowPlaceholders = [];
         for (const record of records) {
-            const cols = [];
-            for (const field of fields) {
-                const val = record[field];
-                if (val instanceof Expression) {
-                    cols.push(val.value);
-                }
-                else {
-                    values.push(val);
-                    cols.push(this.dialect.ph(values.length));
-                }
-            }
-            rowPlaceholders.push(`(${cols.join(', ')})`);
+            rowPlaceholders.push(`(${fields.map((field) => this.#bind(record[field], values)).join(', ')})`);
         }
         return { values, rows: rowPlaceholders.join(', ') };
     }
@@ -170,30 +167,179 @@ export class QueryClient {
         return this.#extractPkRows(result, pkCol, [record])[0];
     }
     async insertOrUpdate(table, record, conflictKeys, pkCol) {
-        const values = [];
-        const { fields, placeholders } = this.#params(record, values);
-        if (!fields.length)
+        if (!Object.keys(record).length)
             throw new Error('Cannot execute empty insert');
-        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, conflictKeys));
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
+        const [pkRow] = await this.#bulkWrite(table, [record], pkCol, 1, { conflictKeys, keepAsIs: conflictKeys });
+        return pkRow;
+    }
+    /**
+     * Group records by their exact field set, keeping each record's input position. A bulk write
+     * is N single writes issued efficiently (ADR 0003), so every record writes only its own
+     * fields: records with different fields cannot share a statement, or a field missing from
+     * the statement is dropped and a field missing from the record is bound as NULL — which
+     * skips the column default on insert and overwrites the stored value on upsert.
+     */
+    #groupByFields(records) {
+        const groups = new Map();
+        records.forEach((record, i) => {
+            const fields = Object.keys(record);
+            const key = JSON.stringify([...fields].sort());
+            const group = groups.get(key);
+            if (group)
+                group.indexes.push(i);
+            else
+                groups.set(key, { fields, indexes: [i] });
+        });
+        return [...groups.values()];
+    }
+    /**
+     * Rows found by each record's key, keyed by the record's position. One statement for the
+     * whole chunk: a `UNION ALL` part per record, each row tagged with its position, so the order
+     * the database returns them in does not matter and value comparison stays the database's
+     * (types, collations). Records whose key holds a null are not looked up: NULL never matches.
+     */
+    async #findByKey(table, records, pkCol, keys) {
+        const found = new Map();
+        const values = [];
+        const position = this.dialect.qi(LOOKUP_POSITION);
+        const from = `${this.#quotedPkCols(pkCol)} FROM ${this.dialect.qi(table)}`;
+        const lookups = records.flatMap((record, i) => {
+            if (keys.some((k) => record[k] == null))
+                return [];
+            const where = this.#equalities(Object.fromEntries(keys.map((k) => [k, record[k]])), values, ' AND ');
+            return [`SELECT ${i} AS ${position}, ${from} WHERE ${where}`];
+        });
+        if (!lookups.length)
+            return found;
+        const result = await this.query(lookups.join(' UNION ALL '), values);
+        for (const { [LOOKUP_POSITION]: i, ...pk } of result.rows) {
+            found.set(Number(i), [...(found.get(Number(i)) ?? []), pk]);
+        }
+        for (const rows of found.values()) {
+            if (rows.length > 1) {
+                throw new Error(`An upsert key (${keys.join(', ')}) of "${table}" matches several rows: it is not unique ` +
+                    `in the database — nothing was written (ADR 0021)`);
+            }
+        }
+        return found;
+    }
+    /**
+     * PK rows for postgres upsert records that update nothing on conflict: `DO NOTHING` returns no
+     * row for an existing one. The record gives its PK when it holds every PK column; otherwise
+     * the row — inserted or untouched — is looked up by its conflict keys.
+     */
+    async #untouchedPkRows(table, records, pkCol, conflictKeys) {
+        const pkCols = Array.isArray(pkCol) ? pkCol : [pkCol];
+        const holdsPk = (record) => pkCols.every((c) => record[c] != null && !(record[c] instanceof Expression));
+        const found = await this.#findByKey(table, records.map((r) => (holdsPk(r) ? {} : r)), pkCol, conflictKeys);
+        return records.map((record, i) => {
+            if (holdsPk(record))
+                return Object.fromEntries(pkCols.map((c) => [c, record[c]]));
+            const [row] = found.get(i) ?? [];
+            if (!row) {
+                throw new Error(`Cannot resolve the primary key of an upserted "${table}" row: no row matches its conflict keys (${conflictKeys.join(', ')})`);
+            }
+            return row;
+        });
+    }
+    /**
+     * One multi-row INSERT for records sharing `fields`; `tail` is the upsert clause, if any.
+     * Returns the PK rows in the records' order.
+     */
+    async #insertRows(table, fields, records, pkCol, tail = '') {
+        const { values, rows } = this.#bulkValues(fields, records);
         const result = await this.query(`${this.#insertHead(table, fields)}
-       VALUES (${placeholders.join(', ')})
-       ${upsertClause}${returning}`, values);
-        return this.#extractPkRows(result, pkCol, [record])[0];
+       VALUES ${rows}
+       ${tail}${this.dialect.returningPk(this.#quotedPkCols(pkCol))}`, values);
+        return this.#extractPkRows(result, pkCol, records);
+    }
+    /**
+     * Update existing rows by their key in one statement: each column takes a `CASE` over the
+     * keys, and the WHERE names the same keys, so a row can only be reached through its own key.
+     * Every row must be matched: one deleted since it was read is an error, never a skipped write.
+     */
+    async #updateByKey(table, columns, records, keys) {
+        const values = [];
+        const match = (record) => `(${this.#equalities(Object.fromEntries(keys.map((k) => [k, record[k]])), values, ' AND ')})`;
+        const set = columns.map((col) => {
+            const cases = records.map((r) => `WHEN ${match(r)} THEN ${this.#bind(r[col], values)}`);
+            return `${this.dialect.qi(col)} = CASE ${cases.join(' ')} END`;
+        });
+        const where = records.map(match).join(' OR ');
+        const result = await this.query(`UPDATE ${this.dialect.qi(table)} SET ${set.join(', ')} WHERE ${where}`, values);
+        if (result.affectedRows !== records.length) {
+            throw new Error(`Upsert on "${table}": ${records.length - result.affectedRows} of ${records.length} rows ` +
+                `to update were not found — deleted after the upsert read them`);
+        }
+    }
+    /**
+     * Upsert by key for dialects whose upsert syntax names no conflict target (mysql/mariadb,
+     * ADR 0021): probe which keys exist, insert the rest, update the found rows by their key.
+     * Only the row the key names can be written — a collision on another unique index is an
+     * error, as it is on postgres. PKs come from the probe and from the insert.
+     */
+    async #upsertByKey(table, fields, records, pkCol, upsert) {
+        // A group missing a key field can only insert: nothing to probe
+        const found = upsert.conflictKeys.every((k) => fields.includes(k))
+            ? await this.#findByKey(table, records, pkCol, upsert.conflictKeys)
+            : new Map();
+        const pkRows = new Array(records.length);
+        const inserts = records.flatMap((_, i) => (found.has(i) ? [] : [i]));
+        if (inserts.length) {
+            const inserted = await this.#insertRows(table, fields, inserts.map((i) => records[i]), pkCol);
+            inserts.forEach((i, k) => { pkRows[i] = inserted[k]; });
+        }
+        const updates = [...found.keys()];
+        const columns = fields.filter((f) => !upsert.keepAsIs.includes(f));
+        if (updates.length && columns.length) {
+            await this.#updateByKey(table, columns, updates.map((i) => records[i]), upsert.conflictKeys);
+        }
+        for (const i of updates)
+            pkRows[i] = found.get(i)[0];
+        return pkRows;
+    }
+    /**
+     * One chunk of records sharing `fields`: a plain insert, or an upsert — `ON CONFLICT (key)`
+     * where the dialect has it, by key otherwise. PK rows in the records' order.
+     */
+    async #writeChunk(table, fields, records, pkCol, upsert) {
+        if (!upsert)
+            return this.#insertRows(table, fields, records, pkCol);
+        const onConflict = this.dialect.onConflict;
+        if (!onConflict)
+            return this.#upsertByKey(table, fields, records, pkCol, upsert);
+        const updateSet = onConflict.updateSet(fields, upsert.keepAsIs);
+        const pkRows = await this.#insertRows(table, fields, records, pkCol, onConflict.sql(this.#q(upsert.conflictKeys), updateSet));
+        // Nothing to update: `DO NOTHING` returns no row for an existing one. A group missing a key
+        // field can only insert, and RETURNING names every row it inserted.
+        if (!updateSet && upsert.conflictKeys.every((k) => fields.includes(k))) {
+            return this.#untouchedPkRows(table, records, pkCol, upsert.conflictKeys);
+        }
+        return pkRows;
+    }
+    /**
+     * Write `records`, one chunk at a time within each same-fields group (a single chunk when
+     * every record has the same fields). With `upsert`, an existing row gets the record's fields
+     * except `keepAsIs` — the conflict keys and the columns never overwritten. PK rows are
+     * returned in input order.
+     */
+    async #bulkWrite(table, records, pkCol, chunkSize, upsert) {
+        const results = new Array(records.length);
+        for (const { fields, indexes } of this.#groupByFields(records)) {
+            for (let i = 0; i < indexes.length; i += chunkSize) {
+                const chunkIndexes = indexes.slice(i, i + chunkSize);
+                const pkRows = await this.#writeChunk(table, fields, chunkIndexes.map((j) => records[j]), pkCol, upsert);
+                pkRows.forEach((row, k) => {
+                    results[chunkIndexes[k]] = row;
+                });
+            }
+        }
+        return results;
     }
     async bulkInsert(table, records, pkCol, chunkSize = DEFAULT_CHUNK_SIZE) {
         if (!records.length)
             return [];
-        const fields = Object.keys(records[0]);
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
-        const results = [];
-        for (let i = 0; i < records.length; i += chunkSize) {
-            const chunk = records.slice(i, i + chunkSize);
-            const { values, rows } = this.#bulkValues(fields, chunk);
-            const result = await this.query(`${this.#insertHead(table, fields)} VALUES ${rows}${returning}`, values);
-            results.push(...this.#extractPkRows(result, pkCol, chunk));
-        }
-        return results;
+        return this.#bulkWrite(table, records, pkCol, chunkSize);
     }
     /**
      * `immutableCols` are written when the row is inserted but left untouched when the statement
@@ -203,34 +349,18 @@ export class QueryClient {
     async bulkInsertOrUpdate(table, records, conflictKeys, pkCol, chunkSize = DEFAULT_CHUNK_SIZE, immutableCols = []) {
         if (!records.length)
             return [];
-        const fields = Object.keys(records[0]);
         const keepAsIs = immutableCols.length ? [...conflictKeys, ...immutableCols] : conflictKeys;
-        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, keepAsIs));
-        const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
-        const results = [];
-        for (let i = 0; i < records.length; i += chunkSize) {
-            const chunk = records.slice(i, i + chunkSize);
-            const { values, rows } = this.#bulkValues(fields, chunk);
-            const result = await this.query(`${this.#insertHead(table, fields)}
-         VALUES ${rows}
-         ${upsertClause}${returning}`, values);
-            results.push(...this.#extractPkRows(result, pkCol, chunk));
-        }
-        return results;
+        return this.#bulkWrite(table, records, pkCol, chunkSize, { conflictKeys, keepAsIs });
     }
     async update(table, record, where, extraCondition) {
         const values = [];
-        const { fields: setF, placeholders: setP } = this.#params(record, values);
-        const { fields: whereF, placeholders: whereP } = this.#params(where, values);
+        const setClause = this.#equalities(record, values, ', ');
+        const whereClause = this.#equalities(where, values, ' AND ');
         let extraWhere = '';
         if (extraCondition) {
             extraWhere = ` AND ${extraCondition.build(values.length + 1, this.dialect.ph)}`;
             values.push(...extraCondition.getValues());
         }
-        const setClause = setF.map((f, i) => `${this.dialect.qi(f)} = ${setP[i]}`).join(', ');
-        const whereClause = whereF
-            .map((f, i) => `${this.dialect.qi(f)} = ${whereP[i]}`)
-            .join(' AND ');
         const result = await this.query(`UPDATE ${this.dialect.qi(table)}
        SET ${setClause}
        WHERE ${whereClause}${extraWhere}`, values);
@@ -238,15 +368,12 @@ export class QueryClient {
     }
     async delete(table, where, extraCondition) {
         const values = [];
-        const { fields, placeholders } = this.#params(where, values);
+        const whereClause = this.#equalities(where, values, ' AND ');
         let extraWhere = '';
         if (extraCondition) {
             extraWhere = ` AND ${extraCondition.build(values.length + 1, this.dialect.ph)}`;
             values.push(...extraCondition.getValues());
         }
-        const whereClause = fields
-            .map((f, i) => `${this.dialect.qi(f)} = ${placeholders[i]}`)
-            .join(' AND ');
         const result = await this.query(`DELETE FROM ${this.dialect.qi(table)}
        WHERE ${whereClause}${extraWhere}`, values);
         return result.affectedRows;

package/dist/lib/dialect.d.ts

@@ -9,18 +9,23 @@ export interface SqlDialect {
     /** ConditionBuilder dialect name */
     cbDialect: 'postgres' | 'mysql';
     supportsReturning: boolean;
-    /** ON CONFLICT / ON DUPLICATE KEY syntax */
-    upsertSql(quotedConflictKeys: string, quotedUpdateSet: string): string;
-    /** RETURNING pk_col suffix or empty string */
-    returningPk(quotedPkCol: string): string;
     /**
-     * Build the SET body for an upsert: the column list (separated by ', ') that the dialect
-     * uses to copy "incoming row" values into a conflicting row.
-     * - postgres: `"col" = EXCLUDED."col"`
-     * - mysql/mariadb: `` `col` = VALUES(`col`) ``
-     * Returns '' when there is nothing to update (i.e. all `fields` are conflict keys).
+     * The upsert clause of a dialect whose syntax names its conflict target — postgres
+     * `ON CONFLICT (key)`, which matches exactly the declared key. Absent on mysql/mariadb:
+     * `ON DUPLICATE KEY UPDATE` fires on ANY unique index, so there the QueryClient upserts by
+     * key explicitly — probe, insert, update (ADR 0021).
      */
-    upsertUpdateSet(fields: string[], conflictKeys: string[]): string;
+    onConflict?: {
+        /** `ON CONFLICT (keys) DO UPDATE SET …`, or `DO NOTHING` when the update set is empty. */
+        sql(quotedConflictKeys: string, quotedUpdateSet: string): string;
+        /**
+         * The SET body copying the incoming row into the conflicting one (`"col" = EXCLUDED."col"`)
+         * for every field not in `keepAsIs`; '' when nothing is left to update.
+         */
+        updateSet(fields: string[], keepAsIs: string[]): string;
+    };
+    /** RETURNING pk_col suffix or empty string */
+    returningPk(quotedPkCol: string): string;
     /**
      * Truncate a timestamp/date column to the start of the given unit and
      * return it as an ISO-style string. The output is always a STRING:

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

@@ -1 +1 @@
-{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/lib/dialect.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,KAAK,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,gEAAgE;IAChE,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,oCAAoC;IACpC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4CAA4C;IAC5C,SAAS,CAAC,kBAAkB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;IACvE,8CAA8C;IAC9C,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAClE;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7D;AAqFD,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIxD"}
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/lib/dialect.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,KAAK,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;AAElE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,gEAAgE;IAChE,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1B,oCAAoC;IACpC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;IAChC,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QACX,0FAA0F;QAC1F,GAAG,CAAC,kBAAkB,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC;QACjE;;;WAGG;QACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;KACzD,CAAC;IACF,8CAA8C;IAC9C,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC;IACzC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7D;AAsED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CAIxD"}

package/dist/lib/dialect.js

@@ -1,19 +1,20 @@
+const pgQi = (id) => `"${id.replace(/"/g, '""')}"`;
 const PostgresDialect = {
     name: 'postgres',
-    qi: (id) => `"${id.replace(/"/g, '""')}"`,
+    qi: pgQi,
     ph: (i) => `$${i}`,
     cbDialect: 'postgres',
     supportsReturning: true,
-    upsertSql(quotedConflictKeys, quotedUpdateSet) {
-        if (!quotedUpdateSet)
-            return `ON CONFLICT (${quotedConflictKeys}) DO NOTHING`;
-        return `ON CONFLICT (${quotedConflictKeys}) DO UPDATE SET ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet(fields, conflictKeys) {
-        const updateCols = fields.filter((f) => !conflictKeys.includes(f));
-        if (!updateCols.length)
-            return '';
-        return updateCols.map((f) => `${this.qi(f)} = EXCLUDED.${this.qi(f)}`).join(', ');
+    onConflict: {
+        sql(quotedConflictKeys, quotedUpdateSet) {
+            if (!quotedUpdateSet)
+                return `ON CONFLICT (${quotedConflictKeys}) DO NOTHING`;
+            return `ON CONFLICT (${quotedConflictKeys}) DO UPDATE SET ${quotedUpdateSet}`;
+        },
+        updateSet(fields, keepAsIs) {
+            const updateCols = fields.filter((f) => !keepAsIs.includes(f));
+            return updateCols.map((f) => `${pgQi(f)} = EXCLUDED.${pgQi(f)}`).join(', ');
+        },
     },
     returningPk(quotedPkCol) {
         return ` RETURNING ${quotedPkCol}`;
@@ -33,26 +34,12 @@ function mysqlDateTrunc(unit, col) {
         case 'hour': return `DATE_FORMAT(${col}, '%Y-%m-%dT%H:00:00')`;
     }
 }
-function mysqlUpsertUpdateSet(fields, conflictKeys) {
-    const updateCols = fields.filter((f) => !conflictKeys.includes(f));
-    if (!updateCols.length)
-        return '';
-    return updateCols.map((f) => `${this.qi(f)} = VALUES(${this.qi(f)})`).join(', ');
-}
 const MysqlDialect = {
     name: 'mysql',
     qi: (id) => `\`${id.replace(/`/g, '``')}\``,
     ph: () => '?',
     cbDialect: 'mysql',
     supportsReturning: false,
-    upsertSql(_quotedConflictKeys, quotedUpdateSet) {
-        // MySQL requires at least one assignment in ON DUPLICATE KEY UPDATE; when there's nothing
-        // user-meaningful to update, assign the first conflict key to itself (no-op).
-        if (!quotedUpdateSet)
-            return `ON DUPLICATE KEY UPDATE ${_quotedConflictKeys.split(', ')[0]} = ${_quotedConflictKeys.split(', ')[0]}`;
-        return `ON DUPLICATE KEY UPDATE ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet: mysqlUpsertUpdateSet,
     returningPk() {
         return '';
     },
@@ -64,12 +51,6 @@ const MariadbDialect = {
     ph: () => '?',
     cbDialect: 'mysql',
     supportsReturning: true,
-    upsertSql(_quotedConflictKeys, quotedUpdateSet) {
-        if (!quotedUpdateSet)
-            return `ON DUPLICATE KEY UPDATE ${_quotedConflictKeys.split(', ')[0]} = ${_quotedConflictKeys.split(', ')[0]}`;
-        return `ON DUPLICATE KEY UPDATE ${quotedUpdateSet}`;
-    },
-    upsertUpdateSet: mysqlUpsertUpdateSet,
     returningPk(quotedPkCol) {
         return ` RETURNING ${quotedPkCol}`;
     },

package/dist/lib/engine/bulk/bulk-upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AA+D3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}
+{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAgE3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}

package/dist/lib/engine/bulk/bulk-upsert.js

@@ -1,5 +1,5 @@
 import { camelcaseObject } from '../../naming.js';
-import { processSecondaries, processDeletions, prepareInsertRecord } from '../write-helpers.js';
+import { processSecondaries, processDeletions, prepareInsertRecord, assertUpsertKeys, } from '../write-helpers.js';
 import { enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../../tenant.js';
 import { runBulkValidation } from '../validate.js';
 import { primaryAsCols } from '../../../types.js';
@@ -12,6 +12,7 @@ function upsertMains(params, preparedMains, pkCol) {
         return db.bulkInsert(schema.tableName, preparedMains, pkCol);
     }
     const conflictCols = upsertKeys.map((k) => schema.col(k));
+    assertUpsertKeys(schema, conflictCols, [pkCol].flat(), preparedMains);
     // Tenant isolation: a conflicting upsert must not overwrite rows owned by another tenant, nor
     // re-assign the owner of a row it legitimately updates.
     return assertTenantOwnsConflicts(db, tenant, schema.tableName, conflictCols, preparedMains)

package/dist/lib/engine/rest/insert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAmE9E"}
+{"version":3,"file":"insert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/insert.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAEb,MAAM,mBAAmB,CAAC;AAE3B,wBAAsB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAoE9E"}

package/dist/lib/engine/rest/insert.js

@@ -1,5 +1,5 @@
 import { camelcaseObject } from '../../naming.js';
-import { processSecondaries, prepareInsertRecord } from '../write-helpers.js';
+import { processSecondaries, prepareInsertRecord, assertUpsertKeys } from '../write-helpers.js';
 import { enforceTenantOnWrites, assertTenantOwnsConflicts } from '../../tenant.js';
 import { primaryAsCols } from '../../../types.js';
 export async function insertEngine(params) {
@@ -20,6 +20,7 @@ export async function insertEngine(params) {
         const upsertKeys = tableConf.upsertMap?.get(schema);
         if (upsertKeys) {
             const conflictCols = upsertKeys.map((k) => schema.col(k));
+            assertUpsertKeys(schema, conflictCols, [pkCol].flat(), [mainRecord]);
             // Tenant isolation: a conflicting upsert must not overwrite a row owned by another tenant.
             await assertTenantOwnsConflicts(tx, tenant, schema.tableName, conflictCols, [mainRecord]);
             pkResult = await tx.insertOrUpdate(schema.tableName, mainRecord, conflictCols, pkCol);

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