node:sqlite: implement the module and pass the Node v26.3.0 test suite

[cirospaciari]

What

Adds the node:sqlite module and brings the full Node v26.3.0 test-sqlite-* suite into the repo, passing.

This builds on #29821 (merged into this branch unchanged): native DatabaseSync, StatementSync, backup(), sessions/changesets, custom scalar/aggregate/window functions, the authorizer, and process.versions.sqlite, all implemented in C++ against the bundled sqlite3 amalgamation. On top of that, this PR adds what was still missing to actually ship it on current main and to match Node v26.3.0:

• Rust module registration (src/resolve_builtins/HardcodedModule.rs): the module resolver no longer reads the Zig tables, so node:sqlite is registered there as a prefix-only builtin (same treatment as node:test). This is the line that makes require("node:sqlite") resolve.
• Bundled SQLite 3.53.0 → 3.53.2 (regenerated with scripts/update-sqlite-amalgamation.sh 3530200 2026). 3.53.2 contains the session-extension hardening (SQLite check-in e807d4e379) that makes sqlite3changeset_apply() return SQLITE_CORRUPT on malformed UPDATE changesets instead of dereferencing a NULL sqlite3_value*. Node v26.3.0 ships 3.53.1 plus a cherry-pick of the same check-in, and test-sqlite-session.js exercises it.
• SQLITE_ENABLE_PERCENTILE added to the sqlite build defines, matching Node's compile-time feature set, so the percentile()/median() SQL functions exist (asserted by upstream test-sqlite.js).
• Vendored tests synced to the v26.3.0 tag: test-sqlite-database-sync.js, test-sqlite-backup.mjs, and test-sqlite-session.js refreshed to the upstream copies (using-based cleanup, the backup keep-alive GC test, the malformed-changeset test); test-sqlite-database-sync-dispose.js removed because upstream merged that suite into test-sqlite-database-sync.js; the percentile is enabled test now gates on a runtime probe of the loaded library (sqlite_compileoption_used) rather than an unconditional skip, so it runs for real wherever the bundled amalgamation is linked. common/index.js now treats --experimental-sqlite/--no-experimental-sqlite as no-ops under Bun instead of re-spawning the test, so upstream // Flags: headers stay verbatim.

Test results (debug build, Linux x64)

• All 18 vendored test/js/node/test/parallel/test-sqlite-*.{js,mjs} files pass when run the way CI runs them (bun test --config=bunfig.node-test.toml): 319 subtests pass, 0 fail, 4 skip. Node v26.3.0 has no sqlite tests under test/sequential/.
• Remaining skips (4 subtests, each with an inline reason): Worker online-timing in the busy-timeout test, the error shape for require("sqlite") without the node: prefix, the --no-experimental-sqlite flag, and one upstream-conditional skip in the backup test.
• darwin skips more than this. The subtests that need a feature Apple's system libsqlite3 omits (percentile(), geopoly, rbu, load_extension) gate on a runtime sqlite_compileoption_used probe of the loaded library, so they skip there rather than run; pointing Database.setCustomSQLite() at a full-featured build makes them execute. The counts above are Linux x64, where the bundled amalgamation is linked.
• test/js/node/sqlite/node-sqlite.test.ts, test/js/bun/sqlite/, test/js/sql/sqlite-sql.test.ts, test/js/node/process/process.test.js, test/js/node/module/node-module-module.test.js, and test/regression/issue/25707.test.ts pass with the bumped SQLite.

Fixes from review

• Exit-time close for unclosed databases. JSDatabaseSync handles live only as GC cells and Bun does not destruct the VM on a normal exit, so an unclosed file-backed database never reached sqlite3_close_v2() and its WAL was never checkpointed — unlike Node (~DatabaseSync on environment teardown) and bun:sqlite. open() now registers the handle (mapped to its owning JSC::VM*, captured on the owning thread) in a registry mirroring bun:sqlite's, closeInternal() unregisters it, and Bun__closeAllNodeSqliteDatabasesForTermination() walks it from the same exit-handler call site. The exit walk filters on the stored VM pointer, so it never dereferences a cell another thread's heap may be sweeping, and is realm-agnostic (node:vm contexts, bun --hot reload globals). Busy connections — process.exit() called from inside a UDF/authorizer with sqlite3_step() still on the stack — are skipped by both the walker and the destructor, since closing them is the same UAF a busy close() refuses. On that destructor branch the non-SQLite bookkeeping still runs: each tracked session record is flagged dbGone (so ~JSNodeSqliteSession never follows its raw pointer into the now-swept database cell) and the handle is unregistered. Because sqlite3_close_v2 only zombifies a connection that still has un-finalized statements (deferring the checkpoint to a finalize that never comes), the walker first runs an explicit SQLITE_CHECKPOINT_TRUNCATE so the data always lands in the main file; in that case the emptied -wal/-shm files still exist, since truly closing would require centrally finalizing statements that ~JSStatementSync later finalizes again. Two spawned regression tests cover the exec-only shape (sidecars removed) and the prepare-held shape (no un-checkpointed data stranded in a -wal).
• 64-bit lengths for bind/result. sqlite3_bind_text/blob and sqlite3_result_text/blob take an int length, so a size_t over INT_MAX wrapped to a negative or small value (undefined behaviour for the 32-bit API, or silent truncation). Switched to the *64 variants, which check the un-truncated length against SQLITE_LIMIT_LENGTH and fail with a clean SQLITE_TOOBIG. sqlite3changeset_apply has no *64 variant, so it gets an explicit size guard before the (now provably in-range) narrowing. This has no CI-constructible test — the trigger needs a >2 GiB allocation — and no observable effect for any input SQLite accepts (SQLITE_MAX_LENGTH caps well below 2³¹); the existing bind/result suite covers every swapped call site.

