fix(drivers): recognise the unbacked conflict target on Postgres too, from a measured PG 16.13 (#8567)

[os-zhuang]

Fixes#8567

The card's first deliverable was the measurement, and it decided the rest. Both questions answered, in the order the card set.

(1) MEASURE — Postgres, raised for real

A throwaway PostgreSQL 16.13 cluster from the system PG16 binaries (initdb + pg_ctl, no container runtime — the docker daemon is unreachable here), driven through knex + pg, the same path SqlDriver.upsert takes: a table with no unique index on the target column, then upsert(obj, row, ['email']). Read off the thrown error object, verbatim:

name = error (constructor DatabaseError)
code = "42P10" (typeof string)
severity = "ERROR"
routine = "infer_arbiter_indexes"
constraint = undefined
detail = undefined
status = undefined
message = insert into "plain" ("email", "id", "title") values ($1, $2, $3)
on conflict ("email") do update set "title" = excluded."title"
- there is no unique or exclusion constraint matching the ON CONFLICT specification

The card's stated expectation held — SQLSTATE 42P10, and prose matching "there is no unique or exclusion constraint matching the ON CONFLICT specification" — so nothing had to be overturned. knex wraps it the same way it wraps SQLite's: STATEMENT, then -, then the server's own sentence.

42P10 IS reachable by other conditions, which the card asked to be checked and which changes the design. Measured on the same cluster, same session:

select id from plain order by 7 -> code=42P10 "ORDER BY position 7 is not in select list"
select id from plain group by 9 -> code=42P10 "GROUP BY position 9 is not in select list"
select nope from plain -> code=42703 (a different code entirely)

42P10 is invalid_column_reference, not "unbacked conflict target". So a code-only predicate over-matches, and the message must carry the verdict — the code channel is left deliberately unread on both dialects (SQLite's is the generic SQLITE_ERROR). Also measured: a partial unique index (... where email is not null) raises the identical 42P10 and sentence, which is correct — a partial index cannot serve as an arbiter.

MySQL — the sub-question that needs no server, answered from the compiled SQL. knex compiles the driver's exact call on the mysql2 dialect to ON DUPLICATE KEY UPDATE, which takes no conflict target:

mysql2 -> insert into `plain` (`email`, `id`, `title`) values (?, ?, ?)
on duplicate key update `title` = values(`title`) <- no conflict target
pg -> insert into "plain" (...) values ($1, $2, $3)
on conflict ("email") do update set "title" = excluded."title"

The named keys never leave the process, so the server is never asked to find an index for them: the condition cannot arise on MySQL. What it does instead — merging on whichever unique key the row happens to collide with — is the separate defect the card anticipated; not fixed here, and not asserted here either, because nobody has watched a MySQL server do it. The live MySQL cell is declared un-run through live-dialect-matrix.testkit.ts rather than dropped.

(2) THEN the home — the dialects share a shape, so the predicate graduates

Two dialects, two unrelated sentences, one channel: that is precisely the per-dialect alternation UniqueViolationSignature already encodes. isUnbackedConflictTargetError now lives in @objectstack/types beside isUniqueViolationError, one measured limb per dialect, no new dependency edge.

It stays a separate predicate. isUniqueViolationError answers the opposite condition, and putting the two side by side is what puts the warning where someone reaching for the wrong one will read it.

driver-turso's private copy deliberately stays: that package does not depend on @objectstack/types, and its face speaks libsql/SQLite and only ever will, so the Postgres limb could never apply. Noted in place with the condition under which it should be deleted.

The wording moved one clause, on both faces

"…and SQLite refuses the statement" is now "…and the database refuses the statement". Once recognition covers Postgres, that sentence pointed a Postgres operator at the wrong engine. Per #5240 both faces carry one wording, so driver-turso's copy moved in the same commit. Nothing else in the refusal changed.

⚠️ Found while pinning: a pre-existing inversion, filed not fixed

The disjointness suite went red on its first run, and the measurement won. On SQLite, isUniqueViolationError already claims the unbacked-target error — its unique constraint limb matches SQLite's missing-index sentence, which ends ...any PRIMARY KEY or UNIQUE constraint. Postgres escapes only on word order. Measured on real driver errors:

sqlite unbacked-target error -> isUniqueViolationError = true <- wrong
pg unbacked-target error -> isUniqueViolationError = false <- correct

Filed as #8590 and left alone here — narrowing that predicate moves verdicts in six consuming packages. It is latent today (upsert is the only site compiling a caller-supplied conflict target, and recognition runs first in that catch), but a comment in sql-driver.ts asserted the opposite as fact and reasoned from it; that comment is corrected in place, and the ordering is now documented as load-bearing. The test pins both predicates' verdicts per dialect, so #8590's fix announces itself instead of landing silently. #8590 is not addressed by this PR.

Reverse verification — direction predicted before each leg

• Remove the Postgres limb ⇒ predicted the Postgres cell reddens and every SQLite pin holds. Observed: 3 failed | 11 passed | 1 skipped — envelope, wording and leak pins red on the live-postgres cell only; all 6 SQLite pins green; both positive controls green on both cells, which is what proves the limbs are independent rather than one regex covering both.
• Reword one face only (turso back to "SQLite") ⇒ predicted drivers(turso): the unbacked-conflict-target refusal has no cross-face parity pin — the two wordings can drift without a test noticing #8568's parity pin reddens. Observed: 1 failed | 9 passed, the failure being expect(localErr.message).toBe(remoteErr.message). Restored; both faces moved together, pin green.
• The driver-sql dist rebuild trap from drivers(turso): the unbacked-conflict-target refusal has no cross-face parity pin — the two wordings can drift without a test noticing #8568 was respected — driver-turso was only ever run against a freshly built dist carrying the reword (verified by grepping the built bundle).

Tests

Full suites, live Postgres cell provisioned and non-vacuous (server Asia/Shanghai, process TZ=America/New_York, so the three-way zone skew guard passes rather than the matrix proving nothing):

@objectstack/types 11 files, 280 tests passed
@objectstack/driver-sql 96 files, 1703 tests passed | 1 skipped (the MySQL cell)
@objectstack/driver-turso 37 files, 986 tests passed
typecheck: types, driver-sql, driver-turso — all clean

Gates derived from the actual changed paths via scripts/pm/dispatch-gates.mjs, all green: check:changeset-gate-self-tests, check:objectui-changeset, check:test-source-alias, check:type-source-resolution, check:query-options-erasure, check:type-check-coverage, check:error-code-casing, check:nul-bytes, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset.

Changeset: a real patch across the three packages. The accept/reject set does not move — the same upserts fail, they fail legibly — but a Postgres caller's response body changes from raw statement text to a coded envelope, which is consumer-visible.

Generated by Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 14, 2026 12:27am

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/driver-sql, @objectstack/driver-turso, @objectstack/types.

11 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx(via @objectstack/driver-sql, @objectstack/driver-turso)
• content/docs/deployment/cli.mdx(via @objectstack/driver-turso)
• content/docs/deployment/environment-variables.mdx(via @objectstack/driver-turso)
• content/docs/deployment/self-hosting.mdx(via @objectstack/driver-turso)
• content/docs/getting-started/glossary.mdx(via @objectstack/driver-sql, @objectstack/driver-turso)
• content/docs/kernel/services-checklist.mdx(via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx(via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx(via @objectstack/driver-sql, @objectstack/driver-turso, @objectstack/types)
• content/docs/protocol/kernel/index.mdx(via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx(via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx(via @objectstack/driver-sql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/driver-sql)

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.

[os-zhuang]

ACCEPT — reviewed against the tree at 91bdacb, and the measurement re-run independently rather than taken from the report.

This card's whole deliverable was question (1), so I did not accept the Postgres numbers on the report's word. I started my own throwaway PG 16.13 cluster and raised the condition:

ERROR: 42P10: there is no unique or exclusion constraint matching the ON CONFLICT specification
LOCATION: infer_arbiter_indexes, plancat.c:920

Byte-for-byte the sentence that went into the predicate's regex, and infer_arbiter_indexes matches the reported routine. The three follow-on claims corroborate too:

select id from plain order by 7 -> ERROR: 42P10: ORDER BY position 7 is not in select list <- over-match, real
select nope from plain -> ERROR: 42703: column "nope" does not exist <- different code
create unique index ... where email is not null;
insert ... on conflict (email) -> ERROR: 42P10: there is no unique or exclusion constraint… <- partial index is no arbiter

So 42P10 really is reachable from an unrelated condition, and the decision to leave the code channel unread on both dialects and let the message carry the verdict is forced by measurement, not stylistic. (Aside: initdb refuses to run as root, so this needed an unprivileged user — a real hurdle, cleared the same way on both sides.)

Verified in the diff, independently of the description:

• isUniqueViolationError was documented, not changed.unique-violation.ts is +22 lines of comment and zero code — so no verdict moves in the six consuming packages, exactly as the PR claims. This was the highest-risk thing to get wrong here and it is clean.
• The new predicate refuses a loose limb on purpose. Rejecting a bare on conflict fragment because knex prefixes statement text onto every upsert failure — including a unique violation, the opposite condition — is the sharpest call in this PR. A looser regex would have passed every test in it.
• One wording on both faces ({ field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240).sql-driver.ts and remote-transport.ts both now read "and the database refuses the statement". Naming SQLite to a Postgres operator would have been wrong the moment recognition widened.
• drivers(turso): the unbacked-conflict-target refusal has no cross-face parity pin — the two wordings can drift without a test noticing #8568's parity pin is not in the diff at all — and that is the point. Both faces moved together, so the runtime-vs-runtime comparison stayed green untouched, while drivers(sql): an upsert whose conflictKeys have no backing unique index throws a raw SqliteError — the local twin of #8413's consequence 2 #8445's single-face literal had to be updated. The literal was updated, not weakened: still a full-sentence toBe. The pin built yesterday did exactly the job it was built for, on its first real encounter.
• Path surface is packages/** + .changeset/** only. Not docs/adr/**, not .claude/skills/**. Graduating a predicate into @objectstack/types is triage-sanctioned for this card (its dispatch note names it), and types: isUniqueViolationError claims SQLite's UNBACKED-conflict-target error — a superstring collision on "UNIQUE constraint", the exact inversion the predicate's own warning names #8590's triage confirms types is the cli lane's — so this crossing was authorised, not incidental.
• The MySQL cell is declared un-run, not vacuously green, through the existing live-dialect-matrix.testkit.ts convention.

On #8590 — filing it instead of fixing it was the right call, and the reasoning is better than "out of scope": the fix moves a consolidated predicate's verdicts across six packages, and the naive narrowing would silently drop Postgres' violates unique constraint "...", which that limb has covered since it was inherited verbatim. Correcting the sql-driver.ts comment that asserted the opposite as fact and reasoned from it was the necessary half to do here — a wrong comment that a future author trusts is how the latent bug becomes live.

One thing I can resolve that the dev could not. The report declines to file the MySQL-behaviour card because no mysqld exists in the dev container and describing unobserved behaviour is the evidence standard #8445 ruled out — correct reasoning, incomplete premise. CI provisions a live MySQL:

# .github/workflows/ci.yml:583image: mysql:8.0# :673OS_TEST_MYSQL_URL: mysql://root:root@127.0.0.1:3306/conformance

So that half is measurable — in CI, not on a dev box. Nothing to change in this PR (the file here runs under Test Core, which has no such service, so its declared-un-run cell is honest for the job that runs it). I am filing the follow-up as a card whose first deliverable is the measurement, pointed at that runner, rather than one asserting what MySQL does.

Holding ready + queue until all 24 checks report green.

---

Generated by Claude Code