The write-path documentation taught an API the builder has never had. Every sample on these pages throws on its first line.
Methods that do not exist
db.update, db.insert, db.delete, db.execute, db.truncate, db.prepare, db.explain, db.beginTransaction, db.subquery, db.restore, db.forceDelete, plus the chained .update() / .updateFrom() forms — ~40 call sites. docs/api/reference.md listed update(table) in its method table, and packages/bun-query-builder/README.md used one in its example.
I enumerated the 62 methods the builder actually exports and mapped against that, so the replacements are the real surface rather than a guess:
| documented | actual |
|---|---|
db.update(t, id, v) | db.updateTable(t).set(v).where({ id }) |
db.insert(t, v) | db.create(t, v) — identical signature |
db.delete(t, id) | db.remove(t, id) — identical signature |
db.execute(sql) / db.prepare(sql) | db.unsafe(sql) |
db.explain(sql) | db.selectFrom(t).where(…).explain() |
db.truncate(t) | Model.truncate(), or db.unsafe('TRUNCATE TABLE t') |
db.restore(t, id) | model.restore(), or clear the column via updateTable |
db.subquery(q) | db.raw('(SELECT …)', params) |
Not everything was a rename
There is no manual transaction control — no beginTransaction/commit/rollback, and no rollbackToSavepoint. Both transaction() and savepoint() own their lifecycle through a callback: return to commit, throw to roll back. Those sections were rewritten around the real API, including the batch-checkpoint example, which was built entirely on the imaginary one and is now a per-chunk savepoint() that actually does what the prose claimed.
restore and truncate are model-layer operations, not builder methods, and are shown there now with the query-builder equivalent alongside.
While rewriting the transaction docs I added the warning that the sibling bug in #1065 makes concrete: use tx, not db, inside the callback — db holds a different connection, so work issued through it is not part of the transaction.
Two mechanical corruptions, both from eaa3b24 chore: fix lint errors
Six pages lost their heads. select, insert, update, delete, joins, raw-queries each began mid-code-block — no H1, no intro, the first example's opening fence and the whole "Basic …" section gone, so the page opened on an orphaned .get(). Restored from eaa3b24^, anchored on the surviving body so the edits those files have had since are preserved. Fence counts are now even on every page (they weren't).
132 identifiers had _ rewritten to * — created*at, user*id, avg*age — and the multiplication in 7 * 24 * 60 * 60 * 1000 went the other way to 7 _ 24 _ …. docs/advanced/distributed.md:554 had 60 _ 60 * 1000, half-converted, which is what gives the cause away. Fixed with a guard that leaves SELECT *, COUNT(*) and **bold** untouched; /_ ... _/ block comments restored to /* ... */.
Verification
Every db. / trx. / tx. / sp. call across docs/ and both READMEs now resolves to a real exported method — checked mechanically against the live method list, not by eye. Fence parity is even across all pages. No [A-Za-z0-9]*[A-Za-z0-9] mangling remains.
Docs-only: typecheck 0, lint 0 errors, suite 1698 pass / 4 skip / 0 fail, unchanged.
Worth pairing with a docs-lint test so this class can't come back silently — noted as follow-up, not in this PR.
🤖 Generated with Claude Code