turbine-orm 0.80.0 → 0.81.0

package/dist/powql.d.ts

@@ -889,19 +889,22 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
     }>;
     upsert(args: UpsertArgs<T>): Promise<T>;
     /**
-     * Upsert as a reselect-or-write inside one flat transaction, for every shape
-     * the native `upsert … on .col` statement cannot express: a conflict target
-     * other than a single-column primary key (it takes one column and PowDB has
-     * no composite unique), and a table under a global filter (its conflict
-     * branch takes no predicate). PowDB's single writer makes the read-then-write
-     * safe from concurrent writers; the transaction makes it atomic with the
-     * write.
-     *
-     * The row is looked up by the conflict columns with `create`'s values for
-     * them, which is what `ON CONFLICT (<cols>)` compares on the SQL engines. The
-     * find and the update run through the transaction's table interface, so a
-     * configured global filter applies to both exactly as it does to any other
-     * read or write, and `skipGlobalFilters` is forwarded to both.
+     * `upsert` as Prisma defines it, for every shape the native `upsert … on`
+     * statement cannot express: find the row `where` names, update it if it
+     * exists, else insert `create`, in one flat transaction. PowDB's single
+     * writer makes the read-then-write safe from concurrent writers; the
+     * transaction makes it atomic with the write.
+     *
+     * The lookup is by `where`'s own values. It used to be by `create`'s values
+     * for the conflict columns, which is what the native statement compares, and
+     * so answered a different question whenever the two disagreed: `where: { id }`
+     * with a `create` that leaves the key to the engine inserted a new row every
+     * time. The find and the update run through the transaction's table
+     * interface, so a configured global filter applies to both exactly as it does
+     * to any other read or write, and `skipGlobalFilters` is forwarded to both.
+     *
+     * Both halves are compiled before the lookup, so an unknown field in `update`
+     * is refused whether or not the row exists (the SQL engines do the same).
      */
     private upsertLookupFirst;
     count(args?: CountArgs<T>): Promise<number>;

package/dist/powql.js

@@ -37,10 +37,10 @@
 import { randomUUID } from 'node:crypto';
 import { guardCheckout } from './connection-guard.js';
 import { NotFoundError, OptimisticLockError, ReadOnlyError, TimeoutError, UnsupportedFeatureError, ValidationError, } from './errors.js';
-import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
+import { executeNestedCreate, executeNestedUpdate, extractRelationFields, hasRelationFields, } from './nested-write.js';
 import { ALL_POWDB_CAPABILITIES, atLeastVersion, baseTsType, coerceNativeValue, isJsonColumn, isPowdbDatetimeColumn, isStaleFramePowdbError, PowdbFloatParam, PowdbJsonParam, parsePowdbSemver, powqlColumnType, quotePowqlDotted, quotePowqlIdent, requireCapability, rowToEntity, } from './powdb-shared.js';
 import { assertAggregatePiiOptIn } from './query/aggregates.js';
-import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, } from './query/compound-unique.js';
+import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, upsertWhereMatchesCreate, } from './query/compound-unique.js';
 import { ARRAY_OPERATOR_KEYS, isJsonFilter, isRelationPickOrderBy, orderByEntries } from './query/filters.js';
 import { warnUnknownQueryOptions } from './query/option-surface.js';
 import { applyStableRelationOrderTo, normalizeWithClause } from './query/relation-names.js';
@@ -2665,7 +2665,7 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (resolveRelationDef(this.meta.relations, field)) {
-                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not createMany()/upsert()`);
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update()/upsert(), not createMany()`);
             }
             out.push({ col: this.column(field), value });
         }