Not vendored on purpose: test-permission-sqlite-load-extension.js (requires Node's --permission model) and test-webstorage-without-sqlite.js (covers Node's webstorage global, not node:sqlite).

Binary size

darwin: unchanged (dlopen system libsqlite3, same as bun:sqlite). Linux/Windows: +~200 KB from the six new SQLITE_ENABLE_* compile defines.

macOS caveat

Bun uses the system libsqlite3.dylib on macOS. loadExtension() and percentile()/geopoly/rbu (and the session extension on older macOS) require pointing at a full-featured build via Database.setCustomSQLite().

Deliberate divergences from Node v26.3.0

Each is commented at its site in NodeSqlite.cpp:

• A failed sqlite3_step() exhausts the iterator. Node neither resets nor marks the iterator done, so catching the error and calling next() again silently re-yields from row 1 (SQLite auto-resets a halted statement). We reset and mark it done.
• iterate()'s return() on a finalized statement is a no-op. Node throws ERR_INVALID_STATE. Throwing there turns a benign for (r of stmt.iterate()) { db.close(); break; } into an exception, because for-of runs IteratorClose on break.
• return() only resets the statement if the iterator still owns it. Node resets unconditionally, which rewinds a newer iterator's cursor when one has since taken over the statement.
• The TagStore prepares with sqlite3_prepare_v3(SQLITE_PREPARE_PERSISTENT) where Node uses prepare_v2. Cached statements are exactly the long-lived reused case the flag documents; the hint is allocator-only and not observable.

Test plan

• CI green on all platforms
• bun test --config=bunfig.node-test.toml ./test/js/node/test/parallel/test-sqlite-session.js passes (covers the malformed-changeset fix from the SQLite bump)
• bun test test/js/node/sqlite/node-sqlite.test.ts and bun test test/js/bun/sqlite/ pass (regression coverage for the bundled SQLite update and the exit-time close)

Fixes #31402
Fixes #20412

