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

scripts/build/deps/sqlite.ts

@@ -1,20 +1,29 @@
 /**
- * SQLite — embedded SQL database. Backs bun:sqlite.
+ * SQLite — embedded SQL database. Backs bun:sqlite and node:sqlite.
  *
  * Source lives IN THE BUN REPO at src/jsc/bindings/sqlite/ — it's the
  * sqlite3 amalgamation (single .c file). No fetch step; tracked in git.
  *
- * Only built when staticSqlite=true. Otherwise bun dlopen()s the system
- * sqlite at runtime (macOS ships a recent sqlite; most linux distros don't,
- * so static is the default on linux).
+ * Always built: node:sqlite uses the bundled copy unconditionally (matching
+ * Node.js). bun:sqlite additionally supports dlopen()ing the system sqlite
+ * on macOS when staticSqlite=false (LAZY_LOAD_SQLITE=1), but NodeSqlite.cpp
+ * includes sqlite3_local.h directly and links against these symbols on
+ * every platform.
+ *
+ * Bundling on macOS (previously dlopen-only there) grows the darwin binaries
+ * by ~1.8 MB. That is the cost of node:sqlite parity: Apple's system
+ * libsqlite3 ships without the session extension or percentile() and with
+ * extension loading disabled, so the bundled build is required — Node.js
+ * bundles SQLite for the same reason. Linux/Windows already linked the
+ * bundled copy.
  */
 
 import type { Dependency } from "../source.ts";
 
 export const sqlite: Dependency = {
   name: "sqlite",
 
-  enabled: cfg => cfg.staticSqlite,
+  enabled: () => true,
 
   source: () => ({
     kind: "in-tree",
@@ -36,6 +45,16 @@ export const sqlite: Dependency = {
       SQLITE_ENABLE_MATH_FUNCTIONS: 1,
       SQLITE_ENABLE_UPDATE_DELETE_LIMIT: 1,
       SQLITE_UDL_CAPABLE_PARSER: 1,
+      // node:sqlite exposes createSession/applyChangeset + columns()
+      // metadata. Match Node.js's compile-time feature set so those
+      // APIs work identically. PREUPDATE_HOOK is a prerequisite for the
+      // session extension.
+      SQLITE_ENABLE_SESSION: 1,
+      SQLITE_ENABLE_PREUPDATE_HOOK: 1,
+      SQLITE_ENABLE_DBSTAT_VTAB: 1,
+      SQLITE_ENABLE_GEOPOLY: 1,
+      SQLITE_ENABLE_RBU: 1,
+      SQLITE_ENABLE_PERCENTILE: 1,
     },
     cflags: [
       "-Wno-incompatible-pointer-types-discards-qualifiers",

scripts/build/unified.ts

@@ -72,6 +72,7 @@ const noUnify: readonly string[] = [
   "src/jsc/bindings/webcore/JSDOMPromiseDeferred.cpp",
   "src/jsc/bindings/webcore/JSMessageEventCustom.cpp",
   "src/jsc/bindings/sqlite/JSSQLStatement.cpp",
+  "src/jsc/bindings/sqlite/NodeSqlite.cpp",
 
   // WebKit-derived crypto algorithm impls share file-static helper names
   // (`aesAlgorithm`, `cryptEncrypt`, `ALG128`, `IVSIZE`, ...) — upstream

src/js/node/test.ts

@@ -12,10 +12,72 @@ function run() {
   throwNotImplemented("run()", 5090, "Use `bun:test` in the interim.");
 }
 
-function mock() {
-  throwNotImplemented("mock()", 5090, "Use `bun:test` in the interim.");
+// Minimal `mock` tracker — enough for Node's own test suite (notably
+// test/parallel/test-sqlite-*.{js,mjs}) which only uses `mock.fn()`,
+// `spy.mock.calls[i].arguments`, and `spy.mock.callCount()`. The full
+// MockTracker API (timers, getters, method mocking, restore/reset) is
+// still #5090.
+class MockFunctionContext {
+  calls: { arguments: unknown[]; result?: unknown; error?: unknown; this: unknown }[];
+  #impl: Function;
+  constructor(impl: Function) {
+    this.calls = [];
+    this.#impl = impl;
+  }
+  callCount() {
+    return this.calls.length;
+  }
+  mockImplementation(impl: Function) {
+    this.#impl = impl;
+  }
+  resetCalls() {
+    this.calls.length = 0;
+  }
+  _invoke(thisArg: unknown, args: unknown[]) {
+    const record: any = { arguments: args, this: thisArg };
+    try {
+      record.result = this.#impl.$apply(thisArg, args);
+      this.calls.push(record);
+      return record.result;
+    } catch (e) {
+      record.error = e;
+      this.calls.push(record);
+      throw e;
+    }
+  }
+}
+
+class MockTracker {
+  fn(original: Function = kDefaultFunction, impl: Function = original) {
+    const ctx = new MockFunctionContext(impl);
+    function spy(this: unknown, ...args: unknown[]) {
+      return ctx._invoke(this, args);
+    }
+    Object.defineProperty(spy, "mock", { value: ctx, enumerable: true });
+    // Preserve .length so code that inspects the spy's declared arity
+    // (sqlite's aggregate() infers varargs from it) sees the original.
+    Object.defineProperty(spy, "length", { value: original.length, configurable: true });
+    return spy;
+  }
+  method() {
+    throwNotImplemented("mock.method()", 5090, "Use `bun:test` in the interim.");
+  }
+  getter() {
+    throwNotImplemented("mock.getter()", 5090, "Use `bun:test` in the interim.");
+  }
+  setter() {
+    throwNotImplemented("mock.setter()", 5090, "Use `bun:test` in the interim.");
+  }
+  reset() {}
+  restoreAll() {}
+  get timers() {
+    throwNotImplemented("mock.timers", 5090, "Use `bun:test` in the interim.");
+    return undefined;
+  }
 }
 
+const mock = new MockTracker();
+
 function fileSnapshot(_value: unknown, _path: string, _options: { serializers?: Function[] } = kEmptyObject) {
   throwNotImplemented("fileSnapshot()", 5090, "Use `bun:test` in the interim.");
 }
@@ -98,8 +160,10 @@ class TestContext {
   }
 
   get mock() {
-    throwNotImplemented("mock", 5090, "Use `bun:test` in the interim.");
-    return undefined;
+    // Node gives each TestContext its own tracker so `t.after` can
+    // restore; the shim is stateless enough that sharing one is fine
+    // for now (nothing to restore when only fn() is implemented).
+    return mock;
   }
 
   runOnly(_value?: boolean) {

src/jsc/ErrorCode.rs

@@ -703,9 +703,11 @@ impl ErrorCode {
     pub const TLS_ALPN_CALLBACK_INVALID_RESULT: ErrorCode = ErrorCode(322);
     /// `ERR_PROXY_TUNNEL` (instanceof Error)
     pub const PROXY_TUNNEL: ErrorCode = ErrorCode(323);
+    /// `ERR_SQLITE_ERROR` (instanceof Error)
+    pub const SQLITE_ERROR: ErrorCode = ErrorCode(324);
 
     /// == C++ `NODE_ERROR_COUNT`.
-    pub const COUNT: u16 = 324;
+    pub const COUNT: u16 = 325;
 }
 
 // ──────────────────────────────────────────────────────────────────────────
@@ -1071,6 +1073,7 @@ impl ErrorCode {
     pub const ERR_SECRETS_INTERACTION_REQUIRED: ErrorCode = ErrorCode::SECRETS_INTERACTION_REQUIRED;
     pub const ERR_HTTP2_GOAWAY_SESSION: ErrorCode = ErrorCode::HTTP2_GOAWAY_SESSION;
     pub const ERR_PROXY_TUNNEL: ErrorCode = ErrorCode::PROXY_TUNNEL;
+    pub const ERR_SQLITE_ERROR: ErrorCode = ErrorCode::SQLITE_ERROR;
 
     // NOTE: `ERR_SYSTEM_ERROR` / `ERR_CHILD_CLOSED_BEFORE_REPLY` intentionally
     // do NOT live here. They belong to the unrelated enum
@@ -1412,6 +1415,7 @@ static CODE_STR: [&str; ErrorCode::COUNT as usize] = [
     "ERR_HTTP2_GOAWAY_SESSION",
     "ERR_TLS_ALPN_CALLBACK_INVALID_RESULT",
     "ERR_PROXY_TUNNEL",
+    "ERR_SQLITE_ERROR",
 ];
 
 // ──────────────────────────────────────────────────────────────────────────

src/jsc/bindings/BunProcess.cpp

@@ -167,6 +167,7 @@ extern "C" bool Bun__GlobalObject__connectedIPC(JSGlobalObject*);
 extern "C" bool Bun__GlobalObject__hasIPC(JSGlobalObject*);
 extern "C" bool Bun__ensureProcessIPCInitialized(JSGlobalObject*);
 extern "C" const char* Bun__githubURL;
+extern "C" const char* Bun__sqlite3_version();
 BUN_DECLARE_HOST_FUNCTION(Bun__Process__send);
 
 extern "C" void Process__emitDisconnectEvent(Zig::GlobalObject* global);
@@ -254,6 +255,7 @@ static JSValue constructVersions(VM& vm, JSObject* processObject)
 
     object->putDirect(vm, JSC::Identifier::fromString(vm, "icu"_s), JSValue(JSC::jsOwnedString(vm, String(ASCIILiteral::fromLiteralUnsafe(U_ICU_VERSION)))), 0);
     object->putDirect(vm, JSC::Identifier::fromString(vm, "unicode"_s), JSValue(JSC::jsOwnedString(vm, String(ASCIILiteral::fromLiteralUnsafe(U_UNICODE_VERSION)))), 0);
+    object->putDirect(vm, JSC::Identifier::fromString(vm, "sqlite"_s), JSValue(JSC::jsOwnedString(vm, String(ASCIILiteral::fromLiteralUnsafe(Bun__sqlite3_version())))), 0);
 
 #define STRINGIFY_IMPL(x) #x
 #define STRINGIFY(x) STRINGIFY_IMPL(x)

src/jsc/bindings/ErrorCode.ts

@@ -335,5 +335,6 @@ const errors: ErrorCodeMapping = [
   ["ERR_HTTP2_GOAWAY_SESSION", Error],
   ["ERR_TLS_ALPN_CALLBACK_INVALID_RESULT", TypeError],
   ["ERR_PROXY_TUNNEL", Error],
+  ["ERR_SQLITE_ERROR", Error],
 ];
 export default errors;

src/jsc/bindings/ZigGlobalObject.cpp

@@ -42,6 +42,7 @@
 #include "JavaScriptCore/JSModuleNamespaceObjectInlines.h"
 #include "JavaScriptCore/JSModuleRecord.h"
 #include "JavaScriptCore/JSNativeStdFunction.h"
+#include "JavaScriptCore/JSIteratorPrototype.h"
 #include "JavaScriptCore/JSObject.h"
 #include "JavaScriptCore/JSObjectInlines.h"
 #include "JavaScriptCore/JSPromise.h"
@@ -131,6 +132,7 @@
 #include "JSReactElement.h"
 #include "BunMarkdownMeta.h"
 #include "JSSQLStatement.h"
+#include "sqlite/NodeSqlite.h"
 #include "JSStringDecoder.h"
 #include "JSTextEncoder.h"
 #include "JSTextEncoderStream.h"
@@ -2626,6 +2628,68 @@ void GlobalObject::finishCreation(VM& vm)
             init.setConstructor(constructor);
         });
 
+    m_JSDatabaseSyncClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            auto* prototype = Bun::JSDatabaseSyncPrototype::create(
+                init.vm, init.global, Bun::JSDatabaseSyncPrototype::createStructure(init.vm, init.global, init.global->objectPrototype()));
+            auto* structure = Bun::JSDatabaseSync::createStructure(init.vm, init.global, prototype);
+            auto* constructor = Bun::JSDatabaseSyncConstructor::create(
+                init.vm, init.global, Bun::JSDatabaseSyncConstructor::createStructure(init.vm, init.global, init.global->functionPrototype()), prototype);
+            init.setPrototype(prototype);
+            init.setStructure(structure);
+            init.setConstructor(constructor);
+        });
+
+    m_JSStatementSyncClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            auto* prototype = Bun::JSStatementSyncPrototype::create(
+                init.vm, init.global, Bun::JSStatementSyncPrototype::createStructure(init.vm, init.global, init.global->objectPrototype()));
+            auto* structure = Bun::JSStatementSync::createStructure(init.vm, init.global, prototype);
+            auto* constructor = Bun::JSStatementSyncConstructor::create(
+                init.vm, init.global, Bun::JSStatementSyncConstructor::createStructure(init.vm, init.global, init.global->functionPrototype()), prototype);
+            init.setPrototype(prototype);
+            init.setStructure(structure);
+            init.setConstructor(constructor);
+        });
+
+    m_JSStatementSyncIteratorClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            // Prototype chain: instance → iterator prototype → %IteratorPrototype%
+            // so for-of / spread / Iterator helpers all work out of the box.
+            auto* prototype = Bun::JSStatementSyncIteratorPrototype::create(
+                init.vm, init.global, Bun::JSStatementSyncIteratorPrototype::createStructure(init.vm, init.global, init.global->iteratorPrototype()));
+            auto* structure = Bun::JSStatementSyncIterator::createStructure(init.vm, init.global, prototype);
+            init.setPrototype(prototype);
+            init.setStructure(structure);
+        });
+
+    m_JSNodeSqliteSessionClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            auto* prototype = Bun::JSNodeSqliteSessionPrototype::create(
+                init.vm, init.global, Bun::JSNodeSqliteSessionPrototype::createStructure(init.vm, init.global, init.global->objectPrototype()));
+            auto* structure = Bun::JSNodeSqliteSession::createStructure(init.vm, init.global, prototype);
+            init.setPrototype(prototype);
+            init.setStructure(structure);
+        });
+
+    m_JSNodeSqliteLimitsClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            // Null prototype: Node's DatabaseSyncLimits is an ObjectTemplate
+            // with only the named-property handler, so Object.prototype is
+            // NOT on its chain and can't shadow a limit name.
+            auto* structure = Bun::JSNodeSqliteLimits::createStructure(init.vm, init.global, JSC::jsNull());
+            init.setStructure(structure);
+        });
+
+    m_JSNodeSqliteTagStoreClassStructure.initLater(
+        [](LazyClassStructure::Initializer& init) {
+            auto* prototype = Bun::JSNodeSqliteTagStorePrototype::create(
+                init.vm, init.global, Bun::JSNodeSqliteTagStorePrototype::createStructure(init.vm, init.global, init.global->objectPrototype()));
+            auto* structure = Bun::JSNodeSqliteTagStore::createStructure(init.vm, init.global, prototype);
+            init.setPrototype(prototype);
+            init.setStructure(structure);
+        });
+
     m_JSFFIFunctionStructure.initLater(
         [](LazyClassStructure::Initializer& init) {
             init.setStructure(Zig::JSFFIFunction::createStructure(init.vm, init.global, init.global->functionPrototype()));

src/jsc/bindings/ZigGlobalObject.h

@@ -564,6 +564,12 @@ class GlobalObject : public Bun::GlobalScope {
     V(private, LazyClassStructure, m_JSH3ResponseSinkClassStructure)                                         \
                                                                                                              \
     V(private, LazyClassStructure, m_JSStringDecoderClassStructure)                                          \
+    V(public, LazyClassStructure, m_JSDatabaseSyncClassStructure)                                            \
+    V(public, LazyClassStructure, m_JSStatementSyncClassStructure)                                           \
+    V(public, LazyClassStructure, m_JSStatementSyncIteratorClassStructure)                                   \
+    V(public, LazyClassStructure, m_JSNodeSqliteSessionClassStructure)                                       \
+    V(public, LazyClassStructure, m_JSNodeSqliteLimitsClassStructure)                                        \
+    V(public, LazyClassStructure, m_JSNodeSqliteTagStoreClassStructure)                                      \
     V(private, LazyClassStructure, m_NapiClassStructure)                                                     \
     V(private, LazyClassStructure, m_callSiteStructure)                                                      \
     V(public, LazyClassStructure, m_JSBufferClassStructure)                                                  \

src/jsc/bindings/isBuiltinModule.cpp

@@ -55,6 +55,7 @@ static constexpr ASCIILiteral builtinModuleNamesSortedLength[] = {
     "_tls_common"_s,
     "async_hooks"_s,
     "fs/promises"_s,
+    "node:sqlite"_s,
     "querystring"_s,
     "_http_client"_s,
     "_http_common"_s,

src/jsc/bindings/sqlite/JSSQLStatement.cpp

@@ -279,8 +279,16 @@ extern "C" void Bun__closeAllSQLiteDatabasesForTermination()
     auto& dbs = _instance->databases;
 
     for (auto& db : dbs) {
-        if (db->db)
-            sqlite3_close(db->db);
+        if (db->db) {
+            // close_v2: with unfinalized statements still alive, plain
+            // sqlite3_close() returns SQLITE_BUSY and leaves the connection
+            // open, which would leak it once the pointer is nulled below.
+            sqlite3_close_v2(db->db);
+            // Prevent VersionSqlite3::release() (invoked later by the GC
+            // finalizer during VM teardown) from closing the same handle
+            // again, which would be a use-after-free.
+            db->db = nullptr;
+        }
     }
 }