nodejs · jac0bandres · Aug 13, 2025 · Aug 13, 2025 · Aug 14, 2025 · Aug 14, 2025
diff --git a/src/env_properties.h b/src/env_properties.h
@@ -338,6 +338,7 @@
   V(read_host_object_string, "_readHostObject")                                \
   V(readable_string, "readable")                                               \
   V(read_bigints_string, "readBigInts")                                        \
+  V(read_null_as_undefined_string, "readNullAsUndefined")                      \
   V(reason_string, "reason")                                                   \
   V(refresh_string, "refresh")                                                 \
   V(regexp_string, "regexp")                                                   \

diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
@@ -41,6 +41,7 @@ using v8::MaybeLocal;
 using v8::Name;
 using v8::NewStringType;
 using v8::Null;
+using v8::Undefined;
 using v8::Number;
 using v8::Object;
 using v8::Promise;
@@ -67,7 +68,7 @@ using v8::Value;
     }                                                                          \
   } while (0)
 
-#define SQLITE_VALUE_TO_JS(from, isolate, use_big_int_args, result, ...)       \
+#define SQLITE_VALUE_TO_JS(from, isolate, use_big_int_args, use_null_as_undefined_, result, ...)       \
   do {                                                                         \
     switch (sqlite3_##from##_type(__VA_ARGS__)) {                              \
       case SQLITE_INTEGER: {                                                   \
@@ -96,7 +97,11 @@ using v8::Value;
         break;                                                                 \
       }                                                                        \
       case SQLITE_NULL: {                                                      \
-        (result) = Null((isolate));                                            \
+        if ((use_null_as_undefined_)) {                                        \
+          (result) = Undefined((isolate));                                     \
+        } else {                                                               \
+          (result) = Null((isolate));                                          \
+        }                                                                      \
         break;                                                                 \
       }                                                                        \
       case SQLITE_BLOB: {                                                      \
@@ -254,13 +259,15 @@ class CustomAggregate {
   explicit CustomAggregate(Environment* env,
                            DatabaseSync* db,
                            bool use_bigint_args,
+                           bool use_null_as_undefined_args,
                            Local<Value> start,
                            Local<Function> step_fn,
                            Local<Function> inverse_fn,
                            Local<Function> result_fn)
       : env_(env),
         db_(db),
         use_bigint_args_(use_bigint_args),
+        use_null_as_undefined_args_(use_null_as_undefined_args),
         start_(env->isolate(), start),
         step_fn_(env->isolate(), step_fn),
         inverse_fn_(env->isolate(), inverse_fn),
@@ -310,7 +317,7 @@ class CustomAggregate {
     for (int i = 0; i < argc; ++i) {
       sqlite3_value* value = argv[i];
       MaybeLocal<Value> js_val;
-      SQLITE_VALUE_TO_JS(value, isolate, self->use_bigint_args_, js_val, value);
+      SQLITE_VALUE_TO_JS(value, isolate, self->use_bigint_args_, self->use_null_as_undefined_args_, js_val, value);
       if (js_val.IsEmpty()) {
         // Ignore the SQLite error because a JavaScript exception is pending.
         self->db_->SetIgnoreNextSQLiteError(true);
@@ -418,6 +425,7 @@ class CustomAggregate {
   Environment* env_;
   DatabaseSync* db_;
   bool use_bigint_args_;
+  bool use_null_as_undefined_args_;
   Global<Value> start_;
   Global<Function> step_fn_;
   Global<Function> inverse_fn_;
@@ -591,11 +599,14 @@ class BackupJob : public ThreadPoolWork {
 UserDefinedFunction::UserDefinedFunction(Environment* env,
                                          Local<Function> fn,
                                          DatabaseSync* db,
-                                         bool use_bigint_args)
+                                         bool use_bigint_args,
+                                         bool use_null_as_undefined_args
+                                        )
     : env_(env),
       fn_(env->isolate(), fn),
       db_(db),
-      use_bigint_args_(use_bigint_args) {}
+      use_bigint_args_(use_bigint_args),
+      use_null_as_undefined_args_(use_null_as_undefined_args) {}
 
 UserDefinedFunction::~UserDefinedFunction() {}
 
@@ -613,7 +624,7 @@ void UserDefinedFunction::xFunc(sqlite3_context* ctx,
   for (int i = 0; i < argc; ++i) {
     sqlite3_value* value = argv[i];
     MaybeLocal<Value> js_val = MaybeLocal<Value>();
-    SQLITE_VALUE_TO_JS(value, isolate, self->use_bigint_args_, js_val, value);
+    SQLITE_VALUE_TO_JS(value, isolate, self->use_bigint_args_, self->use_null_as_undefined_args_, js_val, value);
     if (js_val.IsEmpty()) {
       // Ignore the SQLite error because a JavaScript exception is pending.
       self->db_->SetIgnoreNextSQLiteError(true);
@@ -981,6 +992,20 @@ void DatabaseSync::New(const FunctionCallbackInfo<Value>& args) {
       }
     }
 
+    Local<Value> read_null_as_undefined_v;
+    if (options->Get(env->context(), env->read_null_as_undefined_string())
+            .ToLocal(&read_null_as_undefined_v)) {
+      if (!read_null_as_undefined_v->IsUndefined()) {
+        if (!read_null_as_undefined_v->IsBoolean()) {
+          THROW_ERR_INVALID_ARG_TYPE(
+              env->isolate(),
+              R"(The "options.readNullAsUndefined" argument must be a boolean.)");
+          return;
+        }
+        open_config.set_use_null_as_undefined(read_null_as_undefined_v.As<Boolean>()->Value());
+      }
+    }
+
     Local<Value> return_arrays_v;
     if (options->Get(env->context(), env->return_arrays_string())
             .ToLocal(&return_arrays_v)) {
@@ -1126,6 +1151,7 @@ void DatabaseSync::CustomFunction(const FunctionCallbackInfo<Value>& args) {
 
   int fn_index = args.Length() < 3 ? 1 : 2;
   bool use_bigint_args = false;
+  bool use_null_as_undefined_args = false;
   bool varargs = false;
   bool deterministic = false;
   bool direct_only = false;
@@ -1234,7 +1260,7 @@ void DatabaseSync::CustomFunction(const FunctionCallbackInfo<Value>& args) {
   }
 
   UserDefinedFunction* user_data =
-      new UserDefinedFunction(env, fn, db, use_bigint_args);
+      new UserDefinedFunction(env, fn, db, use_bigint_args, use_null_as_undefined_args);
   int text_rep = SQLITE_UTF8;
 
   if (deterministic) {
@@ -1323,9 +1349,11 @@ void DatabaseSync::AggregateFunction(const FunctionCallbackInfo<Value>& args) {
   }
 
   bool use_bigint_args = false;
+  bool use_null_as_undefined_args = false;
   bool varargs = false;
   bool direct_only = false;
   Local<Value> use_bigint_args_v;
+  Local<Value> use_null_as_undefined_args_v;
   Local<Function> inverseFunc = Local<Function>();
   if (!options
            ->Get(env->context(),
@@ -1344,6 +1372,23 @@ void DatabaseSync::AggregateFunction(const FunctionCallbackInfo<Value>& args) {
     use_bigint_args = use_bigint_args_v.As<Boolean>()->Value();
   }
 
+  if (!options
+           ->Get(env->context(),
+                 FIXED_ONE_BYTE_STRING(env->isolate(), "useNullAsUndefined"))
+           .ToLocal(&use_null_as_undefined_args_v)) {
+    return;
+  }
+
+  if (!use_null_as_undefined_args_v->IsUndefined()) {
+    if (!use_null_as_undefined_args_v->IsBoolean()) {
+      THROW_ERR_INVALID_ARG_TYPE(
+          env->isolate(),
+          "The \"options.useNullAsUndefined\" argument must be a boolean.");
+      return;
+    }
+    use_null_as_undefined_args = use_bigint_args_v.As<Boolean>()->Value();
+  }
+
   Local<Value> varargs_v;
   if (!options
            ->Get(env->context(),
@@ -1432,6 +1477,7 @@ void DatabaseSync::AggregateFunction(const FunctionCallbackInfo<Value>& args) {
                                          new CustomAggregate(env,
                                                              db,
                                                              use_bigint_args,
+                                                             use_null_as_undefined_args,
                                                              start_v,
                                                              stepFunction,
                                                              inverseFunc,
@@ -2000,7 +2046,7 @@ MaybeLocal<Value> StatementSync::ColumnToValue(const int column) {
   Isolate* isolate = env()->isolate();
   MaybeLocal<Value> js_val = MaybeLocal<Value>();
   SQLITE_VALUE_TO_JS(
-      column, isolate, use_big_ints_, js_val, statement_, column);
+      column, isolate, use_big_ints_, use_null_as_undefined_, js_val, statement_, column);
   return js_val;
 }
 
@@ -2378,6 +2424,22 @@ void StatementSync::SetReadBigInts(const FunctionCallbackInfo<Value>& args) {
   stmt->use_big_ints_ = args[0]->IsTrue();
 }
 
+void StatementSync::SetReadNullAsUndefined(const FunctionCallbackInfo<Value>& args) {
+  StatementSync* stmt;
+  ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
+  Environment* env = Environment::GetCurrent(args);
+  THROW_AND_RETURN_ON_BAD_STATE(
+      env, stmt->IsFinalized(), "statement has been finalized");
+
+  if (!args[0]->IsBoolean()) {
+    THROW_ERR_INVALID_ARG_TYPE(
+        env->isolate(), "The \"readNullAsUndefined\" argument must be a boolean.");
+    return;
+  }
+
+  stmt->use_null_as_undefined_= args[0]->IsTrue();
+}
+
 void StatementSync::SetReturnArrays(const FunctionCallbackInfo<Value>& args) {
   StatementSync* stmt;
   ASSIGN_OR_RETURN_UNWRAP(&stmt, args.This());
@@ -2447,6 +2509,8 @@ Local<FunctionTemplate> StatementSync::GetConstructorTemplate(
                    tmpl,
                    "setAllowUnknownNamedParameters",
                    StatementSync::SetAllowUnknownNamedParameters);
+    SetProtoMethod(
+      isolate, tmpl, "setReadNullAsUndefined", StatementSync::SetReadNullAsUndefined);
     SetProtoMethod(
         isolate, tmpl, "setReadBigInts", StatementSync::SetReadBigInts);
     SetProtoMethod(

diff --git a/src/node_sqlite.h b/src/node_sqlite.h
@@ -43,6 +43,10 @@ class DatabaseOpenConfiguration {
 
   inline bool get_use_big_ints() const { return use_big_ints_; }
 
+  inline void set_use_null_as_undefined(bool flag) { use_null_as_undefined_ = flag; }
+
+  inline bool get_use_null_as_undefined() const { return use_null_as_undefined_; }
+
   inline void set_return_arrays(bool flag) { return_arrays_ = flag; }
 
   inline bool get_return_arrays() const { return return_arrays_; }
@@ -70,6 +74,7 @@ class DatabaseOpenConfiguration {
   bool enable_dqs_ = false;
   int timeout_ = 0;
   bool use_big_ints_ = false;
+  bool use_null_as_undefined_ = false;
   bool return_arrays_ = false;
   bool allow_bare_named_params_ = true;
   bool allow_unknown_named_params_ = false;
@@ -111,6 +116,7 @@ class DatabaseSync : public BaseObject {
   void UntrackStatement(StatementSync* statement);
   bool IsOpen();
   bool use_big_ints() const { return open_config_.get_use_big_ints(); }
+  bool use_null_as_undefined() const { return open_config_.get_use_null_as_undefined(); }
   bool return_arrays() const { return open_config_.get_return_arrays(); }
   bool allow_bare_named_params() const {
     return open_config_.get_allow_bare_named_params();
@@ -173,6 +179,7 @@ class StatementSync : public BaseObject {
   static void SetAllowUnknownNamedParameters(
       const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReadBigInts(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void SetReadNullAsUndefined(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void SetReturnArrays(const v8::FunctionCallbackInfo<v8::Value>& args);
   void Finalize();
   bool IsFinalized();
@@ -186,6 +193,7 @@ class StatementSync : public BaseObject {
   sqlite3_stmt* statement_;
   bool return_arrays_ = false;
   bool use_big_ints_;
+  bool use_null_as_undefined_ = false;
   bool allow_bare_named_params_;
   bool allow_unknown_named_params_;
   std::optional<std::map<std::string, std::string>> bare_named_params_;
@@ -253,7 +261,9 @@ class UserDefinedFunction {
   UserDefinedFunction(Environment* env,
                       v8::Local<v8::Function> fn,
                       DatabaseSync* db,
-                      bool use_bigint_args);
+                      bool use_bigint_args,
+                      bool use_null_as_undefined_args
+                    );
   ~UserDefinedFunction();
   static void xFunc(sqlite3_context* ctx, int argc, sqlite3_value** argv);
   static void xDestroy(void* self);
@@ -263,6 +273,7 @@ class UserDefinedFunction {
   v8::Global<v8::Function> fn_;
   DatabaseSync* db_;
   bool use_bigint_args_;
+  bool use_null_as_undefined_args_;
 };
 
 }  // namespace sqlite

diff --git a/test/parallel/test-sqlite-aggregate-function.mjs b/test/parallel/test-sqlite-aggregate-function.mjs
@@ -43,6 +43,15 @@
       });
     });
 
+    test('throws if options.readNullAsUndefined is provided but is not a boolean', (t) => {
+      t.assert.throws(() => {
+        new DatabaseSync('foo', { readNullAsUndefined: 42 });
+      }, {
+        code: 'ERR_INVALID_ARG_TYPE',
+        message: 'The "options.readNullAsUndefined" argument must be a boolean.',
+      })
+    })
+
     test('throws if options.varargs is not a boolean', (t) => {
       t.assert.throws(() => {
         db.aggregate('sum', {

diff --git a/test/parallel/test-sqlite-database-sync.js b/test/parallel/test-sqlite-database-sync.js
@@ -205,6 +205,32 @@
     );
   });
 
+  test('throws if options.readNullAsUndefined is provided but is not a boolean', (t) => {
+    t.assert.throws(() => {
+      new DatabaseSync('foo', { readNullAsUndefined: 42 });
+    }, {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: 'The "options.readNullAsUndefined" argument must be a boolean.',
+    })
+  });
+
+  test('SQL null can be read as undefined', (t) => {
+    const db = new DatabaseSync(nextDb(), { readNullAsUndefined: true});
+    t.after(() => { db.close(); });
+    const setup = db.exec(`
+      CREATE TABLE data(is_null TEXT DEFAULT NULL) STRICT;
+      INSERT INTO data(is_null) VALUES(NULL);
+    `)
+    t.assert.strictEqual(setup, undefined);
+
+    const query = db.prepare('SELECT is_null FROM DATA');
+    t.assert.deepStrictEqual(query.get(),{ __proto__: null, is_null: null});
+    t.assert.strictEqual(query.setReadNullAsUndefined(true), undefined);
+    t.assert.deepStrictEqual(query.get(), { __proto__: null, is_null: undefined});
+    t.assert.strictEqual(query.setReadNullAsUndefined(false), undefined);
+    t.assert.deepStrictEqual(query.get(), { __proto__: null, is_null: null});
+  });
+
   test('throws if options.returnArrays is provided but is not a boolean', (t) => {
     t.assert.throws(() => {
       new DatabaseSync('foo', { returnArrays: 42 });

diff --git a/test/parallel/test-sqlite-statement-sync.js b/test/parallel/test-sqlite-statement-sync.js
@@ -275,6 +275,58 @@
   });
 });
 
+suite('StatementSync.prototype.setReadNullAsUndefined', () => {
+  test('Null can be read as undefined', (t) => {
+    const db = new DatabaseSync(nextDb());
+    t.after(() => { db.close(); });
+    const setup = db.exec(`
+      CREATE TABLE data(is_null TEXT DEFAULT NULL) STRICT;
+      INSERT INTO data(is_null) VALUES(NULL);
+    `)
+    t.assert.strictEqual(setup, undefined);
+
+    const query = db.prepare('SELECT is_null FROM DATA');
+    t.assert.deepStrictEqual(query.get(),{ __proto__: null, is_null: null});
+    t.assert.strictEqual(query.setReadNullAsUndefined(true), undefined);
+    t.assert.deepStrictEqual(query.get(), { __proto__: null, is_null: undefined});
+    t.assert.strictEqual(query.setReadNullAsUndefined(false), undefined);
+    t.assert.deepStrictEqual(query.get(), { __proto__: null, is_null: null});
+  })
+
+  test('does not affect non-null values', (t) => {
+    const db = new DatabaseSync(nextDb());
+    t.after(() => { db.close(); });
+    const setup = db.exec(`
+      CREATE TABLE data(is_not_null TEXT) STRICT;
+      INSERT INTO data(is_not_null) VALUES('This is not null');
+    `)
+    t.assert.strictEqual(setup, undefined);
+
+    const query = db.prepare('SELECT is_not_null FROM DATA');
+    t.assert.deepStrictEqual(query.get(),{ __proto__: null, is_not_null: 'This is not null'});
+    t.assert.strictEqual(query.setReadNullAsUndefined(true), undefined);
+    console.log(query.get())
+    t.assert.deepStrictEqual(query.get(), { __proto__: null, is_not_null: 'This is not null'});
+  })
+  test('throws when input is not a boolean', (t) => {
+    const db = new DatabaseSync(nextDb());
+    t.after(() => { db.close(); });
+    const setup = db.exec(`
+      CREATE TABLE data(is_not_null TEXT) STRICT;
+      INSERT INTO data(is_not_null) VALUES('This is not null');
+    `)
+    t.assert.strictEqual(setup, undefined);
+
+    const stmt = db.prepare('SELECT is_not_null FROM data');
+    t.assert.throws(() => {
+      stmt.setReadNullAsUndefined();
+    }, {
+      code: 'ERR_INVALID_ARG_TYPE',
+      message: /The "readNullAsUndefined" argument must be a boolean/,
+    });
+  });
+});
+
 suite('StatementSync.prototype.setReadBigInts()', () => {
   test('BigInts support can be toggled', (t) => {
     const db = new DatabaseSync(nextDb());
@@ -327,8 +379,7 @@
 
   test('BigInt is required for reading large integers', (t) => {
     const db = new DatabaseSync(nextDb());
-    t.after(() => { db.close(); });
-    const bad = db.prepare(`SELECT ${Number.MAX_SAFE_INTEGER} + 1`);
+    t.after(() => { db.close(); }); const bad = db.prepare(`SELECT ${Number.MAX_SAFE_INTEGER} + 1`);
     t.assert.throws(() => {
       bad.get();
     }, {