From 7b6bae96ddf42499c4b5ab67d2852b5ffc699c61 Mon Sep 17 00:00:00 2001
From: byteforge38 <stormcraft318@gmail.com>
Date: Tue, 27 Jan 2026 07:57:09 -0600
Subject: [PATCH 1/3] sqlite: add virtual table support via createModule()

---
 doc/api/sqlite.md                          |  93 ++++
 src/node_sqlite.cc                         | 591 +++++++++++++++++++++
 src/node_sqlite.h                          |  66 +++
 test/parallel/test-sqlite-virtual-table.js | 456 ++++++++++++++++
 4 files changed, 1206 insertions(+)
 create mode 100644 test/parallel/test-sqlite-virtual-table.js

diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
index 85ddfaa1f2d28d..eb2b6850ac3f17 100644
--- a/doc/api/sqlite.md
+++ b/doc/api/sqlite.md
@@ -605,6 +605,98 @@ console.log(allUsers);
 // ]
 ```
 
+### `database.createModule(name, options)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `name` {string} The name of the virtual table module. This name is used in
+  `CREATE VIRTUAL TABLE ... USING name` statements and as an eponymous table
+  name.
+* `options` {Object} Module configuration settings.
+  * `columns` {Array} An array of column definitions. Each element is an object
+    with the following properties:
+    * `name` {string} The name of the column.
+    * `type` {string} The declared type of the column. Must be one of
+      `'INTEGER'`, `'TEXT'`, `'REAL'`, `'BLOB'`, or `'ANY'`.
+    * `hidden` {boolean} If `true`, the column is hidden and acts as a
+      parameter for table-valued function usage. **Default:** `false`.
+  * `rows` {Function} A function called to produce rows when the virtual table
+    is queried. The function receives values for hidden columns (parameters) as
+    arguments, in the order they are defined. Must return an iterable (such as
+    an array or generator) where each element is an array of column values.
+  * `directOnly` {boolean} If `true`, the virtual table can only be used in
+    top-level SQL statements and cannot be used inside triggers or views.
+    **Default:** `false`.
+  * `useBigIntArguments` {boolean} If `true`, integer parameters passed to
+    `rows` are converted to `BigInt`s. **Default:** `false`.
+
+Registers a virtual table module with the database. This method is a wrapper
+around [`sqlite3_create_module_v2()`][]. Virtual tables allow JavaScript code
+to provide the backing data for SQL tables. The registered module can be used
+in two ways:
+
+* **Eponymous table**: Query the module name directly without creating a table
+  (e.g., `SELECT * FROM module_name`).
+* **Named virtual table**: Use `CREATE VIRTUAL TABLE t USING module_name` to
+  create a persistent virtual table.
+
+Hidden columns can be used to pass parameters to the `rows` function using
+table-valued function syntax (e.g., `SELECT * FROM module_name(param1, param2)`).
+
+```cjs
+const { DatabaseSync } = require('node:sqlite');
+
+const db = new DatabaseSync(':memory:');
+
+db.createModule('generate_series', {
+  columns: [
+    { name: 'value', type: 'INTEGER' },
+    { name: 'start', type: 'INTEGER', hidden: true },
+    { name: 'stop', type: 'INTEGER', hidden: true },
+    { name: 'step', type: 'INTEGER', hidden: true },
+  ],
+  *rows(start, stop, step) {
+    start ??= 0;
+    stop ??= 10;
+    step ??= 1;
+    for (let i = start; i <= stop; i += step) {
+      yield [i];
+    }
+  },
+});
+
+console.log(db.prepare('SELECT * FROM generate_series(1, 5, 1)').all());
+// Prints: [ { value: 1 }, { value: 2 }, { value: 3 }, { value: 4 }, { value: 5 } ]
+```
+
+```mjs
+import { DatabaseSync } from 'node:sqlite';
+
+const db = new DatabaseSync(':memory:');
+
+db.createModule('generate_series', {
+  columns: [
+    { name: 'value', type: 'INTEGER' },
+    { name: 'start', type: 'INTEGER', hidden: true },
+    { name: 'stop', type: 'INTEGER', hidden: true },
+    { name: 'step', type: 'INTEGER', hidden: true },
+  ],
+  *rows(start, stop, step) {
+    start ??= 0;
+    stop ??= 10;
+    step ??= 1;
+    for (let i = start; i <= stop; i += step) {
+      yield [i];
+    }
+  },
+});
+
+console.log(db.prepare('SELECT * FROM generate_series(1, 5, 1)').all());
+// Prints: [ { value: 1 }, { value: 2 }, { value: 3 }, { value: 4 }, { value: 5 } ]
+```
+
 ### `database.createSession([options])`
 
 <!-- YAML