@@ -2864,7 +2864,7 @@ export class PowqlInterface {
             if (value === undefined)
                 continue;
             if (resolveRelationDef(this.meta.relations, field)) {
-                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update(), not updateMany()/upsert()`);
+                throw new UnsupportedFeatureError('nested writes', 'PowDB', `relation "${field}", nested writes need create()/update()/upsert(), not updateMany()`);
             }
             const colMeta = this.column(field);
             const ref = this.ref(field);
@@ -3031,46 +3031,47 @@ export class PowqlInterface {
             const plan = this.writeReturnPlan(args);
             const createData = this.applyPkDefault(args.create);
             const pkCol = this.meta.primaryKey[0];
-            // The conflict target is the columns `where` names, as on the SQL
-            // engines (`ON CONFLICT (<where keys>)`), with the conflicting VALUES
-            // taken from `create`. This path used to conflict on the primary key
-            // whatever `where` named, so an upsert keyed on another unique column
-            // (`where: { email }`) never found the existing row.
             const conflictColumns = Object.keys(upsertWhere)
                 .filter((k) => upsertWhere[k] !== undefined)
                 .map((k) => this.column(k).name);
+            const updateData = (args.update ?? {});
             // PowQL's native `upsert … on .col` expresses exactly one shape: a single
-            // conflict column that is the primary key, with no predicate on its
-            // conflict branch. Everything else is an atomic reselect-or-write
-            // transaction.
+            // conflict column that is the primary key, pinned to the value `create`
+            // inserts, with a non-empty update and no predicate on its conflict
+            // branch. Every other shape looks the row up by `where` first, in one
+            // transaction, which is what the SQL engines do for the same shapes and
+            // what the call means (query/compound-unique.ts upsertWhereMatchesCreate).
             //
             // That includes a table under a global filter. The native statement's
             // `on conflict` branch carries no predicate, so a tenant-scoped client
             // whose `create` key matched ANOTHER tenant's row updated that row, and
             // the tenant-filtered reselect then reported the write it had just made
-            // as a NotFoundError. The SQL engines guard the same branch with the
-            // filter (`DO UPDATE … WHERE tenant_id = $n`). The lookup-first path runs
-            // its find and its update through the filtered interface, so another
-            // tenant's row is invisible to it: the insert then collides on the key
-            // and fails, as it does on the SQL engines, and nothing is overwritten.
+            // as a NotFoundError. The lookup runs its find and its update through the
+            // filtered interface, so another tenant's row is invisible to it: the
+            // insert then collides on the key and fails, and nothing is overwritten.
             const filtered = this.applyGlobalFilter('', [], args.skipGlobalFilters) !== '';
             const native = this.meta.primaryKey.length === 1 &&
                 pkCol !== undefined &&
                 conflictColumns.length === 1 &&
                 conflictColumns[0] === pkCol &&
+                upsertWhereMatchesCreate(this.meta, upsertWhere, (args.create ?? {})) &&
+                !hasRelationFields(args.create, this.meta) &&
+                !hasRelationFields(updateData, this.meta) &&
+                Object.values(updateData).some((v) => v !== undefined) &&
                 !filtered;
             if (!native) {
-                return this.upsertLookupFirst(createData, args.update, conflictColumns, {
+                return this.upsertLookupFirst(upsertWhere, createData, updateData, {
                     select: args.select,
                     omit: args.omit,
                     skipGlobalFilters: args.skipGlobalFilters,
+                    timeout: args.timeout,
                 });
             }
             const params = [];
             const createBody = this.scalarData(createData)
                 .map((a) => `${quotePowqlIdent(a.col.name)} := ${this.writeRef(a.value, a.col, params)}`)
                 .join(', ');
-            const updateBody = this.buildUpdateAssignments(args.update, params);
+            const updateBody = this.buildUpdateAssignments(updateData, params);
             // PowDB 0.7.0's `upsert` statement does NOT accept a trailing `returning`
             // (verified: "unexpected trailing token … 'returning'"), because it is one
             // atomic insert-or-update, not two branches. So upsert alone keeps the
@@ -3090,48 +3091,42 @@ export class PowqlInterface {
         });
     }
     /**
-     * Upsert as a reselect-or-write inside one flat transaction, for every shape
-     * the native `upsert … on .col` statement cannot express: a conflict target
-     * other than a single-column primary key (it takes one column and PowDB has
-     * no composite unique), and a table under a global filter (its conflict
-     * branch takes no predicate). PowDB's single writer makes the read-then-write
-     * safe from concurrent writers; the transaction makes it atomic with the
-     * write.
+     * `upsert` as Prisma defines it, for every shape the native `upsert … on`
+     * statement cannot express: find the row `where` names, update it if it
+     * exists, else insert `create`, in one flat transaction. PowDB's single
+     * writer makes the read-then-write safe from concurrent writers; the
+     * transaction makes it atomic with the write.
      *
-     * The row is looked up by the conflict columns with `create`'s values for
-     * them, which is what `ON CONFLICT (<cols>)` compares on the SQL engines. The
-     * find and the update run through the transaction's table interface, so a
-     * configured global filter applies to both exactly as it does to any other
-     * read or write, and `skipGlobalFilters` is forwarded to both.
-     */
-    async upsertLookupFirst(createData, updateData, conflictColumns, shape) {
-        const { skipGlobalFilters, ...projection } = shape;
+     * The lookup is by `where`'s own values. It used to be by `create`'s values
+     * for the conflict columns, which is what the native statement compares, and
+     * so answered a different question whenever the two disagreed: `where: { id }`
+     * with a `create` that leaves the key to the engine inserted a new row every
+     * time. The find and the update run through the transaction's table
+     * interface, so a configured global filter applies to both exactly as it does
+     * to any other read or write, and `skipGlobalFilters` is forwarded to both.
+     *
+     * Both halves are compiled before the lookup, so an unknown field in `update`
+     * is refused whether or not the row exists (the SQL engines do the same).
+     */
+    async upsertLookupFirst(where, createData, updateData, shape) {
+        const { skipGlobalFilters, timeout, ...projection } = shape;
         const skip = skipGlobalFilters === undefined ? {} : { skipGlobalFilters };
-        // Accept either the camelCase field or the snake_case column in `create`
-        // (create() resolves both), and key the where by field name.
-        const keyPairs = conflictColumns.map((col) => {
-            const field = this.meta.reverseColumnMap[col] ?? col;
-            return { field, value: createData[field] ?? createData[col] };
-        });
-        const keyless = keyPairs.some((p) => p.value == null);
-        const isCompositePk = keyPairs.length > 1 &&
-            keyPairs.length === this.meta.primaryKey.length &&
-            conflictColumns.every((c) => this.meta.primaryKey.includes(c));
-        if (keyless && isCompositePk) {
-            throw new ValidationError(`upsert on "${this.table}" needs every composite-PK field in \`create\` (${keyPairs
-                .map((p) => p.field)
-                .join(', ')}).`);
-        }
-        const keyWhere = Object.fromEntries(keyPairs.map((p) => [p.field, p.value]));
+        const time = timeout === undefined ? {} : { timeout };
+        this.scalarData(extractRelationFields(createData, this.meta).scalars);
+        const scalarUpdate = extractRelationFields(updateData, this.meta).scalars;
+        if (Object.values(scalarUpdate).some((v) => v !== undefined))
+            this.buildUpdateAssignments(scalarUpdate, []);
+        const updateIsEmpty = Object.values(updateData).every((v) => v === undefined);
         const run = async (ctx) => {
             const tbl = ctx.tx.table(this.table);
-            // A row whose `create` leaves a conflict column unset cannot collide on
-            // it (NULL never equals NULL in a unique index, and a server-assigned key
-            // is new), which is what `ON CONFLICT` concludes on the SQL engines too.
-            const existing = keyless ? null : await tbl.findUnique({ where: keyWhere, ...skip });
-            return existing
-                ? (await tbl.update({ where: keyWhere, data: updateData, ...projection, ...skip }))
-                : (await tbl.create({ data: createData, ...projection }));
+            const existing = await tbl.findUnique({ where, ...projection, ...skip, ...time });
+            if (existing) {
+                // An empty `update` means "leave it as it is": the row found is the answer.
+                if (updateIsEmpty)
+                    return existing;
+                return (await tbl.update({ where, data: updateData, ...projection, ...skip, ...time }));
+            }
+            return (await tbl.create({ data: createData, ...projection, ...time }));
         };
         return this.isTxScoped() ? run(this.buildNestedCtx()) : this.runInImplicitTx(run);
     }

