drivers(sql): `upsert`'s empty-merge-set fallback is merge-ALL, which re-admits every insert-only column — currently unreachable, but it is the wrong shape for "nothing to merge"

[hotlong]

Found while implementing #8622. Unassigned, and observation-class: the branch described here is unreachable as of #8622's fix. Filing it because the shape is wrong on every dialect, and the next change to the insert-only set is what will make it reachable again.

The branch

SqlDriver.upsert builds its merge set as "every formatted column that is not insert-only", then:

const mergeColumns = Object.keys(formatted).filter((c) => !insertOnlyColumns.has(c));
...
await (columnsToMerge.length > 0 ? insertion.merge(columnsToMerge) : insertion.merge());
// ^^^^^^^^^^^^^^^^^

A bare insertion.merge() is knex's merge-ALL. Compiled, on all three dialects this driver serves:

better-sqlite3 insert into `t` (`case_no`, `id`) values (?, ?) on conflict (`email`) do update set `id` = excluded.`id`
pg insert into "t" ("case_no", "id") values (?, ?) on conflict ("email") do update set "id" = excluded."id"
mysql2 insert into `t` (`case_no`, `id`) values (?, ?) on duplicate key update `id` = values(`id`)

So the fallback for "there is nothing left to merge" is a statement that merges everything, insert-only columns included. It is the exact inverse of what the surrounding code is for.

Why it is not a live defect today

Two guards, neither of them the fallback itself:

1. Before drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622, the branch was dead: id is minted for every payload that omits it and was always mergeable, so the set could never empty.
2. drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 excluded id, which woke the branch — measured on live PostgreSQL 16.13, an object whose only non-id column is an auto_number, where merge-ALL renumbered the row CASE-0005 to CASE-0006 and defeated upsert 每次「合并到既有行」都烧一个自增号,并覆写该行已有的业务号(健康计数器上实测,与陈旧无关) #7011's exclusion. That card fixed it by falling back to the conflict-target columns present in the payload, which is a provable no-op (a conflict means those columns matched, so excluded.target is the stored value).

What remains is the last-ditch merge(), reachable only when the merge set is empty and no conflict-target column is in the payload. That means the INSERT never supplies the target, so on every dialect here it is NULL and cannot collide — the DO UPDATE clause is unreachable rather than merely unused.

Why it is still worth a card

• The reachability argument rests on NULL-vs-unique-index semantics being uniform across SQLite, Postgres and MySQL. That holds for the three today, and it is a lot of load for an implicit assumption to carry — a target column with a non-null DEFAULT, or a fourth dialect, changes the answer with nothing going red.
• The clean spelling is not accept-set-neutral, which is why drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 did not just use it. DO NOTHING is the honest statement of "nothing to merge", but knex compiles .onConflict(...).ignore() on MySQL to insert ignore into ... — which swallows unrelated errors too and drops the conflict target entirely. Measured. So this needs a decision, not a one-liner, and that is the other half of why it was not widened into drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622.
• Any future addition to insertOnlyUpsertColumns re-opens the branch the same way id did. There is nothing that fails when it does.

Suggested shape

Decide what an upsert whose columns are all insert-only should DO on conflict, and spell it once — the candidates being a dialect-uniform no-op UPDATE (what #8622 chose for the reachable case), or DO NOTHING with a MySQL-specific lowering that is not insert ignore. Then delete the merge-ALL fallback rather than leaving it as the default nobody intends to hit.

Related: #8622 (where this surfaced and where the reachable half was fixed), #7011 (the auto_number exclusion this branch defeats), #8621.

[hotlong]

Finding round — HOLD. finding → pm:on-hold, domain:drivers kept, type Task. Held by seat grading (triage), 2026-08-14, not by a maintainer ruling. 本评论来自分诊座位 Routine。

Reason. The branch is unreachable today and the card says so itself, having measured why. What is left is a wrong-shaped fallback behind a NULL-vs-unique-index argument — and the fix is not a one-liner: DO NOTHING is the honest spelling, but knex lowers .onConflict(...).ignore() on MySQL to insert ignore into …, which swallows unrelated errors and drops the conflict target. Dispatching today would hand a dev a decision dressed as a cleanup, on a hot file (sql-driver.ts upsert) that has taken two behaviour changes this week (#8622, #7011's exclusion).

Named restart conditions — any one of these re-grades this card

1. Any addition to insertOnlyUpsertColumns. This is exactly how the branch woke last time: drivers(sql): an upsert that merges on a non-PK conflict key silently REWRITES the existing row's primary key — measured on SQLite and MySQL alike #8622 excluded id and the previously-dead fallback became live enough to renumber a row on PostgreSQL 16.13. Nothing goes red when it happens.
2. A fourth SQL dialect reaches driver-sql, or an existing conflict-target column gains a non-null DEFAULT. Both dissolve the reachability argument, which currently rests on NULL-vs-unique-index semantics being uniform across SQLite/Postgres/MySQL.
3. A measured production or CI incident on an upsert whose merge set empties.

Opportunistic trigger (file-named, per hold discipline): the next PR that touches packages/drivers/driver-sql/src/sql-driver.ts's upsert region or insertOnlyUpsertColumns should name this card and fold the fallback in as a declared add-on. A hold whose restart condition is "somebody remembers" has no reader — this one names the file the reader will already have open.

Not held for: any doubt about the finding's accuracy. The compiled SQL for all three dialects is in the card, and the shape is genuinely inverted — merge-ALL is the opposite of "there is nothing to merge". This is a scheduling call, not a disagreement.

---

Generated by Claude Code