bun:sqlite: refuse an asynchronous callback in db.transaction()

[robobun]

Related to #24662

Problem

• db.transaction(fn) of bun:sqlite runs COMMIT when fn returns. An async callback returns at its first await, so later statements run outside the transaction. A failed transfer ends at 60, 0, not 100, 0.
• Cause: wrapTransaction (src/js/bun/sqlite.ts:670-674) runs after.run() after fn.$apply(). It ignores the result.

Fix

• The wrapper throws a TypeError for a promise or thenable result. The existing catch rolls back. better-sqlite3, the source of this helper, does this since 11.10.0.
• For an async function, db.transaction(fn) returns wrappers that throw before BEGIN, so the body never starts. A Bun addition, in its own commit.
• Behaviour change on a released API. A maintainer must decide which release carries it.
• Verified: test/js/bun/sqlite/sqlite.test.js (24 new tests fail on release main, pass here). Other suites: Notes. Self-reviewed: 13 concerns raised, 13 addressed.

Background

• db.transaction(fn) returns a function that runs BEGIN, fn, then COMMIT, or ROLLBACK when fn throws.
• Considered the result check alone: the async body still starts. Considered COMMIT on settle (SQLite Database.transaction() should support async functions #24662): the connection stays in a transaction across awaits.

Downsides

• A program that passes an async callback now throws on each call. It is non-atomic today.
• A callback that starts async work and returns its promise still throws. That work runs on: 100, 40 (main: 60, 40). If it fails, Bun exits with code 1, even if the caller caught the TypeError.
• Per synchronous call: +2 bytecodes, +7 for an object result. DFG: +0 to +45 machine instructions, about +300 for an 80-column row. Binary: +1,029 bytes.

Notes

Earlier attempt. This PR replaces #32937, which a cleanup of stale PRs closed with no verdict on the fix. Four things differ from it. The refusal of an async function moved from db.transaction() to the call. The refused promise is no longer marked as handled. A primitive result no longer costs a then lookup. An async function of another realm is refused before BEGIN too. One statement of mine on #32937 was wrong. A never overload does not catch a callback that returns any. It does catch a callback that always throws and a callback typed any, so it is still the wrong shape.

The rule, for a maintainer to accept or change once.

Callback	db.transaction(fn)	A call of the returned function
returns a value that is not a thenable	returns the wrapper	BEGIN, fn, COMMIT, returns the value
throws	returns the wrapper	BEGIN, fn, ROLLBACK, the error propagates
async function of any realm (arrow, function, method, AsyncFunction), or a bound function or a Proxy of one of this realm	returns the wrapper	TypeError before BEGIN. fn does not run
any other function that returns a promise or a thenable	returns the wrapper	BEGIN, fn, ROLLBACK, TypeError
returns an object whose then getter throws	returns the wrapper	BEGIN, fn, ROLLBACK, the error of the getter propagates (as in better-sqlite3). Main returns the object and does not read then
generator or async generator function	returns the wrapper	unchanged: returns the iterator

The errors are plain TypeErrors with no code, as for the existing argument check of db.transaction():

• db.transaction() callback must be synchronous, but it is an async function. Remove async/await from the callback, or move the awaited work outside the transaction.
• db.transaction() callback must be synchronous, but it returned a promise. Remove async/await from the callback, or move the awaited work outside the transaction.

Before and after. The balances start at 100, 0 and the callback moves 40. Release builds of main 7c96a12 and of this change.

Callback	main	this PR
async: debit, await, fail	promise rejects, 60, 0	TypeError at the call, 100, 0
async: debit, fail before any await	promise rejects, 60, 0	TypeError at the call, 100, 0
async: debit, await, credit	promise fulfils, 60, 40	TypeError at the call, 100, 0
plain: debit, return a promise that rejects	promise rejects, 60, 0	TypeError, 100, 0, the rejection is reported as unhandled
plain: debit, credit, return an unrelated promise	promise fulfils, 60, 40	TypeError, 100, 0
plain: debit, then an async helper credits later	promise fulfils, 60, 40	TypeError, then 100, 40
generator: debit, yield, credit	60, 40 after iteration	unchanged
a forwarder that drops the result of an async callback	60, 0	unchanged

A matrix of 17 callback shapes and 6 call paths (default, .deferred, .immediate, .exclusive, nested, under a BEGIN by hand) gives 102 cells. On main all 102 return with no error: 72 end at 60, 40 and 30 at 60, 0. With this PR 60 cells are refused at 100, 0, 6 more at 100, 0 with the rejection reported, 18 are refused and end at 100, 40, and 18 are unchanged (12 generator, 6 forwarder). The 18 cells at 100, 40 are an async function whose prototype was replaced, down-levelled async output, and a plain function around an async helper.

Choices that are open for a maintainer.

1. Refuse, or support. SQLite Database.transaction() should support async functions #24662 asks for COMMIT when the promise settles. That keeps the single connection in a transaction across awaits, so a statement that other code runs on the handle joins the transaction. A refusal can become support later without a break for any program that is valid after this PR.
2. A synchronous callback that runs every statement and then returns an unrelated promise is atomic today. With this PR it gets ROLLBACK and a TypeError, as in better-sqlite3. No check on the result can tell this callback from one whose work is still running. The same check reads then of an object result once, so a then getter that throws now rolls back and propagates. Alternative: COMMIT (or RELEASE), then throw. A call at the top level then ends as on main, 60, 40, or 60, 0 when the work fails. But a call that throws has then applied its statements, and a call inside an outer transaction that rethrows still ends at 100, 40.
3. Where an async function is refused. As built: at the call, before BEGIN, which keeps every order of calls that better-sqlite3 accepts (a wrapper that is never called, a wrapper made at module scope, the RangeError of a closed database). Alternative: inside db.transaction(), by a move of one throw. Alternative: nowhere, by a drop of the second commit. Then the body of an async function runs to its first await, and the rest of it runs after the rollback.
4. How an async function is recognised. As built: the prototype of this realm's async functions, or util.types.isAsyncFunction for another realm. A function whose prototype is this realm's Function.prototype is not asked. Jest evaluates test files and application modules in a node:vm context, so the first test alone never matches there. With real Jest 30 on this build, an async callback gets the TypeError before BEGIN and its body starts 0 times. A bound function or a Proxy of an async function of another realm is still seen by the result check only.
5. The refused promise. As built it is left as it is. If it rejects, Bun reports the rejection and the exit code is 1, also when the caller caught the TypeError, and a Bun.serve process ends (main: the caller handles the promise and the process goes on, with the debit kept). This happens for a callback that the kind test cannot see: a plain function around an async helper, down-levelled async output, an async function whose prototype was replaced. One line of $pokePromiseAsHandled makes the process quiet. Then a failure of work that already committed leaves no trace: exit code 0, empty stderr, 100, 40. fs.cpSync (src/js/internal/fs/cp-sync.ts:192), node:sqlite user functions (NodeSqlite.cpp:437), fetch tls.checkServerIdentity and the WebSocket client also refuse a promise and leave it alone. Two open PRs, Bun.plugin: mark the loader's promise handled when require() cannot wait for a plugin's promise #37038 and Propagate errors thrown by a runtime plugin's onResolve callback #33408, mark a promise that a synchronous path cannot wait for. One answer can cover all three PRs. A sentence for REVIEW.md would end the question: a sync-only API that refuses a promise throws and leaves the promise alone.
6. A refusal in the types. packages/bun-types/sqlite.d.ts gets JSDoc only. Each hard refusal that I measured with tsc 6.0.2 fails on a shape that the runtime accepts. The existing result type intersected with 0 extends 1 & T ? unknown : [T] extends [null | undefined] ? unknown : [T] extends [PromiseLike<unknown>] ? never : unknown makes the wrapper of a promise-returning callback never. It accepts callbacks that return any, never, unknown, void, a union with a promise, and a generic forwarder. It fails on a subclass that overrides transaction and writes the old result type out (TS2416). The same conditional on the parameter gives an error at the db.transaction() call, and fails on a generic forwarder (TS2345). The choice is left to the owner of the types.

Reach. The checks cover direct callers only. drizzle-orm/bun-sqlite wraps the callback in a synchronous arrow function that returns nothing (session.ts:74-77), so it neither starts to throw nor stops the early COMMIT. A GitHub code search found 15 public programs that pass an async function to db.transaction() of bun:sqlite. I read 3 of them: in each, a failure of the callback rolls back nothing today. No code or test in this repository passes an async callback to it.

Not changed on purpose. Generator and async generator callbacks: better-sqlite3 accepts them, and the docs now say that their statements run outside the transaction. Callbacks of other modules that must be synchronous. #24662 stays open. #36712 (a better-sqlite3 module on top of bun:sqlite) forwards to db.transaction(). It gets the refusal at the call, as upstream.

One changed error. A wrapper of an async callback that is called after db.close() throws the TypeError. On main it throws Database has closed.

Measurements. Release builds of main and of this change on the same base, debug builds for the bytecode dumps. The sizes and the bytecode counts are from base c69a636. The instruction counts and the matrix are from base 7c96a12 and an earlier revision of this branch, whose wrapper is the same. perf, valgrind and strace are not installed here and the machine has no hardware counters. The instruction counts come from a ptrace single-step counter, 30 windows per row.

• Bytecodes (BUN_JSC_dumpGeneratedBytecodes=1): the sync wrapper 72 to 80, with +2 executed for a result that is not an object and +7 (one then read) for an object. Database#transaction 83 to 90, plus a helper of 35. A synchronous callback executes +18 per db.transaction(fn), with one Object.getPrototypeOf call. wrapTransaction 26 to 26.

• then reads per synchronous call (20,000 calls per kind): 0 for undefined, null and each primitive, 1 for an object, array, function or Proxy result. Main: 0.

• Machine instructions per synchronous call in DFG and FTL, main to PR:

  Callback	DFG	FTL
  returns undefined, a number or the same object, inlined	2938 to 2938	2570 to 2570
  returns undefined, not inlined	3001 to 3006	2605 to 2606
  returns a new object literal	2954 to 2954	2584 to 2584
  returns stmt.get()	6495 to 6508	6128 to 6138
  returns stmt.all()	6867 to 6880	6500 to 6510
  returns objects of 32 shapes	2960 to 3005	2597 to 2637
  returns an 80-column row (minimum of 30 windows)	112208 to 112506	111839 to 112099

  A callback that runs a statement and returns undefined or the result of stmt.run() shows no difference between the builds: the windows of both builds vary by 92 instructions.

• Machine instructions per synchronous call below the JIT tiers. LLInt: 7267 to 7336 (undefined, number), 7340 to 7778 (object). Baseline: 3961 to 3973, 3970 to 4034 (object).

• Machine instructions per db.transaction(syncFn), before the short cut for an ordinary function: LLInt 30959 to 31649, Baseline 24208 to 24494, DFG 20759 to 20925, FTL 20464 to 20579. The short cut removes the util.types call from that path (+24 bytecodes to +18).

• GC cells: 18 per db.transaction(syncFn) (main 18), 10 per db.transaction(asyncFn) (main 18), 3 per synchronous call (main 3).

• A Proxy callback sees its getPrototypeOf trap once per db.transaction(fn) and never per call.

• Module load of bun:sqlite: +17 bytecodes (one async function object, two more function objects, one Object.getPrototypeOf call, five bindings).

• Size: the module text grows by 1,029 bytes (14,600 to 15,629) and the release binary by the same 1,029 bytes of text (size). No host function is added.

• A refused async callback: 0 sqlite3_step calls and 0 starts of the callback in 1,000 calls (gdb breakpoint count). Main: 2 steps per call. With the write lock held by another connection, .immediate() and .exclusive() throw the TypeError, not SQLITE_BUSY.

Repro. Exit code 1 on main (release builds of 7c96a12 and c69a636, a debug build) and on Bun 1.4.2. Exit code 0 with this change (release and debug).

import { Database } from "bun:sqlite";
const open = () => { const db = new Database(":memory:"); db.exec("create table acc (id integer primary key, bal integer); insert into acc values (1, 100), (2, 0)"); return db; };
const debit = (db, n) => db.run("update acc set bal = bal - ? where id = 1", [n]);
const fail = () => { throw new Error("the credit failed"); };
async function run(name, make) {
  const db = open(); let how = "resolved";
  try { await make(db)(40); } catch (e) { how = e.name + ": " + e.message; }
  const b = db.query("select bal from acc order by id").all().map(r => r.bal).join(", ");
  console.log(name + ": balances " + b + " | " + how); return b;
}
const got = [
  await run("async function, fails after an await", db => db.transaction(async n => { debit(db, n); await Bun.sleep(1); fail(); })),
  await run("async function, fails before any await", db => db.transaction(async n => { debit(db, n); fail(); })),
  await run("plain function that returns a promise", db => db.transaction(n => { debit(db, n); return Bun.sleep(1).then(fail); })),
  await run("async function, .immediate", db => db.transaction(async n => { debit(db, n); await Bun.sleep(1); fail(); }).immediate),
];
process.exit(got.every(b => b === "100, 0") ? 0 : 1);

Tests. 24 new tests in one describe block. All 24 fail on a release build of main c69a636. All 24 pass on a debug build and on a release build of this branch. With the second commit reverted, its 11 tests fail and the other 13 pass.

Other suites. test/js/bun/sqlite/ on the debug build: 166 pass. #13082, a GC stress test in the same file, exceeds its 5 s limit on a debug build, on main and on this branch alike. test/regression/issue/14709.test.ts: 5 pass. test/integration/bun-types/bun-types.test.ts: 22 pass. bun x tsc --noEmit -p src/js/tsconfig.json: exit 0. bun lint and bun fmt --check on the changed files: no problems.

Docs. I ran each claim of the new docs note: the two refusals, the work that runs on after the rollback and joins a transaction that is open, a generator body that runs at iteration, and two overlapping transactions by hand or with sql.begin() of Bun.SQL, where the second BEGIN throws cannot start a transaction within a transaction. With the usual try { BEGIN ... COMMIT } catch { ROLLBACK } handler, that second request rolls back the transaction of the first one, which is why the note says to keep BEGIN outside the try.

---

no test proof · iteration 4 · platform-specific test(s) that do not run on this machine, deferring to CI, which covers all platforms: test/js/bun/sqlite/sqlite.test.js

[robobun]

^{Updated 2:56 PM PT - Oct 13th, 2026}

✅ @robobun, your commit 10e9abb9e22226efa9786838a77e396f3a39e1a7 passed in Build #125217! 🎉

---

🧪   To try this PR locally:

bunx bun-pr 45132

That installs a local version of the PR into your bun-45132 executable, so you can run:

bun-45132 --bun

[robobun]

Status: reproduced with the script in the Notes of the description. It exits with code 1 on a release build and on a debug build of main 7c96a12, and on Bun 1.4.2: 4 of 4 failed transfers keep the debit (60, 0). With this branch it exits with code 0 (100, 0 on each row).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: oven-sh/bun/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 2cff5a1b-04f1-48f2-bc6a-b0ad3c25e0df

📥 Commits

Reviewing files that changed from the base of the PR and between 56f486b and 10e9abb.

📒 Files selected for processing: 1

• src/js/bun/sqlite.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

Walkthrough

SQLite transaction wrappers now reject async-function callbacks before starting a transaction and reject promise-like results before committing. Tests cover callback forms, rollback behavior, and asynchronous work that continues after refusal. Documentation describes the synchronous callback requirement and connection-scoped transaction limits.

Changes

SQLite Transaction Validation

Layer / File(s)	Summary
Refuse async callbacks src/js/bun/sqlite.ts, test/js/bun/sqlite/sqlite.test.js	Transaction variants detect async functions, including supported bound, proxy, and cross-realm forms. They throw TypeError before transaction setup or callback execution. Tests cover these forms and transaction states.
Reject promise-like results src/js/bun/sqlite.ts, test/js/bun/sqlite/sqlite.test.js, packages/bun-types/sqlite.d.ts, docs/runtime/sqlite.mdx	The wrapper rejects native promises and callable thenables before commit or savepoint release. Tests cover result inspection, rollback, and asynchronous work that continues after refusal. The API and runtime documentation describe the synchronous callback requirement and transaction limits.

Priority: ⬆️ High

Merge Risk: ⚪ Minimal · up to 10e9a

Async transaction callbacks and promise-like results are rejected rather than committed; the inspected callable-thenable case is also covered. No actionable merge risk is established in the reviewed context.

Pre-merge checks: 4

Passed checks: 4 passed

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly and concisely identifies the main change: refusing asynchronous callbacks in bun:sqlite transactions.
Description check		The description explains the problem, implementation, behavior change, limitations, verification results, and test coverage. It does not use the exact template headings, but it provides the required i…

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Findings marked 🟡 are optional suggestions and need no follow-up push.

[claude]

🔴 Callers whose sync callback wraps an async helper now get torn data: the helper's synchronous prefix is rolled back while its continuation still commits later. src/js/bun/sqlite.ts:694 throws for a promise result inside the try, so src/js/bun/sqlite.ts:703 runs ROLLBACK after the callback has already returned; statements after the first await cannot be undone. The base committed the prefix, so both halves landed (60, 40); after merging the end state is 100, 40, as test/js/bun/sqlite/sqlite.test.js:1321 records. Fix: for a thenable result keep the already-executed statements as the base did, e.g. after.run() then throw the TypeError, on both the BEGIN and savepoint paths. Population: tslib __awaiter output, tracing/APM wrappers, any () => asyncHelper(). [also at: src/js/bun/sqlite.ts:703 - Users whose plain callback forwards an async helper's promise now get a half-applied write that the base never produces: the part before the first await is rolled back, the rest commits later. src/js/bun/sqlite.ts:694 throws for a promise result and the catch at src/js/bun/sqlite.ts:703 runs ROLLBACK, but the helper's body is already running and resumes after the rollback, outside any transaction.]

Why this was flagged

A plain function passed to db.transaction() calls an async helper and returns its promise, e.g. db.transaction(o => createOrder(o)) where createOrder inserts the order row, awaits something, then inserts the item rows. On the base, wrapTransaction ran BEGIN, the synchronous prefix (order insert), COMMIT, and returned the promise; the continuation (item inserts) ran later in autocommit, so both halves were in the database. After merging, src/js/bun/sqlite.ts:694 sees $isPromise(result) and throws; the catch at src/js/bun/sqlite.ts:702-706 runs ROLLBACK, undoing the order insert, and the continuation still inserts the items later, so the database holds item rows with no parent order. The test at test/js/bun/sqlite/sqlite.test.js:1305-1321 shows exactly this: balances go to [100, 40] instead of the base's [60, 40]. The TypeError is thrown synchronously, but the torn write happens anyway on the next microtask, with nothing to stop it.

Verification: In src/js/bun/sqlite.ts, line 694 matches the returned promise and line 695 throws, so the catch at lines 701-706 executes undo.run() (ROLLBACK) at line 703, discarding the prefix. Nothing cancels the continuation, which runs later outside any transaction. The check at lines 662-667 cannot see this shape. After this change the end state is prefix undone + continuation applied (100, 40).

[robobun]

The end state you describe is right, and it is the second bullet of Downsides: 100, 40 where main ends at 60, 40. I measured the alternative with a userland copy of the wrapper. The balances start at 100, 0. The helper debits 40, awaits, then credits 40.

Wrapper	the helper succeeds	the helper fails after the await
main	no throw, 60, 40	no throw, 60, 0
ROLLBACK, then throw (this PR)	TypeError, 100, 40	TypeError, 100, 0
COMMIT, then throw, call at the top level	TypeError, 60, 40	TypeError, 60, 0
COMMIT, then throw, call inside an outer transaction that rethrows	TypeError, 100, 40	TypeError, 100, 0

COMMIT then throw keeps the data of main for a call at the top level. It has three costs. A call that throws has applied its statements, against the documented rule that a throw rolls back. The failure case of the report stays at 60, 0. A nested call whose TypeError propagates ends at 100, 40 anyway, because the ROLLBACK of the outer transaction takes the first half with it.

ROLLBACK is also what better-sqlite3 does since 11.10.0, so I kept it and added this alternative to choice 2 of the description for a maintainer. Neither order can stop the work that the callback already started. Only the refusal before BEGIN does that, and it covers each callback that is an async function at runtime.

[claude]

🔴 Users whose callback returns a promise that later rejects now get an unhandled rejection and exit code 1, even when they catch the TypeError. src/js/bun/sqlite.ts:694-697 throws and drops the promise without marking it handled, so a transpiled async body (TypeScript __awaiter), a plain wrapper around an async helper, or a prototype-swapped async function that fails after its first await crashes the process; on the base branch the caller received that promise and handled it. Fix: call $pokePromiseAsHandled (or attach a no-op rejection handler) on the refused promise before throwing, so the TypeError remains the single error surface.

Why this was flagged

A plain (non-async-kind) callback that starts async work and returns its promise reaches wrapTransaction via any of the four wrappers created at src/js/bun/sqlite.ts:613-620, because isAsyncFunction at src/js/bun/sqlite.ts:662-667 cannot see it (TypeScript emitted __awaiter, () => asyncHelper(), or an async function with its prototype replaced). At src/js/bun/sqlite.ts:694-697 the result is detected and a TypeError is thrown; the promise object is discarded with no handler attached. If that work later throws (e.g. after its first await), the promise rejects with no handler, Bun prints the unhandled rejection and exits with code 1 even though the caller wrapped the call in try/catch; the test at test/js/bun/sqlite/sqlite.test.js "does not hide the rejection of the promise that it refused" asserts exactly exitCode 1 and stdout "caught TypeError". On the base branch the wrapper returned the promise and the caller awaited or .catch-ed it, so the process kept running. The catch block at src/js/bun/sqlite.ts:701-707 only rolls back and rethrows; nothing marks the promise as handled.

Verification: src/js/bun/sqlite.ts:694-697 discards result with no handler attached and no $pokePromiseAsHandled. The orphaned promise's rejection is then unhandled, and Bun's default unhandled-rejection policy terminates the process with exit code 1 even though the caller's try/catch swallowed the TypeError. On the base branch the caller received that promise and could await/.catch it.

[robobun]

This is choice 5 in the description, which is left to a maintainer, and the cost you describe is the second bullet of Downsides. I measured both sides on release builds.

• As built: when the work that the callback started fails later, Bun reports the rejection and the exit code is 1, also when the caller caught the TypeError. A Bun.serve process ends.
• With $pokePromiseAsHandled: the process goes on. But a failure of that work then leaves no trace, also when the work committed a statement before it failed: exit code 0, empty stderr, 100, 40.

I left the promise alone for two reasons. The callbacks in the tree that must be synchronous and already refuse a promise leave it alone: fs.cpSync (src/js/internal/fs/cp-sync.ts:192), node:sqlite user functions (NodeSqlite.cpp:437), fetch tls.checkServerIdentity and the WebSocket client. And REVIEW.md says never to swallow a failure.

The first version of this change (#32937) had the mark, and #37038 and #33408 mark such a promise, so one ruling can cover all of them. If the ruling is to mark, it is one line before the throw, and the test does not hide the rejection of the promise that it refused changes its expected exit code.

[claude]

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.

Still open from earlier reviews (2):

• 🔴 src/js/bun/sqlite.ts:700 — Users whose callback returns a promise that later rejects now get an unhandled rejection and exit code 1, even when the…
• 🔴 src/js/bun/sqlite.ts:701 — Callers whose sync callback wraps an async helper now get torn data: the helper's synchronous prefix is rolled back whi…

If you have decided not to act on one of these findings, resolve its thread (a reply alone leaves it open) and the next review stops counting it. To review this commit again now, use Re-run on its "Claude Code Review" check.