package/dist/prisma-compat.d.ts

@@ -159,6 +159,8 @@ export interface CompatQueryInterface {
         count: number;
     }>;
     buildUpsert(args: Record<string, unknown>): DeferredQuery<unknown>;
+    /** Whether `upsert()` will look the row up first (and `buildUpsert` refuse). Absent on PowDB. */
+    upsertNeedsLookup?(args: Record<string, unknown>): boolean;
     buildCount(args?: Record<string, unknown>): DeferredQuery<number>;
     buildAggregate(args: Record<string, unknown>): DeferredQuery<unknown>;
     buildGroupBy(args: Record<string, unknown>): DeferredQuery<unknown[]>;

package/dist/prisma-compat.js

@@ -1738,53 +1738,6 @@ function hasNestedKeys(ctx, mm, data) {
         return v !== null && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date);
     });
 }
-/**
- * Whether an upsert's translated `where` key values all equal the
- * corresponding `create` values. When they do (the common Prisma idiom), the
- * native single-statement ON CONFLICT upsert is semantically identical to
- * Prisma's lookup-first and stays atomic. When they differ, native upsert
- * would insert the `create` row even though the `where` row exists, so the
- * adapter must emulate lookup-first instead.
- */
-function upsertKeysMatch(t) {
-    const where = t.where;
-    const create = t.create;
-    if (!isPlainObject(where) || !isPlainObject(create))
-        return false;
-    const scalarEq = (a, b) => {
-        if (a instanceof Date || b instanceof Date) {
-            return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
-        }
-        return a === b;
-    };
-    for (const [k, v] of Object.entries(where)) {
-        if (v !== null && typeof v === 'object' && !(v instanceof Date)) {
-            // Compound-unique selector object: every member must scalar-match create.
-            if (Array.isArray(v))
-                return false;
-            for (const [mk, mv] of Object.entries(v)) {
-                if (mv !== null && typeof mv === 'object' && !(mv instanceof Date))
-                    return false;
-                if (!scalarEq(mv, create[mk]))
-                    return false;
-            }
-            continue;
-        }
-        if (!scalarEq(v, create[k]))
-            return false;
-    }
-    return true;
-}
-/** Prisma upsert semantics: look up by where; update the found row, else insert create. */
-async function upsertLookupFirst(qi, t) {
-    const existing = await qi.findUnique({ where: t.where });
-    // The projection rides along so both branches return what the native upsert
-    // path returns (an explicitly selected PII field included).
-    const shape = { select: t.select, omit: t.omit };
-    if (existing)
-        return qi.update({ where: t.where, data: t.update, ...shape });
-    return qi.create({ data: t.create, ...shape });
-}
 /**
  * The row shapes a translated `createMany` has to insert, as contiguous runs
  * that each name the same fields (see {@link createManyShapeRuns}).
@@ -1846,7 +1799,7 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                 reshape: batch.reshape,
                 nested: () => {
                     try {
-                        return batch.nested?.(translate()) ?? false;
+                        return batch.nested?.(translate(), getQI()) ?? false;
                     }
                     catch {
                         return false; // let the build path surface the translation error consistently
@@ -2008,24 +1961,17 @@ function makeDelegate(ctx, mm, getQI, runInTx) {
                 };
                 applyNativeOptions(UPSERT_OPTIONS, a, t);
                 return t;
-            }, (qi, t) => {
-                // Native ON CONFLICT upsert is only Prisma-equivalent when the where
-                // key values equal the create values AND no nested write data is
-                // present; otherwise emulate Prisma's lookup-first atomically.
-                if (upsertKeysMatch(t) && !hasNestedKeys(ctx, mm, t.create) && !hasNestedKeys(ctx, mm, t.update)) {
-                    return qi.upsert(t).then(shape);
-                }
-                return runInTx(async (table) => shape(await upsertLookupFirst(table(mm.table), t)));
-            }, {
+            }, 
+            // Core `upsert` has Prisma's semantics itself (it looks the row up by
+            // `where` whenever one conflict statement would mean something else,
+            // and runs nested writes), so the adapter passes it straight through.
+            (qi, t) => qi.upsert(t).then(shape), {
                 build: (qi, t) => qi.buildUpsert(t),
                 reshape: shape,
-                nested: (t) => !upsertKeysMatch(t) || hasNestedKeys(ctx, mm, t.create) || hasNestedKeys(ctx, mm, t.update),
-                execInTx: async (table, t) => {
-                    if (upsertKeysMatch(t) && !hasNestedKeys(ctx, mm, t.create) && !hasNestedKeys(ctx, mm, t.update)) {
-                        return shape(await table(mm.table).upsert(t));
-                    }
-                    return shape(await upsertLookupFirst(table(mm.table), t));
-                },
+                // Batchable only when core would run it as one statement. PowDB has
+                // no deferred statements at all, so it always takes the tx path.
+                nested: (t, qi) => qi.upsertNeedsLookup?.(t) ?? true,
+                execInTx: async (table, t) => shape(await table(mm.table).upsert(t)),
             });
         },
         count: (args = {}) => defer('count', args, () => {

package/dist/query/builder.d.ts

@@ -1283,6 +1283,35 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private makeTxProxy;
     delete<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: DeleteArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
     upsert<S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined>(args: UpsertArgs<T, R, S, O>): Promise<FieldResult<T, S, O>>;
+    /**
+     * @internal Whether `upsert()` looks the row up rather than running one
+     * statement, which is also exactly when `buildUpsert` refuses these args.
+     * prisma-compat reads it to decide whether an array `$transaction` can batch
+     * an upsert or has to run the array inside a transaction.
+     */
+    upsertNeedsLookup(args: UpsertArgs<T, R, Record<string, boolean> | undefined, Record<string, boolean> | undefined>): boolean;
+    /**
+     * `upsert` as Prisma defines it: find the row `where` names, update it if it
+     * exists, else insert `create`, in one transaction (the caller's, when there
+     * is one). Taken whenever the single conflict statement would mean something
+     * else (`upsertLookupReason`: `where` not pinned to `create`'s values, an
+     * empty `update`, a global filter the engine's statement cannot carry) and
+     * whenever `create` or `update` holds nested relation writes, which only the
+     * nested-write engine can run.
+     *
+     * Validation is DATA-INDEPENDENT, as it is for the batched relation loader:
+     * both halves are compiled before the lookup runs, so an unknown field in
+     * `update` is refused whether or not the row exists, and a call is never
+     * valid on one row and invalid on the next. Only the scalar part of each half
+     * is compiled here; nested relation writes are validated by the engine that
+     * runs them.
+     *
+     * Not atomic against a concurrent insert of the same key, exactly as Prisma's
+     * own lookup is not: two callers can both miss, and the second insert then
+     * fails on the unique constraint (E008) when `create` carries the key. It
+     * never writes two rows over one key the database enforces.
+     */
+    private upsertLookupFirst;
     updateMany(args: UpdateManyArgs<T, R>): Promise<{
         count: number;
     }>;