(Not marking #24255 as fixed: the MockTracker itself landed on main separately; this PR only makes TestContext.mock return it so the sqlite tests can use t.mock.fn().)

---

no test proof · iteration 5 · 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 test/js/node/process/process.test.js test/js/node/sqlite/node-sqlite.test.ts

[robobun]

^{Updated 4:45 PM PT - Jul 16th, 2026}

⏳ @robobun, your commit 2546808 is still building in Build #74185, but has 3 failures so far (All Failures):

• test/js/node/test/parallel/test-worker-message-port-transfer-terminate.js - SIGABRT on 🐧 13 x64-asan
• test/js/web/timers/timer-heap-race.test.ts - pid 15885 sigabrt on 🐧 13 x64-asan
• test/cli/install/bun-create.test.ts - code 1 on 🪟 11 aarch64
• test/cli/install/bun-create.test.ts - code 1 on 🪟 2019 x64-baseline
• test/cli/install/bun-create.test.ts - code 1 on 🪟 2019 x64
• test/cli/install/bun-create.test.ts - pid 1952 error: addresssanitizer on 🐧 13 x64-asan

[github-actions]

Found 3 issues this PR may fix:

1. node:sqlite not implemented in Bun — forces dual-runtime code to fork imports #31402 - Directly implements the node:sqlite module, resolving the incompatibility that forces dual-runtime codebases to fork imports
2. Add support for node:sqlite #20412 - Adds node:sqlite as a builtin module backed by Bun's SQLite engine, exactly what this issue requests
3. Support node:test mock #24255 - Partial implementation of mock.fn() / MockTracker / MockFunctionContext in node:test, addressing the core API requested in this issue

If this is helpful, copy the block below into the PR description to auto-close these issues on merge.

Fixes #31402
Fixes #20412
Fixes #24255

🤖 Generated with Claude Code

[github-actions]

This PR may be a duplicate of:

1. node:sqlite: implement the complete API (xi58t8) #29821 - Also implements the full node:sqlite module with the same C++ classes (DatabaseSync, StatementSync, session/changeset API); PR node:sqlite: implement the module and pass the Node v26.3.0 test suite #32498 states it builds on node:sqlite: implement the complete API (xi58t8) #29821's code but node:sqlite: implement the complete API (xi58t8) #29821 remains open and unmerged

🤖 Generated with Claude Code

[cirospaciari]

Not a coincidence — this PR includes #29821's branch as a merge (its C++ implementation is unchanged) and adds what it still needed to land on current main: registration in the Rust module-resolver tables, a bundled SQLite 3.53.2 update (fixes a crash on malformed changesets that the v26.3.0 test suite exercises), the SQLITE_ENABLE_PERCENTILE define, and the vendored test files synced to the Node v26.3.0 tag. If this one merges, #29821 can be closed as superseded.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Implements node:sqlite as a built-in module in Bun by upgrading the bundled SQLite amalgamation to 3.53.2 with expanded compile-time features and internal correctness improvements, adding C++ class bindings for DatabaseSync, StatementSync, sessions, limits, backup, and a tag store, wiring GC subspaces and lazy class structures, registering the module across all resolution tables, exposing process.versions.sqlite, improving the node:test mock shim, and providing a comprehensive test suite covering both Bun and Node.js compatibility scenarios.

Changes

node:sqlite built-in module implementation

Layer / File(s)	Summary
SQLite 3.53.2 upgrade and build config scripts/build/deps/sqlite.ts, scripts/build/unified.ts, src/jsc/bindings/sqlite/sqlite3.c, src/jsc/bindings/sqlite/sqlite3_local.h	Upgrades the bundled SQLite amalgamation from 3.53.0 to 3.53.2 with multiple internal improvements (string accumulation fallback paths, integer overflow detection, expression subtype propagation, FTS/Rtree height/bounds validation, session changeset retry logic with SQLITE_CHANGESETAPPLY_NOUPDATELOOP flag support). Adds compile-time feature flags SQLITE_ENABLE_SESSION, SQLITE_ENABLE_PREUPDATE_HOOK, SQLITE_ENABLE_DBSTAT_VTAB, SQLITE_ENABLE_GEOPOLY, SQLITE_ENABLE_RBU, and SQLITE_ENABLE_PERCENTILE to match Node.js feature parity. Makes the sqlite dependency unconditionally enabled instead of conditional on cfg.staticSqlite and marks NodeSqlite.cpp as a no-unify translation unit.
node:sqlite C++ class declarations src/jsc/bindings/sqlite/NodeSqlite.h	Declares the complete C++ bindings: DatabaseSyncOpenConfiguration with open-time options, JSDatabaseSync connection wrapper (lifecycle, open-generation tracking, session/authorizer/limits management), JSStatementSync prepared statement wrapper (binding, row-structure caching, BigInt/array/named-parameter flags), JSStatementSyncIterator, JSNodeSqliteSession session wrapper, JSNodeSqliteLimits with property override semantics for 11 named limits, JSNodeSqliteTagStore as LRU-cached prepared statement store, and createNodeSqliteConstants factory.
GC/VM wiring and double-close fix src/jsc/bindings/ZigGlobalObject.h, src/jsc/bindings/ZigGlobalObject.cpp, src/jsc/bindings/webcore/DOMIsoSubspaces.h, src/jsc/bindings/webcore/DOMClientIsoSubspaces.h, src/jsc/bindings/sqlite/JSSQLStatement.cpp	Adds six LazyClassStructure GC members to GlobalObject's FOR_EACH_GLOBALOBJECT_GC_MEMBER macro, implements lazy initialization in finishCreation with prototype/constructor setup for each class, declares matching IsoSubspace and GCClient::IsoSubspace members, and fixes Bun__closeAllSQLiteDatabasesForTermination to conditionally call sqlite3_close_v2 and null the handle to prevent use-after-free during VM teardown.
Module registration and process.versions.sqlite src/resolve_builtins/HardcodedModule.rs, src/resolve_builtins/HardcodedModule.zig, src/jsc/modules/_NativeModule.h, src/jsc/modules/NodeSqliteModule.h, src/jsc/modules/NodeModuleModule.cpp, src/jsc/bindings/isBuiltinModule.cpp, src/jsc/ErrorCode.rs, src/jsc/bindings/ErrorCode.ts, src/jsc/bindings/BunProcess.cpp	Registers node:sqlite with nodeEntryOnlyPrefix in both HardcodedModule tables (Rust and Zig), adds to the BUN_FOREACH_ESM_AND_CJS_NATIVE_MODULE macro, defines the NodeSqlite native module exporting DatabaseSync class, StatementSync class, constants object, and backup function with arity 2, adds node:sqlite to builtin module name lists, adds ERR_SQLITE_ERROR discriminant and alias to error code mappings, and exposes process.versions.sqlite via Bun__sqlite3_version().
node:test mock.fn() shim src/js/node/test.ts	Replaces the unimplemented mock() stub with MockTracker and MockFunctionContext classes supporting mock.fn() spy creation, call argument/context recording, callCount(), mockImplementation(), and resetCalls(); updates TestContext.mock to return the shared tracker instead of throwing.
Bun-specific node:sqlite tests test/js/node/sqlite/node-sqlite.test.ts, test/js/node/process/process.test.js, test/js/node/module/node-module-module.test.js	Adds comprehensive Bun test suite covering module detection, lifecycle, data type binding, UDF/aggregate registration, iteration, sessions/changesets, backup, authorizer, limits, serialize/deserialize, tag store, row-shape caching, defensive mode, and heap-use-after-free regression; updates process.versions and builtinModules assertions.
Node-compat parallel test suite and helpers test/js/node/test/parallel/test-sqlite-*.{js,mjs}, test/js/node/test/common/index.{js,mjs}, test/js/node/test/sqlite/next-db.js, test/js/node/test/sqlite/worker.js	Adds 16 parallel test files covering aggregate functions, authorizer, backup, config, custom functions, data types, database lifecycle, limits, named parameters, serialize/deserialize, sessions, statement columns/sync, template tag, timeout, transactions, and typed arrays; adds hasSQLite and skipIfSQLiteMissing helpers to common harness and nextDb path utility.
Regression test fixture update test/regression/issue/25707.test.ts	Updates issue 25707 fixtures to use node:quic instead of node:sqlite in CJS dynamic-import scenarios, since node:sqlite is now a real built-in.

Possibly related PRs

• oven-sh/bun#31830: Both PRs modify src/js/node/test.ts by implementing/reworking test.mock to support mock.fn() spies and call tracking.

Suggested reviewers

• dylan-conway

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR fully addresses both linked issues (#31402, #20412) by implementing the complete node:sqlite module reusing bun:sqlite, enabling code portability without conditional imports.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the node:sqlite implementation, SQLite upgrade, and related test additions; no unrelated modifications are present.
Title check	✅ Passed	The title clearly states the main change: adding node:sqlite and validating it against Node v26.3.0 tests.
Description check	✅ Passed	It covers the required 'what' and verification details, though the headings don't match the template exactly.

---

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

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/js/node/test.ts`:
- Around line 71-72: The reset() and restoreAll() methods in the test tracker
are currently empty implementations that do nothing, which means spy state is
never actually cleaned up even though these calls appear to succeed. Implement
these methods to actually reset and restore the tracker's internal spy state
respectively. Since the tracker instance returned at lines 162-166 is shared,
ensure these cleanup methods properly clear all tracked spies and restore their
original behavior instead of being no-op methods.
- Around line 51-52: The fn method accepts original and impl parameters without
validating that they are callable functions, causing errors to surface later at
the $apply method instead of immediately. Add validation guards at the beginning
of the fn method to check that both original and impl parameters are functions,
and throw an appropriate error if either is not callable. This should occur
before creating the MockFunctionContext instance to catch invalid inputs
upfront.

In `@src/jsc/bindings/sqlite/JSSQLStatement.cpp`:
- Around line 283-287: Replace the sqlite3_close(db->db) call with
sqlite3_close_v2(db->db) to properly defer cleanup in garbage-collected
environments. The sqlite3_close_v2() function always succeeds (no return-code
check needed) and marks unreferenceable connections as zombie connections for
cleanup during VM teardown, matching the pattern already used in
VersionSqlite3::release(). This ensures that when db->db is nulled on the
following line, the finalizer's cleanup path can still defer proper resource
release.

In `@src/jsc/bindings/sqlite/NodeSqlite.h`:
- Around line 162-173: The BusyScope struct can be accidentally copied or moved,
which would cause multiple instances to exist and each would decrement
m_busyDepth in their destructors, leading to counter underflow and bypassing
re-entrancy protection. Make BusyScope non-copyable and non-movable by
explicitly deleting the copy constructor, copy assignment operator, move
constructor, and move assignment operator. Add these deleted member function
declarations to the BusyScope struct definition.

In `@test/js/node/test/parallel/test-sqlite-session.js`:
- Line 607: The test `concurrent applyChangeset with workers` has an explicit
timeout of 120 seconds which violates the no-timeout rule. Remove the `{
timeout: 120_000 }` configuration from this test. Instead of extending the
timeout, reduce the test complexity by either decreasing the number of
iterations from 10 to 3-5, or splitting the test into separate test cases with
fewer workers per test to keep execution within the fast test budget without
requiring explicit timeouts.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8fa6b59e-be07-4812-aace-2c53082f8f1b

📥 Commits

Reviewing files that changed from the base of the PR and between 454e3b2 and 6cab772.

📒 Files selected for processing (46)

• scripts/build/deps/sqlite.ts
• scripts/build/unified.ts
• src/js/node/test.ts
• src/jsc/bindings/BunProcess.cpp
• src/jsc/bindings/ErrorCode.ts
• src/jsc/bindings/ZigGlobalObject.cpp
• src/jsc/bindings/ZigGlobalObject.h
• src/jsc/bindings/isBuiltinModule.cpp
• src/jsc/bindings/sqlite/JSSQLStatement.cpp
• src/jsc/bindings/sqlite/NodeSqlite.cpp
• src/jsc/bindings/sqlite/NodeSqlite.h
• src/jsc/bindings/sqlite/sqlite3.c
• src/jsc/bindings/sqlite/sqlite3_local.h
• src/jsc/bindings/webcore/DOMClientIsoSubspaces.h
• src/jsc/bindings/webcore/DOMIsoSubspaces.h
• src/jsc/modules/NodeModuleModule.cpp
• src/jsc/modules/NodeSqliteModule.h
• src/jsc/modules/_NativeModule.h
• src/resolve_builtins/HardcodedModule.rs
• src/resolve_builtins/HardcodedModule.zig
• test/js/node/module/node-module-module.test.js
• test/js/node/process/process.test.js
• test/js/node/sqlite/node-sqlite.test.ts
• test/js/node/test/common/index.js
• test/js/node/test/common/index.mjs
• test/js/node/test/parallel/test-sqlite-aggregate-function.mjs
• test/js/node/test/parallel/test-sqlite-authz.js
• test/js/node/test/parallel/test-sqlite-backup.mjs
• test/js/node/test/parallel/test-sqlite-config.js
• test/js/node/test/parallel/test-sqlite-custom-functions.js
• test/js/node/test/parallel/test-sqlite-data-types.js
• test/js/node/test/parallel/test-sqlite-database-sync.js
• test/js/node/test/parallel/test-sqlite-limits.js
• test/js/node/test/parallel/test-sqlite-named-parameters.js
• test/js/node/test/parallel/test-sqlite-serialize.js
• test/js/node/test/parallel/test-sqlite-session.js
• test/js/node/test/parallel/test-sqlite-statement-sync-columns.js
• test/js/node/test/parallel/test-sqlite-statement-sync.js
• test/js/node/test/parallel/test-sqlite-template-tag.js
• test/js/node/test/parallel/test-sqlite-timeout.js
• test/js/node/test/parallel/test-sqlite-transactions.js
• test/js/node/test/parallel/test-sqlite-typed-array-and-data-view.js
• test/js/node/test/parallel/test-sqlite.js
• test/js/node/test/sqlite/next-db.js
• test/js/node/test/sqlite/worker.js
• test/regression/issue/25707.test.ts

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/jsc/ErrorCode.rs`:
- Around line 706-710: The error code index alignment between Rust and
TypeScript is broken. In the Rust ErrorCode.rs file, the SQLITE_ERROR constant
is defined at index 324 with a total COUNT of 325 entries, but the TypeScript
errors array only contains 321 entries with SQLITE_ERROR at index 320, and is
additionally missing 51 error codes that exist in Rust's CODE_STR. Update the
TypeScript errors array to include all 325 error code entries in the exact same
order as they appear in Rust's CODE_STR constant, ensuring that SQLITE_ERROR
ends up at index 324 to maintain the index-alignment invariant required by the
C++ memory-safety constraint referenced in the code comment.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 350fc0c6-eff9-4d06-bc58-2d58738e9b44

📥 Commits

Reviewing files that changed from the base of the PR and between 6cab772 and 4481f87.

📒 Files selected for processing (4)

• src/jsc/ErrorCode.rs
• src/jsc/bindings/ErrorCode.ts
• src/jsc/bindings/sqlite/JSSQLStatement.cpp
• src/jsc/bindings/sqlite/NodeSqlite.h

[claude]

I didn't find any bugs, but this is a large feature PR adding an entire new built-in module (node:sqlite) with ~4k lines of new native C++ JSC bindings, GC/IsoSubspace wiring, a bundled SQLite version bump, and module-resolver changes across Rust/Zig/C++ — it warrants a human review.

Extended reasoning...

Overview

This PR implements the node:sqlite built-in module end-to-end and brings it to parity with Node v26.3.0's test suite. It touches 47 files, including:

• New native bindings: NodeSqlite.h (758 lines) declaring six new JSDestructibleObject cell types (JSDatabaseSync, JSStatementSync, JSStatementSyncIterator, JSNodeSqliteSession, JSNodeSqliteLimits, JSNodeSqliteTagStore) plus their prototypes/constructors, and NodeSqlite.cpp (not shown in the diff header but referenced as a new no-unify TU) implementing them.
• GC/VM wiring: six new LazyClassStructure members in ZigGlobalObject.h, six initLater blocks in finishCreation, and matching IsoSubspace/GCClient::IsoSubspace slots in DOMIsoSubspaces.h / DOMClientIsoSubspaces.h.
• Module registration: HardcodedModule.rs, HardcodedModule.zig, _NativeModule.h, NodeModuleModule.cpp, isBuiltinModule.cpp, NodeSqliteModule.h.
• Bundled SQLite bump 3.53.0 → 3.53.2: large amalgamation diff in sqlite3.c / sqlite3_local.h (upstream-generated), plus six new compile-time SQLITE_ENABLE_* flags and making the sqlite dep unconditionally built.
• bun:sqlite teardown fix: Bun__closeAllSQLiteDatabasesForTermination now uses sqlite3_close_v2 and nulls the handle.
• node:test shim: a minimal MockTracker/MockFunctionContext so vendored Node tests using t.mock.fn() work.
• Error-code table append: ERR_SQLITE_ERROR added at the end of ErrorCode.ts and mirrored in ErrorCode.rs (index 324, COUNT bumped to 325).
• Tests: 19 vendored upstream test-sqlite-* files, a 1100-line Bun-native test, common/index.{js,mjs} helpers, and a regression-fixture swap from node:sqlite → node:quic.

Security risks

The implementation surface is memory-safety-sensitive: raw sqlite3* / sqlite3_stmt* / sqlite3_session* ownership across GC-managed wrappers, re-entrancy guards (BusyScope) protecting against close() from inside UDF/authorizer/option-getter callbacks, ABA-style open-generation tracking, and buffer-detach defenses around applyChangeset/deserialize. loadExtension is gated on allowExtension per Node semantics. The header design is careful and well-commented (e.g., sessions freed before sqlite3_close_v2, deleteTrackedSessions() invariant, structure-cache invalidation on schema change), and the test suite explicitly exercises several UAF/double-free scenarios under ASAN. I did not spot a concrete vulnerability, but the .cpp implementation is large and not fully visible in the diff, and any of these invariants being subtly wrong is a heap-UAF in production.

The SQLite 3.53.2 bump is an upstream patch release and includes the session-extension hardening the PR description calls out; the amalgamation diff is mechanical.

Level of scrutiny

High. This is a brand-new public API surface backed by thousands of lines of new native code that manages C resource lifetimes against a concurrent GC, wires new IsoSubspaces, and changes the module-resolution tables that every require() consults. It also incorporates another open PR (#29821) by merge. None of this is mechanical or pattern-following; it's exactly the kind of change a maintainer should read.

Other factors

• The bug-hunting system found nothing.
• My earlier inline nit (require('../common/index.mjs') in test-sqlite-config.js) was answered — the file is byte-identical to upstream Node v26.3.0, intentionally kept verbatim.
• The author already addressed two CodeRabbit findings in commit 4481f87 (BusyScope made non-copyable/non-movable; termination path switched to sqlite3_close_v2). The remaining CodeRabbit comments (mock.fn input validation, mock.reset/restoreAll no-ops, and the explicit per-test timeout on the worker-based session test) are minor and the author can decide whether to act on them.
• Test coverage is extensive (319 upstream subtests passing per the description, plus a dedicated Bun suite covering the GC/re-entrancy edge cases), which raises confidence but doesn't substitute for a human pass over the native lifetime management and the GC visit/subspace plumbing.

[cirospaciari]

CI status after the error-code alignment fix (build #63406): 282/286 jobs passed. Notes on the remaining 4 failed jobs — none are sqlite failures:

• binary-size: darwin binaries grow ~1.8 MB because sqlite3.c is now compiled on macOS too (it was dlopen-only there before). node:sqlite needs the bundled build — Apple's system libsqlite3 lacks the session extension and percentile() and disables extension loading; Node.js bundles SQLite for the same reason. Linux/Windows already linked the bundled copy (+~200 KB from the new feature defines). The latest push documents this in scripts/build/deps/sqlite.ts and tags the commit [skip size check] so the step records the delta as intentional; happy to revisit if reviewers prefer a different trade-off on macOS.
• test-net-connect-memleak.js (alpine x64 / x64-baseline): GC-collection assertion that also failed recently on unrelated branches (builds #63365, #63344); passes 5/5 locally on this branch. Not introduced here.
• test-tls-client-destroy-soon.js (macOS arm64): classified as pre-existing by the CI triage script (bun run ci:errors); the failing assertion (TLS bytesRead 2097152 vs 2048000) is in a path this PR doesn't touch.

[cirospaciari]

Build #63424 (latest commit): 281/286 jobs passed; the binary-size step now soft-fails as an intentional, documented increase. The 4 remaining job failures are all pre-existing or flaky and unrelated to this PR — puppeteer's Chrome download failing on the darwin-26 runner (next-pages tests), the pre-existing test-tls-client-destroy-soon on darwin-14, the cross-branch test-net-connect-memleak GC flake on Alpine, and a grpc-js flake. I've retried those 4 jobs to get a clean run.

[cirospaciari]

Build #63467 (latest commit, all review feedback applied): 281/286 jobs passed. The binary-size step soft-fails as the documented intentional increase, and the 4 hard-failed jobs are the same recurring flaky/pre-existing tests already triaged earlier in this PR — test-net-connect-memleak.js on the two Alpine shards (GC-timing flake also seen on unrelated branches), test-tls-client-destroy-soon.js on darwin-14 (pre-existing, also fails on main), and napi.test.ts on Windows (known flaky suite; this PR doesn't touch N-API). I've retried those 4 jobs to get a clean run.

[claude]

No further issues found after the latest fixes — all prior findings look addressed. Deferring to a human reviewer given the scope (~4.5k lines of new GC-sensitive JSC bindings in NodeSqlite.{cpp,h}) and the macOS binary-size trade-off you flagged.

Extended reasoning...

Overview

This PR implements the node:sqlite built-in module end-to-end: ~3.7k lines of new C++ in NodeSqlite.cpp plus an 821-line header defining six JSC cell types (JSDatabaseSync, JSStatementSync, iterator, session, limits, tag-store), lazy class-structure / IsoSubspace wiring in ZigGlobalObject, module registration across the Rust/Zig/C++ resolver tables, a bundled SQLite 3.53.0→3.53.2 amalgamation bump, six new compile-time feature defines, an always-on sqlite build (previously macOS dlopen-only), a minimal node:test mock.fn() shim, process.versions.sqlite, a new ERR_SQLITE_ERROR code, and ~6k lines of vendored Node v26.3.0 tests plus ~1.3k lines of Bun-authored tests.

Security risks

The implementation handles native resource lifetimes (sqlite3*, sqlite3_stmt*, sqlite3_session*) across JSC GC boundaries with re-entrant JS callbacks (UDFs, authorizers, filter/conflict handlers, option getters). Over the review cycle I flagged and the author fixed four memory-safety issues in this area: a Strong<>-rooted UDF cycle leak, an orphaned-session unbounded-growth leak, a deferred-xDestroy use-after-free on zombified connections, and a stale-iterator return() that silently rewound a live cursor. Buffer-detachment via hostile option getters is now guarded in both deserialize() and applyChangeset(). Extension loading is gated behind allowExtension; the authorizer hook is exposed. These are exactly the surfaces a human should re-read in NodeSqlite.cpp — the diff omits that file's body due to size.

Level of scrutiny

High. This is a large new native module with subtle GC/finalizer ordering invariants, and the review history demonstrates that getting those invariants right took several iterations. Separately, the author explicitly raised a policy question for reviewers: bundling sqlite3.c on macOS grows the darwin binaries by ~1.8 MB (documented and [skip size check]-tagged), and they noted they're "happy to revisit if reviewers prefer a different trade-off."

Other factors

All 15+ inline findings I raised across eight review rounds have been applied and resolved; the latest revision (commits through 4d19528) produced no new findings from the bug-hunting system. CI on the most recent build is green except for documented pre-existing/flaky failures unrelated to this change. Test coverage is extensive (319 vendored Node subtests passing plus Bun-authored regression tests for each fixed lifetime bug). The remaining work is human sign-off on the implementation design, the lifetime-management approach in NodeSqlite.cpp, and the binary-size trade-off.

[cirospaciari]

Final-state build #63476: 282/286 jobs passed; binary-size soft-fails as the documented intentional increase, and the only 3 hard-failed jobs are the recurring flakes already triaged (terminal.test.ts PTY timeout on darwin — also failing on 10+ unrelated branches — and test-net-connect-memleak.js on the two Alpine shards). Retried those 3 jobs to get the build green. Automated review has signed off ("no further issues"); ready for human review.

[cirospaciari]

Retry outcome on build #63476: the three flaky jobs failed again on the same tests, so the build stays at 282/286 with those two flake classes. For the record on why they're not from this PR: test-net-connect-memleak.js asserts a dropped socket is collected after one gc() — with conservative stack scanning that's sensitive to binary layout, it isn't exercising any sqlite code (node:sqlite isn't loaded there), it passed on the same Alpine shards on build #63456 of this PR, and it also fails on unrelated branches (e.g. #63365, #63344). The terminal.test.ts PTY timeout on darwin appears on 10+ recent unrelated branches. Happy to dig further if a maintainer suspects either is real.

[cirospaciari]

Brought the branch up to date with main (merge commit 13bdb62). Conflict notes: ERR_SQLITE_ERROR moved to the end of the error-code table after the codes main added (Rust mirror updated to index 327 / COUNT 328), and the PR's minimal node:test mock shim was dropped in favor of the MockTracker that landed on main — TestContext.mock now returns that tracker (dde35fb) since Node's sqlite tests drive callbacks through t.mock.fn(). Re-verified locally after the merge: all 19 vendored test-sqlite-* files pass, node-sqlite.test.ts (69) and bun:sqlite (80) pass, and the error-code mapping spot-checks are correct.

[cirospaciari]

Build #63956 (current head, post-main-merge): 284/286 — the only hard-failed job is darwin-26, which hit the known Next.js/puppeteer infra tests and the flaky s3 suite (binary-size soft-fails as the documented intentional increase). Retried that job; everything sqlite-related is green.

[cirospaciari]

Build #63956 is now green after the darwin-26 retry — 285/286 passed with only the binary-size soft-fail (documented intentional increase). CI is clean for the current head; ready for human review.

[dylan-conway]

@robobun we don't check for VMTraps NeedTermination like this anywhere. why is this needed?

[robobun]

It's needed because vm.hasTerminationRequest() won't work here: m_hasTerminationRequest is only flipped by VMTraps::handleTraps() (which then calls vm.setHasTerminationRequest()), and that only runs at a JS safepoint. Worker.terminate() → notifyNeedTermination() just does traps().fireTrap(NeedTermination), which sets the atomic trap bit cross-thread and nothing else.

Without a progress callback this loop is sqlite3_backup_step → sqlite3_sleep(25ms) → repeat, never entering JS, so there's no safepoint to promote the trap bit into m_hasTerminationRequest or a pending termination exception. Polling hasTerminationRequest() here would read false forever and the worker would hang on a permanently-BUSY destination. test/js/node/sqlite/node-sqlite.test.ts "Worker.terminate() interrupts a backup() spinning on a locked destination" covers exactly that (parent holds a BEGIN IMMEDIATE lock on the dest, worker backup-spins on BUSY, terminate() must land).

The other hasTerminationRequest() call sites in src/jsc/bindings/ (NodeVMModule, NodeVMScript, BunProcess) all check after returning from a JS call where a safepoint has already handled the trap, so the bool is set. This is the only spot that sits in a pure-C loop with no JS re-entry.

That said, if reading the trap bits directly is undesirable, the alternative is to call JSC::call into a no-op on each iteration (giving the trap a safepoint to land at, then checking scope.exception()), or to route this through Bun's hasTerminationRequest Rust helper via an extern "C" that also peeks the trap bits. Happy to switch the shape if you'd prefer one of those.

[dylan-conway]

@robobun is it not possible to run this as a task in the thread pool like nodejs?

[robobun]

Yes, and that's the right fix; the synchronous loop is a documented divergence, not a design choice. The header comment above jsNodeSqliteBackup says as much and names PhonyWorkQueue/ConcurrentCppTask__createAndRun as the in-tree precedent. Doing it would also remove the VMTraps::NeedTermination poll entirely, since the JS thread wouldn't be blocked.

What it needs, roughly mirroring Node's BackupJob:

• A heap-allocated job object holding sqlite3_backup*, the destination sqlite3*, rate, a Strong<JSPromise>, a Strong<JSDatabaseSync> (so the source cell and handle survive GC across the async gap), and a Strong<> for progressFn.
• Each tick: dispatch one sqlite3_backup_step via ConcurrentCppTask__createAndRun, then post back to the JS thread (ScriptExecutionContext::postTask) to run progress, check for db.close()/abort, and either re-dispatch or resolve/reject.
• BusyScope can't stay stack-scoped; the job would hold an explicit busy count (or a m_backupInFlight flag on JSDatabaseSync) that closeInternal() checks the same way it checks isBusy(), so a close during backup defers until the job finishes. Node handles this via BaseObjectPtr keeping the DatabaseSync alive.
• sqlite3_backup_step reading the source connection from a pool thread is safe under SQLITE_THREADSAFE=1 (serialized) since it takes the source handle's mutex internally; that's the same assumption Node makes.

The current sync version passes all 18 vendored test-sqlite-* files (the upstream suite doesn't actually exercise the "source db usable during backup" promise), which is why it shipped this way with the divergence noted. Happy to implement the threadpool version here if you'd rather not carry the divergence; it's ~200 lines but not risky. If you'd prefer to land this PR as-is and take that as a follow-up I can open one.

[claude]

I didn't find any bugs, but this is a large feature PR (~4,100 lines of new C++ in NodeSqlite.cpp plus bindings/build/test changes across 50 files) implementing node:sqlite, so it warrants a human review.

What was reviewed:

• Exception-scope handling and GC rooting in the new JSC classes (DatabaseSync/StatementSync/Session) — WriteBarriers visited, ThrowScopes checked.
• SQLite lifetime/ownership: statements and sessions tracked on the DB and finalized on close; lazy-load dlsym gating on macOS.
• Parameter binding paths for Buffer/TypedArray/BigInt and the changeset callback re-entrancy guards.
• Module registration in ZigGlobalObject/HardcodedModule and process.versions.sqlite wiring.

Extended reasoning...

Overview

This PR adds a native node:sqlite implementation to Bun. The core is a new 4,122-line C++ file (src/jsc/bindings/sqlite/NodeSqlite.cpp) plus a header, defining DatabaseSync, StatementSync, Session, backup, aggregate/user-defined functions, and changeset APIs. It touches ZigGlobalObject.{cpp,h}, IsoSubspace headers, BunProcess.cpp (process.versions.sqlite), isBuiltinModule.cpp, module registration (_NativeModule.h, NodeSqliteModule.h, HardcodedModule.rs), lazy_sqlite3.h and the vendored amalgamation config, build scripts, ErrorCode.ts, and ~20 test files ported from Node's parallel suite.

Security risks

The surface includes: user-controlled SQL passed to sqlite3_prepare_v2; loadExtension (dlopen of arbitrary paths, gated by an allowExtension flag); user JS callbacks invoked from inside SQLite (UDFs, aggregates, authorizer, changeset conflict handlers) with the attendant re-entrancy and GC hazards; and Buffer/TypedArray byte views bound into SQLite blobs. None of these are new attack surface relative to Node, but each is a place where a missed exception check, a stale pointer after a JS callback, or an unrooted JSValue would be exploitable.

Level of scrutiny

High. This is thousands of lines of new hand-written JSC C++ binding code interfacing with a C library, with manual memory management, WriteBarrier members, visitChildren implementations, and callbacks that cross the JS↔native boundary in both directions. Per the repo's own review guidance, memory safety in native bindings is the most-blocked PR category. It also adds fields to ZigGlobalObject and new IsoSubspaces.

Other factors

The PR ships an extensive Node-ported test suite (test-sqlite-*.js/mjs) which is a good signal, and the bug-hunting pass came back clean. But the sheer size and the number of independently risky subsystems (GC integration, dlopen-based lazy loading on macOS, session/changeset C API, build-system changes) put this well outside the bar for auto-approval. A maintainer should read at least the ownership/finalization paths in NodeSqlite.cpp and the ZigGlobalObject additions.