@@ -1494,6 +1586,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3_column_origin_name()`]: https://www.sqlite.org/c3ref/column_database_name.html
 [`sqlite3_column_table_name()`]: https://www.sqlite.org/c3ref/column_database_name.html
 [`sqlite3_create_function_v2()`]: https://www.sqlite.org/c3ref/create_function.html
+[`sqlite3_create_module_v2()`]: https://www.sqlite.org/c3ref/create_module.html
 [`sqlite3_create_window_function()`]: https://www.sqlite.org/c3ref/create_function.html
 [`sqlite3_db_filename()`]: https://sqlite.org/c3ref/db_filename.html
 [`sqlite3_exec()`]: https://www.sqlite.org/c3ref/exec.html
diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index 4fad22c618900d..a5527afc130965 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -665,6 +665,336 @@ void UserDefinedFunction::xDestroy(void* self) {
   delete static_cast<UserDefinedFunction*>(self);
 }
 
+// ---------------------------------------------------------------------------
+// VirtualTableModule
+// ---------------------------------------------------------------------------
+
+VirtualTableModule::VirtualTableModule(Environment* env,
+                                       DatabaseSync* db,
+                                       Local<Function> rows_fn,
+                                       std::string&& schema_sql,
+                                       int num_columns,
+                                       std::vector<int>&& hidden_col_indices,
+                                       bool use_bigint_args,
+                                       bool direct_only)
+    : env_(env),
+      db_(db),
+      rows_fn_(env->isolate(), rows_fn),
+      schema_sql_(std::move(schema_sql)),
+      num_columns_(num_columns),
+      hidden_col_indices_(std::move(hidden_col_indices)),
+      use_bigint_args_(use_bigint_args),
+      direct_only_(direct_only) {
+  // Build mapping from schema column index to row array index.
+  // Visible columns are numbered sequentially; hidden columns map to -1.
+  col_index_map_.assign(num_columns, 0);
+  for (int idx : hidden_col_indices_) {
+    col_index_map_[idx] = -1;
+  }
+  int visible_idx = 0;
+  for (int i = 0; i < num_columns; i++) {
+    if (col_index_map_[i] < 0) {
+      continue;
+    }
+    col_index_map_[i] = visible_idx++;
+  }
+}
+
+VirtualTableModule::~VirtualTableModule() {}
+
+int VirtualTableModule::xCreate(sqlite3* db,
+                                void* pAux,
+                                int argc,
+                                const char* const* argv,
+                                sqlite3_vtab** ppVTab,
+                                char** pzErr) {
+  VirtualTableModule* mod = static_cast<VirtualTableModule*>(pAux);
+
+  int rc = sqlite3_declare_vtab(db, mod->schema_sql_.c_str());
+  if (rc != SQLITE_OK) {
+    *pzErr = sqlite3_mprintf("%s", sqlite3_errmsg(db));
+    return rc;
+  }
+
+  if (mod->direct_only_) {
+    sqlite3_vtab_config(db, SQLITE_VTAB_DIRECTONLY);
+  }
+
+  NodeVTab* vtab = new NodeVTab();
+  memset(&vtab->base, 0, sizeof(vtab->base));
+  vtab->module = mod;
+  *ppVTab = &vtab->base;
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xBestIndex(sqlite3_vtab* pVTab,
+                                   sqlite3_index_info* pInfo) {
+  NodeVTab* vtab = reinterpret_cast<NodeVTab*>(pVTab);
+  VirtualTableModule* mod = vtab->module;
+  int num_hidden = static_cast<int>(mod->hidden_col_indices_.size());
+  int argv_index = 0;
+  int idx_num = 0;
+
+  // For each hidden column (parameter), look for a usable EQ constraint.
+  // Use idxNum as a bitmask to communicate which hidden columns have
+  // constraints, so xFilter can assign argv values to the correct parameters.
+  for (int hidden_idx = 0; hidden_idx < num_hidden; hidden_idx++) {
+    int col = mod->hidden_col_indices_[hidden_idx];
+
+    for (int i = 0; i < pInfo->nConstraint; i++) {
+      if (pInfo->aConstraint[i].iColumn == col &&
+          pInfo->aConstraint[i].usable &&
+          pInfo->aConstraint[i].op == SQLITE_INDEX_CONSTRAINT_EQ) {
+        argv_index++;
+        pInfo->aConstraintUsage[i].argvIndex = argv_index;
+        pInfo->aConstraintUsage[i].omit = 1;
+        idx_num |= (1 << hidden_idx);
+        break;
+      }
+    }
+  }
+
+  pInfo->idxNum = idx_num;
+  pInfo->estimatedCost = 1000000.0;
+  pInfo->estimatedRows = 1000;
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xDisconnect(sqlite3_vtab* pVTab) {
+  NodeVTab* vtab = reinterpret_cast<NodeVTab*>(pVTab);
+  delete vtab;
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xDestroy(sqlite3_vtab* pVTab) {
+  return xDisconnect(pVTab);
+}
+
+int VirtualTableModule::xOpen(sqlite3_vtab* pVTab,
+                              sqlite3_vtab_cursor** ppCursor) {
+  NodeVTab* vtab = reinterpret_cast<NodeVTab*>(pVTab);
+  NodeVTabCursor* cursor = new NodeVTabCursor();
+  memset(&cursor->base, 0, sizeof(cursor->base));
+  cursor->module = vtab->module;
+  cursor->rowid = 0;
+  cursor->done = true;
+  *ppCursor = &cursor->base;
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xClose(sqlite3_vtab_cursor* pCursor) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  cursor->iterator.Reset();
+  cursor->current_row.Reset();
+  delete cursor;
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xFilter(sqlite3_vtab_cursor* pCursor,
+                                int idxNum,
+                                const char* idxStr,
+                                int argc,
+                                sqlite3_value** argv) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  VirtualTableModule* mod = cursor->module;
+  Environment* env = mod->env_;
+  Isolate* isolate = env->isolate();
+  HandleScope handle_scope(isolate);
+
+  cursor->rowid = 0;
+  cursor->done = false;
+  cursor->iterator.Reset();
+  cursor->current_row.Reset();
+
+  // Build arguments for rows() from hidden column constraint values.
+  // The idxNum bitmask (set in xBestIndex) indicates which hidden columns
+  // received EQ constraints. argv values are in order of the set bits.
+  int num_hidden = static_cast<int>(mod->hidden_col_indices_.size());
+  LocalVector<Value> js_args(isolate);
+  int argv_pos = 0;
+
+  for (int i = 0; i < num_hidden; i++) {
+    if ((idxNum & (1 << i)) && argv_pos < argc) {
+      sqlite3_value* sv = argv[argv_pos];
+      MaybeLocal<Value> js_val;
+      SQLITE_VALUE_TO_JS(
+          value, isolate, mod->use_bigint_args_, js_val, sv);
+      if (js_val.IsEmpty()) {
+        mod->db_->SetIgnoreNextSQLiteError(true);
+        return SQLITE_ERROR;
+      }
+      Local<Value> local;
+      if (!js_val.ToLocal(&local)) {
+        mod->db_->SetIgnoreNextSQLiteError(true);
+        return SQLITE_ERROR;
+      }
+      js_args.emplace_back(local);
+      argv_pos++;
+    } else {
+      js_args.emplace_back(Null(isolate));
+    }
+  }
+
+  // Call the rows() function.
+  auto recv = Undefined(isolate);
+  auto fn = mod->rows_fn_.Get(isolate);
+  MaybeLocal<Value> retval = fn->Call(
+      env->context(), recv, js_args.size(), js_args.data());
+  Local<Value> result;
+  if (!retval.ToLocal(&result)) {
+    mod->db_->SetIgnoreNextSQLiteError(true);
+    return SQLITE_ERROR;
+  }
+
+  // Get an iterator from the result. If the result has Symbol.iterator,
+  // call it. Otherwise, assume the result is already an iterator.
+  Local<Object> iterator_obj;
+  if (result->IsObject()) {
+    Local<Object> result_obj = result.As<Object>();
+    Local<Value> iter_method_val;
+    if (!result_obj->Get(env->context(), v8::Symbol::GetIterator(isolate))
+             .ToLocal(&iter_method_val)) {
+      mod->db_->SetIgnoreNextSQLiteError(true);
+      return SQLITE_ERROR;
+    }
+
+    if (iter_method_val->IsFunction()) {
+      MaybeLocal<Value> iter_result =
+          iter_method_val.As<Function>()->Call(
+              env->context(), result_obj, 0, nullptr);
+      Local<Value> iter_val;
+      if (!iter_result.ToLocal(&iter_val) || !iter_val->IsObject()) {
+        mod->db_->SetIgnoreNextSQLiteError(true);
+        return SQLITE_ERROR;
+      }
+      iterator_obj = iter_val.As<Object>();
+    } else {
+      // Assume result is already an iterator (has .next()).
+      iterator_obj = result_obj;
+    }
+  } else {
+    sqlite3_free(pCursor->pVtab->zErrMsg);
+    pCursor->pVtab->zErrMsg = sqlite3_mprintf(
+        "The \"options.rows\" function must return an iterable object");
+    return SQLITE_ERROR;
+  }
+
+  cursor->iterator.Reset(isolate, iterator_obj);
+
+  // Advance to the first row.
+  return xNext(pCursor);
+}
+
+int VirtualTableModule::xNext(sqlite3_vtab_cursor* pCursor) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  VirtualTableModule* mod = cursor->module;
+  Environment* env = mod->env_;
+  Isolate* isolate = env->isolate();
+  HandleScope handle_scope(isolate);
+
+  Local<Object> iterator = cursor->iterator.Get(isolate);
+
+  // Call iterator.next().
+  Local<Value> next_method_val;
+  if (!iterator
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(isolate, "next"))
+           .ToLocal(&next_method_val) ||
+      !next_method_val->IsFunction()) {
+    mod->db_->SetIgnoreNextSQLiteError(true);
+    return SQLITE_ERROR;
+  }
+
+  MaybeLocal<Value> next_result =
+      next_method_val.As<Function>()->Call(
+          env->context(), iterator, 0, nullptr);
+  Local<Value> next_val;
+  if (!next_result.ToLocal(&next_val) || !next_val->IsObject()) {
+    mod->db_->SetIgnoreNextSQLiteError(true);
+    return SQLITE_ERROR;
+  }
+
+  Local<Object> next_obj = next_val.As<Object>();
+
+  // Read "done" property.
+  Local<Value> done_val;
+  if (!next_obj->Get(env->context(), env->done_string())
+           .ToLocal(&done_val)) {
+    mod->db_->SetIgnoreNextSQLiteError(true);
+    return SQLITE_ERROR;
+  }
+
+  if (done_val->BooleanValue(isolate)) {
+    cursor->done = true;
+    cursor->current_row.Reset();
+  } else {
+    cursor->done = false;
+    cursor->rowid++;
+
+    // Read "value" property.
+    Local<Value> value_val;
+    if (!next_obj->Get(env->context(), env->value_string())
+             .ToLocal(&value_val)) {
+      mod->db_->SetIgnoreNextSQLiteError(true);
+      return SQLITE_ERROR;
+    }
+
+    cursor->current_row.Reset(isolate, value_val);
+  }
+
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xEof(sqlite3_vtab_cursor* pCursor) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  return cursor->done ? 1 : 0;
+}
+
+int VirtualTableModule::xColumn(sqlite3_vtab_cursor* pCursor,
+                                sqlite3_context* ctx,
+                                int i) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  VirtualTableModule* mod = cursor->module;
+  Environment* env = mod->env_;
+  Isolate* isolate = env->isolate();
+  HandleScope handle_scope(isolate);
+
+  // Hidden columns are not present in the row array.
+  if (i < 0 || i >= mod->num_columns_ || mod->col_index_map_[i] < 0) {
+    sqlite3_result_null(ctx);
+    return SQLITE_OK;
+  }
+
+  Local<Value> row = cursor->current_row.Get(isolate);
+  if (!row->IsObject()) {
+    sqlite3_result_null(ctx);
+    return SQLITE_OK;
+  }
+
+  Local<Object> row_obj = row.As<Object>();
+  Local<Value> col_val;
+  if (!row_obj->Get(env->context(), mod->col_index_map_[i])
+           .ToLocal(&col_val)) {
+    mod->db_->SetIgnoreNextSQLiteError(true);
+    sqlite3_result_error(ctx, "", 0);
+    return SQLITE_ERROR;
+  }
+
+  JSValueToSQLiteResult(isolate, ctx, col_val);
+  return SQLITE_OK;
+}
+
+int VirtualTableModule::xRowid(sqlite3_vtab_cursor* pCursor,
+                               sqlite3_int64* pRowid) {
+  NodeVTabCursor* cursor = reinterpret_cast<NodeVTabCursor*>(pCursor);
+  *pRowid = cursor->rowid;
+  return SQLITE_OK;
+}
+
+void VirtualTableModule::xDestroyModule(void* pAux) {
+  delete static_cast<VirtualTableModule*>(pAux);
+}
+
 DatabaseSync::DatabaseSync(Environment* env,
                            Local<Object> object,
                            DatabaseOpenConfiguration&& open_config,
@@ -1605,6 +1935,265 @@ void DatabaseSync::AggregateFunction(const FunctionCallbackInfo<Value>& args) {
   CHECK_ERROR_OR_THROW(env->isolate(), db, r, SQLITE_OK, void());
 }
 
+void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
+  DatabaseSync* db;
+  ASSIGN_OR_RETURN_UNWRAP(&db, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(env, !db->IsOpen(), "database is not open");
+
+  if (!args[0]->IsString()) {
+    THROW_ERR_INVALID_ARG_TYPE(env->isolate(),
+                               "The \"name\" argument must be a string.");
+    return;
+  }
+
+  if (!args[1]->IsObject()) {
+    THROW_ERR_INVALID_ARG_TYPE(env->isolate(),
+                               "The \"options\" argument must be an object.");
+    return;
+  }
+
+  Utf8Value name(env->isolate(), args[0].As<String>());
+  Local<Object> options = args[1].As<Object>();
+
+  // Extract columns array.
+  Local<Value> columns_v;
+  if (!options
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(env->isolate(), "columns"))
+           .ToLocal(&columns_v)) {
+    return;
+  }
+
+  if (!columns_v->IsArray()) {
+    THROW_ERR_INVALID_ARG_TYPE(
+        env->isolate(),
+        "The \"options.columns\" argument must be an array.");
+    return;
+  }
+
+  Local<Array> columns = columns_v.As<Array>();
+  uint32_t num_columns = columns->Length();
+
+  if (num_columns == 0) {
+    THROW_ERR_INVALID_ARG_VALUE(
+        env->isolate(),
+        "The \"options.columns\" array must not be empty.");
+    return;
+  }
+
+  // Extract rows function.
+  Local<Value> rows_v;
+  if (!options
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(env->isolate(), "rows"))
+           .ToLocal(&rows_v)) {
+    return;
+  }
+
+  if (!rows_v->IsFunction()) {
+    THROW_ERR_INVALID_ARG_TYPE(
+        env->isolate(),
+        "The \"options.rows\" argument must be a function.");
+    return;
+  }
+
+  Local<Function> rows_fn = rows_v.As<Function>();
+
+  // Extract optional boolean options.
+  bool direct_only = false;
+  Local<Value> direct_only_v;
+  if (!options
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(env->isolate(), "directOnly"))
+           .ToLocal(&direct_only_v)) {
+    return;
+  }
+
+  if (!direct_only_v->IsUndefined()) {
+    if (!direct_only_v->IsBoolean()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "The \"options.directOnly\" argument must be a boolean.");
+      return;
+    }
+    direct_only = direct_only_v.As<Boolean>()->Value();
+  }
+
+  bool use_bigint_args = false;
+  Local<Value> use_bigint_args_v;
+  if (!options
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(env->isolate(), "useBigIntArguments"))
+           .ToLocal(&use_bigint_args_v)) {
+    return;
+  }
+
+  if (!use_bigint_args_v->IsUndefined()) {
+    if (!use_bigint_args_v->IsBoolean()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "The \"options.useBigIntArguments\" argument must be a boolean.");
+      return;
+    }
+    use_bigint_args = use_bigint_args_v.As<Boolean>()->Value();
+  }
+
+  // Build CREATE TABLE schema SQL from columns.
+  std::string schema_sql = "CREATE TABLE x(";
+  std::vector<int> hidden_col_indices;
+
+  for (uint32_t i = 0; i < num_columns; i++) {
+    Local<Value> col_v;
+    if (!columns->Get(env->context(), i).ToLocal(&col_v)) {
+      return;
+    }
+
+    if (!col_v->IsObject()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "Each column in \"options.columns\" must be an object.");
+      return;
+    }
+
+    Local<Object> col = col_v.As<Object>();
+
+    // Get column name.
+    Local<Value> col_name_v;
+    if (!col->Get(env->context(), env->name_string()).ToLocal(&col_name_v)) {
+      return;
+    }
+
+    if (!col_name_v->IsString()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "The column \"name\" property must be a string.");
+      return;
+    }
+
+    Utf8Value col_name(env->isolate(), col_name_v.As<String>());
+
+    // Get column type.
+    Local<Value> col_type_v;
+    if (!col->Get(env->context(), env->type_string()).ToLocal(&col_type_v)) {
+      return;
+    }
+
+    if (!col_type_v->IsString()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "The column \"type\" property must be a string.");
+      return;
+    }
+
+    Utf8Value col_type(env->isolate(), col_type_v.As<String>());
+
+    // Get optional hidden flag.
+    bool hidden = false;
+    Local<Value> hidden_v;
+    if (!col->Get(env->context(),
+                  FIXED_ONE_BYTE_STRING(env->isolate(), "hidden"))
+             .ToLocal(&hidden_v)) {
+      return;
+    }
+
+    if (!hidden_v->IsUndefined()) {
+      if (!hidden_v->IsBoolean()) {
+        THROW_ERR_INVALID_ARG_TYPE(
+            env->isolate(),
+            "The column \"hidden\" property must be a boolean.");
+        return;
+      }
+      hidden = hidden_v.As<Boolean>()->Value();
+    }
+
+    if (hidden) {
+      hidden_col_indices.push_back(static_cast<int>(i));
+    }
+
+    if (i > 0) {
+      schema_sql += ", ";
+    }
+
+    // Validate column type against allowed SQLite type names.
+    std::string type_str = col_type.ToString();
+    if (type_str != "INTEGER" && type_str != "TEXT" && type_str != "REAL" &&
+        type_str != "BLOB" && type_str != "ANY") {
+      THROW_ERR_INVALID_ARG_VALUE(
+          env->isolate(),
+          "The column \"type\" property must be one of "
+          "'INTEGER', 'TEXT', 'REAL', 'BLOB', or 'ANY'.");
+      return;
+    }
+
+    // Quote column name to prevent SQL injection.
+    schema_sql += "\"";
+    std::string name_str = col_name.ToString();
+    for (char c : name_str) {
+      if (c == '"') {
+        schema_sql += "\"\"";
+      } else {
+        schema_sql += c;
+      }
+    }
+    schema_sql += "\" ";
+    schema_sql += type_str;
+
+    if (hidden) {
+      schema_sql += " HIDDEN";
+    }
+  }
+
+  schema_sql += ")";
+
+  // Create the static module definition.
+  // This must be static or heap-allocated because SQLite retains a pointer.
+  static sqlite3_module vtab_module_def = {
+      1,                                // iVersion
+      VirtualTableModule::xCreate,      // xCreate
+      VirtualTableModule::xCreate,      // xConnect (same as xCreate)
+      VirtualTableModule::xBestIndex,   // xBestIndex
+      VirtualTableModule::xDisconnect,  // xDisconnect
+      VirtualTableModule::xDestroy,     // xDestroy
+      VirtualTableModule::xOpen,        // xOpen
+      VirtualTableModule::xClose,       // xClose
+      VirtualTableModule::xFilter,      // xFilter
+      VirtualTableModule::xNext,        // xNext
+      VirtualTableModule::xEof,         // xEof
+      VirtualTableModule::xColumn,      // xColumn
+      VirtualTableModule::xRowid,       // xRowid
+      nullptr,                          // xUpdate
+      nullptr,                          // xBegin
+      nullptr,                          // xSync
+      nullptr,                          // xCommit
+      nullptr,                          // xRollback
+      nullptr,                          // xFindFunction
+      nullptr,                          // xRename
+      nullptr,                          // xSavepoint
+      nullptr,                          // xRelease
+      nullptr,                          // xRollbackTo
+      nullptr,                          // xShadowName
+      nullptr,                          // xIntegrity
+  };
+
+  VirtualTableModule* vtab_mod =
+      new VirtualTableModule(env,
+                             db,
+                             rows_fn,
+                             std::move(schema_sql),
+                             num_columns,
+                             std::move(hidden_col_indices),
+                             use_bigint_args,
+                             direct_only);
+
+  int r = sqlite3_create_module_v2(db->connection_,
+                                   *name,
+                                   &vtab_module_def,
+                                   vtab_mod,
+                                   VirtualTableModule::xDestroyModule);
+  CHECK_ERROR_OR_THROW(env->isolate(), db, r, SQLITE_OK, void());
+}
+
 void DatabaseSync::CreateSession(const FunctionCallbackInfo<Value>& args) {
   std::string table;
   std::string db_name = "main";
@@ -3464,6 +4053,8 @@ static void Initialize(Local<Object> target,
       isolate, db_tmpl, "loadExtension", DatabaseSync::LoadExtension);
   SetProtoMethod(
       isolate, db_tmpl, "setAuthorizer", DatabaseSync::SetAuthorizer);
+  SetProtoMethod(
+      isolate, db_tmpl, "createModule", DatabaseSync::CreateModule);
   SetSideEffectFreeGetter(isolate,
                           db_tmpl,
                           FIXED_ONE_BYTE_STRING(isolate, "isOpen"),
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
index 515660bf98999b..432576b4c63997 100644
--- a/src/node_sqlite.h
+++ b/src/node_sqlite.h
@@ -148,6 +148,7 @@ class DatabaseSync : public BaseObject {
   static void EnableDefensive(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void LoadExtension(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetAuthorizer(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void CreateModule(const v8::FunctionCallbackInfo<v8::Value>& args);
   static int AuthorizerCallback(void* user_data,
                                 int action_code,
                                 const char* param1,
@@ -198,6 +199,7 @@ class DatabaseSync : public BaseObject {
   friend class Session;
   friend class SQLTagStore;
   friend class StatementExecutionHelper;
+  friend class VirtualTableModule;
 };
 
 class StatementSync : public BaseObject {
@@ -351,6 +353,70 @@ class UserDefinedFunction {
   bool use_bigint_args_;
 };
 
+struct NodeVTab {
+  sqlite3_vtab base;
+  class VirtualTableModule* module;
+};
+
+struct NodeVTabCursor {
+  sqlite3_vtab_cursor base;
+  class VirtualTableModule* module;
+  v8::Global<v8::Object> iterator;
+  v8::Global<v8::Value> current_row;
+  sqlite3_int64 rowid;
+  bool done;
+};
+
+class VirtualTableModule {
+ public:
+  VirtualTableModule(Environment* env,
+                     DatabaseSync* db,
+                     v8::Local<v8::Function> rows_fn,
+                     std::string&& schema_sql,
+                     int num_columns,
+                     std::vector<int>&& hidden_col_indices,
+                     bool use_bigint_args,
+                     bool direct_only);
+  ~VirtualTableModule();
+
+  static int xCreate(sqlite3* db,
+                     void* pAux,
+                     int argc,
+                     const char* const* argv,
+                     sqlite3_vtab** ppVTab,
+                     char** pzErr);
+  static int xBestIndex(sqlite3_vtab* pVTab, sqlite3_index_info* pInfo);
+  static int xDisconnect(sqlite3_vtab* pVTab);
+  static int xDestroy(sqlite3_vtab* pVTab);
+  static int xOpen(sqlite3_vtab* pVTab, sqlite3_vtab_cursor** ppCursor);
+  static int xClose(sqlite3_vtab_cursor* pCursor);
+  static int xFilter(sqlite3_vtab_cursor* pCursor,
+                     int idxNum,
+                     const char* idxStr,
+                     int argc,
+                     sqlite3_value** argv);
+  static int xNext(sqlite3_vtab_cursor* pCursor);
+  static int xEof(sqlite3_vtab_cursor* pCursor);
+  static int xColumn(sqlite3_vtab_cursor* pCursor,
+                     sqlite3_context* ctx,
+                     int i);
+  static int xRowid(sqlite3_vtab_cursor* pCursor, sqlite3_int64* pRowid);
+  static void xDestroyModule(void* pAux);
+
+ private:
+  Environment* env_;
+  DatabaseSync* db_;
+  v8::Global<v8::Function> rows_fn_;
+  std::string schema_sql_;
+  int num_columns_;
+  std::vector<int> hidden_col_indices_;
+  // Maps schema column index to row array index for visible columns.
+  // Hidden columns are mapped to -1.
+  std::vector<int> col_index_map_;
+  bool use_bigint_args_;
+  bool direct_only_;
+};
+
 }  // namespace sqlite
 }  // namespace node
 
diff --git a/test/parallel/test-sqlite-virtual-table.js b/test/parallel/test-sqlite-virtual-table.js
new file mode 100644
index 00000000000000..ae5db2d5111689
--- /dev/null
+++ b/test/parallel/test-sqlite-virtual-table.js
@@ -0,0 +1,456 @@
+'use strict';
+const { skipIfSQLiteMissing } = require('../common');
+skipIfSQLiteMissing();
+const assert = require('node:assert');
+const { DatabaseSync } = require('node:sqlite');
+const { suite, test } = require('node:test');
+
+suite('DatabaseSync.prototype.createModule()', () => {
+  suite('input validation', () => {
+    const db = new DatabaseSync(':memory:');
+
+    test('throws if name is not a string', () => {
+      assert.throws(() => {
+        db.createModule();
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "name" argument must be a string/,
+      });
+    });
+
+    test('throws if options is not an object', () => {
+      assert.throws(() => {
+        db.createModule('mod', null);
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "options" argument must be an object/,
+      });
+    });
+
+    test('throws if options.columns is not an array', () => {
+      assert.throws(() => {
+        db.createModule('mod', { columns: 'bad', rows() {} });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "options\.columns" argument must be an array/,
+      });
+    });
+
+    test('throws if options.columns is empty', () => {
+      assert.throws(() => {
+        db.createModule('mod', { columns: [], rows() {} });
+      }, {
+        code: 'ERR_INVALID_ARG_VALUE',
+        message: /The "options\.columns" array must not be empty/,
+      });
+    });
+
+    test('throws if options.rows is not a function', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 'TEXT' }],
+          rows: 'bad',
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "options\.rows" argument must be a function/,
+      });
+    });
+
+    test('throws if column name is not a string', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 123, type: 'TEXT' }],
+          rows() {},
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The column "name" property must be a string/,
+      });
+    });
+
+    test('throws if column type is not a string', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 123 }],
+          rows() {},
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The column "type" property must be a string/,
+      });
+    });
+
+    test('throws if column type is not a valid SQLite type', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 'INVALID' }],
+          rows() {},
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_VALUE',
+        message: /The column "type" property must be one of/,
+      });
+    });
+
+    test('throws if column hidden is not a boolean', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 'TEXT', hidden: 'yes' }],
+          rows() {},
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The column "hidden" property must be a boolean/,
+      });
+    });
+
+    test('throws if options.directOnly is not a boolean', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 'TEXT' }],
+          rows() {},
+          directOnly: 'yes',
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "options\.directOnly" argument must be a boolean/,
+      });
+    });
+
+    test('throws if options.useBigIntArguments is not a boolean', () => {
+      assert.throws(() => {
+        db.createModule('mod', {
+          columns: [{ name: 'x', type: 'TEXT' }],
+          rows() {},
+          useBigIntArguments: 'yes',
+        });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: /The "options\.useBigIntArguments" argument must be a boolean/,
+      });
+    });
+
+    test('throws if database is not open', () => {
+      const closedDb = new DatabaseSync(':memory:');
+      closedDb.close();
+      assert.throws(() => {
+        closedDb.createModule('mod', {
+          columns: [{ name: 'x', type: 'TEXT' }],
+          rows() {},
+        });
+      }, {
+        code: 'ERR_INVALID_STATE',
+        message: /database is not open/,
+      });
+    });
+  });
+
+  suite('basic virtual table', () => {
+    test('creates a simple read-only virtual table', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('simple', {
+        columns: [
+          { name: 'id', type: 'INTEGER' },
+          { name: 'name', type: 'TEXT' },
+        ],
+        *rows() {
+          yield [1, 'Alice'];
+          yield [2, 'Bob'];
+          yield [3, 'Charlie'];
+        },
+      });
+
+      db.exec('CREATE VIRTUAL TABLE t1 USING simple');
+      const result = db.prepare('SELECT * FROM t1').all();
+      assert.deepStrictEqual(result, [
+        { __proto__: null, id: 1, name: 'Alice' },
+        { __proto__: null, id: 2, name: 'Bob' },
+        { __proto__: null, id: 3, name: 'Charlie' },
+      ]);
+    });
+
+    test('works as eponymous table (without CREATE VIRTUAL TABLE)', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('eponymous', {
+        columns: [
+          { name: 'value', type: 'TEXT' },
+        ],
+        *rows() {
+          yield ['hello'];
+          yield ['world'];
+        },
+      });
+
+      const result = db.prepare('SELECT * FROM eponymous').all();
+      assert.deepStrictEqual(result, [
+        { __proto__: null, value: 'hello' },
+        { __proto__: null, value: 'world' },
+      ]);
+    });
+
+    test('supports rows() returning an array', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('array_mod', {
+        columns: [
+          { name: 'val', type: 'INTEGER' },
+        ],
+        rows() {
+          return [[10], [20], [30]];
+        },
+      });
+
+      const result = db.prepare('SELECT * FROM array_mod').all();
+      assert.deepStrictEqual(result, [
+        { __proto__: null, val: 10 },
+        { __proto__: null, val: 20 },
+        { __proto__: null, val: 30 },
+      ]);
+    });
+
+    test('supports empty result set', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('empty_mod', {
+        columns: [
+          { name: 'x', type: 'TEXT' },
+        ],
+        *rows() {
+          // yields nothing
+        },
+      });
+
+      const result = db.prepare('SELECT * FROM empty_mod').all();
+      assert.deepStrictEqual(result, []);
+    });
+  });
+
+  suite('table-valued function with parameters', () => {
+    test('passes hidden column values as arguments to rows()', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('gen_series', {
+        columns: [
+          { name: 'value', type: 'INTEGER' },
+          { name: 'start', type: 'INTEGER', hidden: true },
+          { name: 'stop', type: 'INTEGER', hidden: true },
+          { name: 'step', type: 'INTEGER', hidden: true },
+        ],
+        *rows(start, stop, step) {
+          start ??= 0;
+          stop ??= 10;
+          step ??= 1;
+          for (let i = start; i <= stop; i += step) {
+            yield [i];
+          }
+        },
+      });
+
+      const result = db.prepare(
+        'SELECT value FROM gen_series(1, 5, 1)'
+      ).all();
+      assert.deepStrictEqual(result, [
+        { __proto__: null, value: 1 },
+        { __proto__: null, value: 2 },
+        { __proto__: null, value: 3 },
+        { __proto__: null, value: 4 },
+        { __proto__: null, value: 5 },
+      ]);
+    });
+
+    test('passes step parameter', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('gen_step', {
+        columns: [
+          { name: 'value', type: 'INTEGER' },
+          { name: 'start', type: 'INTEGER', hidden: true },
+          { name: 'stop', type: 'INTEGER', hidden: true },
+          { name: 'step', type: 'INTEGER', hidden: true },
+        ],
+        *rows(start, stop, step) {
+          start ??= 0;
+          stop ??= 10;
+          step ??= 1;
+          for (let i = start; i <= stop; i += step) {
+            yield [i];
+          }
+        },
+      });
+
+      const result = db.prepare(
+        'SELECT value FROM gen_step(0, 10, 3)'
+      ).all();
+      assert.deepStrictEqual(result, [
+        { __proto__: null, value: 0 },
+        { __proto__: null, value: 3 },
+        { __proto__: null, value: 6 },
+        { __proto__: null, value: 9 },
+      ]);
+    });
+
+    test('handles partial parameters (some hidden cols unconstrained)', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('partial_params', {
+        columns: [
+          { name: 'value', type: 'INTEGER' },
+          { name: 'count', type: 'INTEGER', hidden: true },
+        ],
+        *rows(count) {
+          const n = count ?? 3;
+          for (let i = 0; i < n; i++) {
+            yield [i];
+          }
+        },
+      });
+
+      // Without parameter (uses default).
+      db.exec('CREATE VIRTUAL TABLE pp USING partial_params');
+      const result1 = db.prepare('SELECT * FROM pp').all();
+      assert.strictEqual(result1.length, 3);
+
+      // With parameter via table-valued function syntax.
+      const result2 = db.prepare('SELECT * FROM partial_params(5)').all();
+      assert.strictEqual(result2.length, 5);
+    });
+  });
+
+  suite('type conversions', () => {
+    test('handles various SQLite data types', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('types_mod', {
+        columns: [
+          { name: 'int_col', type: 'INTEGER' },
+          { name: 'real_col', type: 'REAL' },
+          { name: 'text_col', type: 'TEXT' },
+          { name: 'blob_col', type: 'BLOB' },
+          { name: 'null_col', type: 'TEXT' },
+        ],
+        *rows() {
+          yield [42, 3.14, 'hello', new Uint8Array([1, 2, 3]), null];
+        },
+      });
+
+      const result = db.prepare('SELECT * FROM types_mod').get();
+      assert.strictEqual(result.int_col, 42);
+      assert.strictEqual(result.real_col, 3.14);
+      assert.strictEqual(result.text_col, 'hello');
+      assert.deepStrictEqual(
+        new Uint8Array(result.blob_col),
+        new Uint8Array([1, 2, 3])
+      );
+      assert.strictEqual(result.null_col, null);
+    });
+  });
+
+  suite('useBigIntArguments', () => {
+    test('passes INTEGER parameters as BigInts when enabled', () => {
+      const db = new DatabaseSync(':memory:');
+      let receivedType;
+
+      db.createModule('bigint_mod', {
+        columns: [
+          { name: 'result', type: 'TEXT' },
+          { name: 'input', type: 'INTEGER', hidden: true },
+        ],
+        useBigIntArguments: true,
+        *rows(input) {
+          receivedType = typeof input;
+          yield [String(input)];
+        },
+      });
+
+      db.prepare('SELECT * FROM bigint_mod(42)').get();
+      assert.strictEqual(receivedType, 'bigint');
+    });
+
+    test('passes INTEGER parameters as numbers by default', () => {
+      const db = new DatabaseSync(':memory:');
+      let receivedType;
+
+      db.createModule('number_mod', {
+        columns: [
+          { name: 'result', type: 'TEXT' },
+          { name: 'input', type: 'INTEGER', hidden: true },
+        ],
+        *rows(input) {
+          receivedType = typeof input;
+          yield [String(input)];
+        },
+      });
+
+      db.prepare('SELECT * FROM number_mod(42)').get();
+      assert.strictEqual(receivedType, 'number');
+    });
+  });
+
+  suite('error handling', () => {
+    test('propagates errors thrown in rows()', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('error_mod', {
+        columns: [
+          { name: 'x', type: 'TEXT' },
+        ],
+        rows() {
+          throw new Error('rows error');
+        },
+      });
+
+      assert.throws(() => {
+        db.prepare('SELECT * FROM error_mod').all();
+      }, {
+        message: /rows error/,
+      });
+    });
+
+    test('propagates errors thrown during iteration', () => {
+      const db = new DatabaseSync(':memory:');
+
+      db.createModule('iter_error_mod', {
+        columns: [
+          { name: 'x', type: 'INTEGER' },
+        ],
+        *rows() {
+          yield [1];
+          throw new Error('iteration error');
+        },
+      });
+
+      assert.throws(() => {
+        db.prepare('SELECT * FROM iter_error_mod').all();
+      }, {
+        message: /iteration error/,
+      });
+    });
+  });
+
+  suite('multiple queries', () => {
+    test('supports querying the virtual table multiple times', () => {
+      const db = new DatabaseSync(':memory:');
+      let callCount = 0;
+
+      db.createModule('multi_mod', {
+        columns: [
+          { name: 'value', type: 'INTEGER' },
+        ],
+        *rows() {
+          callCount++;
+          yield [callCount];
+        },
+      });
+
+      db.exec('CREATE VIRTUAL TABLE m USING multi_mod');
+      const r1 = db.prepare('SELECT * FROM m').get();
+      const r2 = db.prepare('SELECT * FROM m').get();
+      assert.strictEqual(r1.value, 1);
+      assert.strictEqual(r2.value, 2);
+      assert.strictEqual(callCount, 2);
+    });
+  });
+});

From 04c015f641e9cdd0cda283a867daa089979fa108 Mon Sep 17 00:00:00 2001
From: byteforge38 <stormcraft318@gmail.com>
Date: Tue, 27 Jan 2026 10:24:38 -0600
Subject: [PATCH 2/3] sqlite: heap-allocate sqlite3_module per virtual table
 module

---
 src/node_sqlite.cc | 51 +++++++++++++++++-----------------------------
 src/node_sqlite.h  |  3 +++
 2 files changed, 22 insertions(+), 32 deletions(-)

diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index a5527afc130965..ab8e4a3fad34a1 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -684,7 +684,24 @@ VirtualTableModule::VirtualTableModule(Environment* env,
       num_columns_(num_columns),
       hidden_col_indices_(std::move(hidden_col_indices)),
       use_bigint_args_(use_bigint_args),
-      direct_only_(direct_only) {
+      direct_only_(direct_only),
+      module_def_({}) {
+  // Initialize the sqlite3_module definition. Each VirtualTableModule instance
+  // gets its own copy to avoid thread-safety issues with worker threads.
+  module_def_.iVersion = 1;
+  module_def_.xCreate = VirtualTableModule::xCreate;
+  module_def_.xConnect = VirtualTableModule::xCreate;
+  module_def_.xBestIndex = VirtualTableModule::xBestIndex;
+  module_def_.xDisconnect = VirtualTableModule::xDisconnect;
+  module_def_.xDestroy = VirtualTableModule::xDestroy;
+  module_def_.xOpen = VirtualTableModule::xOpen;
+  module_def_.xClose = VirtualTableModule::xClose;
+  module_def_.xFilter = VirtualTableModule::xFilter;
+  module_def_.xNext = VirtualTableModule::xNext;
+  module_def_.xEof = VirtualTableModule::xEof;
+  module_def_.xColumn = VirtualTableModule::xColumn;
+  module_def_.xRowid = VirtualTableModule::xRowid;
+
   // Build mapping from schema column index to row array index.
   // Visible columns are numbered sequentially; hidden columns map to -1.
   col_index_map_.assign(num_columns, 0);
@@ -2146,36 +2163,6 @@ void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
 
   schema_sql += ")";
 
-  // Create the static module definition.
-  // This must be static or heap-allocated because SQLite retains a pointer.
-  static sqlite3_module vtab_module_def = {
-      1,                                // iVersion
-      VirtualTableModule::xCreate,      // xCreate
-      VirtualTableModule::xCreate,      // xConnect (same as xCreate)
-      VirtualTableModule::xBestIndex,   // xBestIndex
-      VirtualTableModule::xDisconnect,  // xDisconnect
-      VirtualTableModule::xDestroy,     // xDestroy
-      VirtualTableModule::xOpen,        // xOpen
-      VirtualTableModule::xClose,       // xClose
-      VirtualTableModule::xFilter,      // xFilter
-      VirtualTableModule::xNext,        // xNext
-      VirtualTableModule::xEof,         // xEof
-      VirtualTableModule::xColumn,      // xColumn
-      VirtualTableModule::xRowid,       // xRowid
-      nullptr,                          // xUpdate
-      nullptr,                          // xBegin
-      nullptr,                          // xSync
-      nullptr,                          // xCommit
-      nullptr,                          // xRollback
-      nullptr,                          // xFindFunction
-      nullptr,                          // xRename
-      nullptr,                          // xSavepoint
-      nullptr,                          // xRelease
-      nullptr,                          // xRollbackTo
-      nullptr,                          // xShadowName
-      nullptr,                          // xIntegrity
-  };
-
   VirtualTableModule* vtab_mod =
       new VirtualTableModule(env,
                              db,
@@ -2188,7 +2175,7 @@ void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
 
   int r = sqlite3_create_module_v2(db->connection_,
                                    *name,
-                                   &vtab_module_def,
+                                   &vtab_mod->module_def_,
                                    vtab_mod,
                                    VirtualTableModule::xDestroyModule);
   CHECK_ERROR_OR_THROW(env->isolate(), db, r, SQLITE_OK, void());
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
index 432576b4c63997..79d2147aaf363a 100644
--- a/src/node_sqlite.h
+++ b/src/node_sqlite.h
@@ -415,6 +415,9 @@ class VirtualTableModule {
   std::vector<int> col_index_map_;
   bool use_bigint_args_;
   bool direct_only_;
+  sqlite3_module module_def_;
+
+  friend class DatabaseSync;
 };
 
 }  // namespace sqlite

From cf6f98e73bf9a89a7f2cd71edab254cc17cca1ec Mon Sep 17 00:00:00 2001
From: byteforge38 <stormcraft318@gmail.com>
Date: Tue, 27 Jan 2026 17:40:14 -0600
Subject: [PATCH 3/3] sqlite: fix clang-format in virtual table code

---
 src/node_sqlite.cc | 12 ++++--------
 src/node_sqlite.h  |  4 +---
 2 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
index ab8e4a3fad34a1..abbe020e692be4 100644
--- a/src/node_sqlite.cc
+++ b/src/node_sqlite.cc
@@ -2010,8 +2010,7 @@ void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
 
   if (!rows_v->IsFunction()) {
     THROW_ERR_INVALID_ARG_TYPE(
-        env->isolate(),
-        "The \"options.rows\" argument must be a function.");
+        env->isolate(), "The \"options.rows\" argument must be a function.");
     return;
   }
 
@@ -2083,8 +2082,7 @@ void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
 
     if (!col_name_v->IsString()) {
       THROW_ERR_INVALID_ARG_TYPE(
-          env->isolate(),
-          "The column \"name\" property must be a string.");
+          env->isolate(), "The column \"name\" property must be a string.");
       return;
     }
 
@@ -2098,8 +2096,7 @@ void DatabaseSync::CreateModule(const FunctionCallbackInfo<Value>& args) {
 
     if (!col_type_v->IsString()) {
       THROW_ERR_INVALID_ARG_TYPE(
-          env->isolate(),
-          "The column \"type\" property must be a string.");
+          env->isolate(), "The column \"type\" property must be a string.");
       return;
     }
 
@@ -4040,8 +4037,7 @@ static void Initialize(Local<Object> target,
       isolate, db_tmpl, "loadExtension", DatabaseSync::LoadExtension);
   SetProtoMethod(
       isolate, db_tmpl, "setAuthorizer", DatabaseSync::SetAuthorizer);
-  SetProtoMethod(
-      isolate, db_tmpl, "createModule", DatabaseSync::CreateModule);
+  SetProtoMethod(isolate, db_tmpl, "createModule", DatabaseSync::CreateModule);
   SetSideEffectFreeGetter(isolate,
                           db_tmpl,
                           FIXED_ONE_BYTE_STRING(isolate, "isOpen"),
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
index 79d2147aaf363a..a62fe8497ef6a4 100644
--- a/src/node_sqlite.h
+++ b/src/node_sqlite.h
@@ -397,9 +397,7 @@ class VirtualTableModule {
                      sqlite3_value** argv);
   static int xNext(sqlite3_vtab_cursor* pCursor);
   static int xEof(sqlite3_vtab_cursor* pCursor);
-  static int xColumn(sqlite3_vtab_cursor* pCursor,
-                     sqlite3_context* ctx,
-                     int i);
+  static int xColumn(sqlite3_vtab_cursor* pCursor, sqlite3_context* ctx, int i);
   static int xRowid(sqlite3_vtab_cursor* pCursor, sqlite3_int64* pRowid);
   static void xDestroyModule(void* pAux);