package/dist/query/builder.js

@@ -15,11 +15,11 @@ import { settleEventLoop } from '../connection-guard.js';
 import { postgresDialect } from '../dialect.js';
 import { explainConnectionLoss, isStaleConnectionError, NotFoundError, TimeoutError, UnsupportedFeatureError, ValidationError, wrapPgError, } from '../errors.js';
 import { missingIndexForRelation, schemaHasIndexInfo } from '../index-advisor.js';
-import { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from '../nested-write.js';
+import { executeNestedCreate, executeNestedUpdate, extractRelationFields, hasRelationFields, } from '../nested-write.js';
 import { normalizeKeyColumns, snakeToCamel } from '../schema.js';
 import * as aggMod from './aggregates.js';
 import { assertProjectionShape, defaultProjectionFields, includeKeysForBatching, loadRelationsBatched, neededParentKeyFields, rejectNestedPickOrder, resolveCountRelations, stripFields, } from './batched-loader.js';
-import { assertWhereIdentifiesOneRow, expandCompoundUniqueWhere } from './compound-unique.js';
+import { assertMutationWhereIdentifiesOneRow, assertWhereIdentifiesOneRow, expandCompoundUniqueWhere, } from './compound-unique.js';
 import { dedupeColumnList, dedupeOrderEntries, isEmptyOrderBy, isJsonPathOrderBy, isOrderBySpec, isRelationPickOrderBy, isVectorOrderBy, isWhereOperator, orderByEntries, sortedEntries, } from './filters.js';
 import { warnUnknownQueryOptions } from './option-surface.js';
 import { applyStableRelationOrderTo, normalizeWithClause } from './relation-names.js';
@@ -3600,10 +3600,78 @@ export class QueryInterface {
     // -------------------------------------------------------------------------
     async upsert(args) {
         return this.executeWithMiddleware('upsert', args, async () => {
+            if (this.upsertNeedsLookup(args)) {
+                return this.upsertLookupFirst(args);
+            }
             const deferred = this.buildUpsert(args);
             return this.executeMutation(deferred, args.timeout);
         });
     }
+    /**
+     * @internal Whether `upsert()` looks the row up rather than running one
+     * statement, which is also exactly when `buildUpsert` refuses these args.
+     * prisma-compat reads it to decide whether an array `$transaction` can batch
+     * an upsert or has to run the array inside a transaction.
+     */
+    upsertNeedsLookup(args) {
+        return (hasRelationFields((args.create ?? {}), this.tableMeta) ||
+            hasRelationFields((args.update ?? {}), this.tableMeta) ||
+            writesMod.upsertLookupReason(this.ctx, args) !== null);
+    }
+    /**
+     * `upsert` as Prisma defines it: find the row `where` names, update it if it
+     * exists, else insert `create`, in one transaction (the caller's, when there
+     * is one). Taken whenever the single conflict statement would mean something
+     * else (`upsertLookupReason`: `where` not pinned to `create`'s values, an
+     * empty `update`, a global filter the engine's statement cannot carry) and
+     * whenever `create` or `update` holds nested relation writes, which only the
+     * nested-write engine can run.
+     *
+     * Validation is DATA-INDEPENDENT, as it is for the batched relation loader:
+     * both halves are compiled before the lookup runs, so an unknown field in
+     * `update` is refused whether or not the row exists, and a call is never
+     * valid on one row and invalid on the next. Only the scalar part of each half
+     * is compiled here; nested relation writes are validated by the engine that
+     * runs them.
+     *
+     * Not atomic against a concurrent insert of the same key, exactly as Prisma's
+     * own lookup is not: two callers can both miss, and the second insert then
+     * fails on the unique constraint (E008) when `create` carries the key. It
+     * never writes two rows over one key the database enforces.
+     */
+    async upsertLookupFirst(args) {
+        const where = (args.where ?? {});
+        const create = (args.create ?? {});
+        const update = (args.update ?? {});
+        assertMutationWhereIdentifiesOneRow(this.tableMeta, this.table, expandCompoundUniqueWhere(this.tableMeta, where), 'upsert');
+        this.resolveWriteProjection(args);
+        // An undefined option is an absent one on every call below.
+        const skip = { skipGlobalFilters: args.skipGlobalFilters };
+        const shape = { select: args.select, omit: args.omit, timeout: args.timeout };
+        const scalarCreate = extractRelationFields(create, this.tableMeta).scalars;
+        const scalarUpdate = extractRelationFields(update, this.tableMeta).scalars;
+        const updateIsEmpty = Object.values(update).every((v) => v === undefined);
+        if (Object.keys(scalarCreate).length > 0)
+            this.buildCreate({ data: scalarCreate });
+        if (Object.values(scalarUpdate).some((v) => v !== undefined)) {
+            this.buildUpdate({ where, data: scalarUpdate, ...skip });
+        }
+        const run = async (table) => {
+            const found = await table.findUnique({ where, ...shape, ...skip });
+            if (found) {
+                // Prisma reads an empty `update` as "leave it as it is": the row found
+                // IS the answer, projected as the write would have projected it.
+                if (updateIsEmpty)
+                    return found;
+                return (await table.update({ where, data: update, ...shape, ...skip }));
+            }
+            return (await table.create({ data: create, ...shape }));
+        };
+        if (this.txScoped) {
+            return run(this.buildNestedCtx().tx.table(this.table));
+        }
+        return this.runInImplicitTx((ctx) => run(ctx.tx.table(this.table)));
+    }
     // -------------------------------------------------------------------------
     // updateMany, UPDATE ... WHERE ... returning count
     // -------------------------------------------------------------------------

package/dist/query/compound-unique.d.ts

@@ -169,3 +169,27 @@ export declare function isInternalRowSelector(where: unknown): boolean;
  * uniqueness source there.
  */
 export declare function whereIdentifiesOneRow(meta: TableMetadata, where: Record<string, unknown>): boolean;
+/**
+ * Whether an `upsert` means the same thing as ONE conflict statement.
+ *
+ * An upsert's contract is Prisma's: find the row `where` names; update it if
+ * it exists, else insert `create`. A single `INSERT ... ON CONFLICT (<where
+ * keys>)` (or PowDB's `upsert ... on`) compares the conflict columns against
+ * the values being INSERTED, which are `create`'s, and never reads `where`'s
+ * values at all. The two agree exactly when every `where` key is pinned to the
+ * value `create` carries for that column. Otherwise the statement answers a
+ * different question: `where: { id: 5 }` with a `create` that leaves `id` to
+ * its sequence inserted a new row every time and never touched row 5, and
+ * `where: { email: a }` with `create: { email: b }` updated the row holding
+ * `b`, silently.
+ *
+ * Shared by every engine, like the one-row rule above: each one decides here
+ * whether it may take its single-statement fast path, and looks the row up by
+ * `where` first when it may not. `false` is always a SAFE answer (the lookup
+ * path is correct for every shape, only slower), so anything this does not
+ * recognise as a plain matching value answers `false`: an operator other than a
+ * bare `equals`, a different object (two Dates compare by instant), a key that
+ * names no column, and NULL, which a unique index never treats as equal to
+ * anything.
+ */
+export declare function upsertWhereMatchesCreate(meta: TableMetadata, where: Record<string, unknown>, create: Record<string, unknown>): boolean;

package/dist/query/compound-unique.js

@@ -420,6 +420,60 @@ export function whereIdentifiesOneRow(meta, where) {
         return false;
     return uniqueColumnSets(meta).some((cols) => cols.every((c) => pinned.has(c)));
 }
+/**
+ * Whether an `upsert` means the same thing as ONE conflict statement.
+ *
+ * An upsert's contract is Prisma's: find the row `where` names; update it if
+ * it exists, else insert `create`. A single `INSERT ... ON CONFLICT (<where
+ * keys>)` (or PowDB's `upsert ... on`) compares the conflict columns against
+ * the values being INSERTED, which are `create`'s, and never reads `where`'s
+ * values at all. The two agree exactly when every `where` key is pinned to the
+ * value `create` carries for that column. Otherwise the statement answers a
+ * different question: `where: { id: 5 }` with a `create` that leaves `id` to
+ * its sequence inserted a new row every time and never touched row 5, and
+ * `where: { email: a }` with `create: { email: b }` updated the row holding
+ * `b`, silently.
+ *
+ * Shared by every engine, like the one-row rule above: each one decides here
+ * whether it may take its single-statement fast path, and looks the row up by
+ * `where` first when it may not. `false` is always a SAFE answer (the lookup
+ * path is correct for every shape, only slower), so anything this does not
+ * recognise as a plain matching value answers `false`: an operator other than a
+ * bare `equals`, a different object (two Dates compare by instant), a key that
+ * names no column, and NULL, which a unique index never treats as equal to
+ * anything.
+ */
+export function upsertWhereMatchesCreate(meta, where, create) {
+    const createByColumn = new Map();
+    for (const [key, value] of Object.entries(create)) {
+        if (value === undefined)
+            continue;
+        const column = resolveColumnName(meta, key);
+        if (column !== undefined)
+            createByColumn.set(column, value);
+    }
+    let keys = 0;
+    for (const [key, raw] of Object.entries(expandCompoundUniqueWhere(meta, where))) {
+        if (raw === undefined)
+            continue;
+        const column = resolveColumnName(meta, key);
+        if (column === undefined || !createByColumn.has(column))
+            return false;
+        const value = isBareEquals(raw) ? raw.equals : raw;
+        if (!sameKeyValue(value, createByColumn.get(column)))
+            return false;
+        keys++;
+    }
+    return keys > 0;
+}
+/** `{ equals: v }` and nothing else (a `mode` beside it changes the match). */
+function isBareEquals(value) {
+    return isPlainObject(value) && Object.keys(value).length === 1 && 'equals' in value;
+}
+/** Equal non-null key values; two Dates compare by instant, other objects by identity. */
+function sameKeyValue(a, b) {
+    return a != null && (a instanceof Date && b instanceof Date ? a.getTime() === b.getTime() : a === b);
+}
 /** A bare value, or an operator object whose `equals` is a value. */
 function isPinnedToOneValue(value) {
     if (value === undefined || value === null)

package/dist/query/writes.d.ts

@@ -59,6 +59,29 @@ export declare function makeCreateReselect<T extends object>(qi: BuilderCtx, ins
 export declare function buildCreateMany<T extends object>(qi: BuilderCtx, args: CreateManyArgs<T>): DeferredQuery<T[]>;
 export declare function buildUpdate<T extends object>(qi: BuilderCtx, args: UpdateArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 export declare function buildDelete<T extends object>(qi: BuilderCtx, args: DeleteArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
+/**
+ * Why an `upsert` cannot run as this engine's single conflict statement, or
+ * `null` when it can. The one authority for that decision: `upsert()` asks it
+ * to choose between the statement and a lookup by `where` inside a
+ * transaction, and `buildUpsert` asks it to refuse the shapes its one
+ * statement cannot express, since a `DeferredQuery` (a pipeline, an array
+ * `$transaction`) has no second round trip to look anything up with.
+ *
+ * - `where-differs`: `where` is not pinned to `create`'s values, so the
+ *   conflict statement would compare the wrong row (upsertWhereMatchesCreate).
+ * - `empty-update`: an `update` with no fields has no `DO UPDATE SET` to emit;
+ *   every engine rejected the statement as a syntax error. Prisma reads it as
+ *   "create it if it is missing", which the lookup answers.
+ * - `global-filter`: MySQL's `ON DUPLICATE KEY UPDATE` has no predicate slot
+ *   and SQL Server's MERGE cannot take the builder's column references there,
+ *   so the table's global filter cannot guard the conflict update. The lookup
+ *   and the update both carry the filter, so another tenant's row is invisible
+ *   to them.
+ *
+ * Reads `currentSkip`, so it resolves `skipGlobalFilters` itself first.
+ */
+export type UpsertLookupReason = 'where-differs' | 'empty-update' | 'global-filter';
+export declare function upsertLookupReason<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>): UpsertLookupReason | null;
 export declare function buildUpsert<T extends object>(qi: BuilderCtx, args: UpsertArgs<T>, projection?: WriteProjection): DeferredQuery<T>;
 export declare function buildUpdateMany<T extends object>(qi: BuilderCtx, args: UpdateManyArgs<T>): DeferredQuery<{
     count: number;