feat: add defensive mode support in DatabaseSync with corresponding tests

Author: mceachen

src/index.ts

@@ -60,6 +60,15 @@ export interface DatabaseSyncOptions {
    * @default false
    */
   readonly allowUnknownNamedParameters?: boolean;
+  /**
+   * If true, enables the defensive flag. When the defensive flag is enabled,
+   * language features that allow ordinary SQL to deliberately corrupt the
+   * database file are disabled. The defensive flag can also be set using
+   * `enableDefensive()`.
+   * @see https://sqlite.org/c3ref/c_dbconfig_defensive.html
+   * @default false
+   */
+  readonly defensive?: boolean;
   /**
    * If true, the database is opened immediately. If false, the database is not opened until the first operation.
    * @default true
@@ -305,6 +314,14 @@ export interface DatabaseSyncInstance {
    * @param entryPoint Optional entry point function name. If not provided, uses the default entry point.
    */
   loadExtension(path: string, entryPoint?: string): void;
+  /**
+   * Enables or disables the defensive flag. When the defensive flag is active,
+   * language features that allow ordinary SQL to deliberately corrupt the
+   * database file are disabled.
+   * @param active Whether to enable or disable the defensive flag.
+   * @see https://sqlite.org/c3ref/c_dbconfig_defensive.html
+   */
+  enableDefensive(active: boolean): void;
 
   /**
    * Makes a backup of the database. This method abstracts the sqlite3_backup_init(),

src/sqlite_impl.cpp

@@ -278,6 +278,7 @@ Napi::Object DatabaseSync::Init(Napi::Env env, Napi::Object exports) {
        InstanceMethod("enableLoadExtension",
                       &DatabaseSync::EnableLoadExtension),
        InstanceMethod("loadExtension", &DatabaseSync::LoadExtension),
+       InstanceMethod("enableDefensive", &DatabaseSync::EnableDefensive),
        InstanceMethod("createSession", &DatabaseSync::CreateSession),
        InstanceMethod("applyChangeset", &DatabaseSync::ApplyChangeset),
        InstanceMethod("backup", &DatabaseSync::Backup),
@@ -416,6 +417,20 @@ DatabaseSync::DatabaseSync(const Napi::CallbackInfo &info)
                 .Value());
       }
 
+      if (options.Has("defensive")) {
+        Napi::Value defensive_val = options.Get("defensive");
+        if (!defensive_val.IsUndefined()) {
+          if (!defensive_val.IsBoolean()) {
+            node::THROW_ERR_INVALID_ARG_TYPE(
+                info.Env(),
+                "The \"options.defensive\" argument must be a boolean.");
+            return;
+          }
+          config.set_enable_defensive(
+              defensive_val.As<Napi::Boolean>().Value());
+        }
+      }
+
       // Handle the open option
       if (options.Has("open")) {
         Napi::Value open_val = options.Get("open");
@@ -682,6 +697,21 @@ void DatabaseSync::InternalOpen(DatabaseOpenConfiguration config) {
       throw ex;
     }
   }
+
+  // Configure defensive mode
+  if (config_.get_enable_defensive()) {
+    int defensive_enabled;
+    result = sqlite3_db_config(connection(), SQLITE_DBCONFIG_DEFENSIVE, 1,
+                               &defensive_enabled);
+    if (result != SQLITE_OK) {
+      std::string error = sqlite3_errmsg(connection());
+      SqliteException ex(connection_, result,
+                         "Failed to configure DEFENSIVE: " + error);
+      sqlite3_close(connection_);
+      connection_ = nullptr;
+      throw ex;
+    }
+  }
 }
 
 void DatabaseSync::InternalClose() {
@@ -1041,6 +1071,36 @@ Napi::Value DatabaseSync::LoadExtension(const Napi::CallbackInfo &info) {
   return env.Undefined();
 }
 
+Napi::Value DatabaseSync::EnableDefensive(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  if (!ValidateThread(env)) {
+    return env.Undefined();
+  }
+
+  if (!IsOpen()) {
+    node::THROW_ERR_INVALID_STATE(env, "database is not open");
+    return env.Undefined();
+  }
+
+  if (info.Length() < 1 || !info[0].IsBoolean()) {
+    node::THROW_ERR_INVALID_ARG_TYPE(
+        env, "The \"active\" argument must be a boolean.");
+    return env.Undefined();
+  }
+
+  int enable = info[0].As<Napi::Boolean>().Value() ? 1 : 0;
+  int defensive_enabled;
+  int result = sqlite3_db_config(connection(), SQLITE_DBCONFIG_DEFENSIVE,
+                                 enable, &defensive_enabled);
+  if (result != SQLITE_OK) {
+    node::ThrowEnhancedSqliteError(env, connection(), result,
+                                   "Failed to set defensive mode");
+  }
+
+  return env.Undefined();
+}
+
 Napi::Value DatabaseSync::CreateSession(const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
 

src/sqlite_impl.h

@@ -100,6 +100,9 @@ class DatabaseOpenConfiguration {
     allow_unknown_named_params_ = flag;
   }
 
+  bool get_enable_defensive() const { return defensive_; }
+  void set_enable_defensive(bool flag) { defensive_ = flag; }
+
 private:
   std::string location_;
   bool read_only_ = false;
@@ -110,6 +113,7 @@ class DatabaseOpenConfiguration {
   bool return_arrays_ = false;
   bool allow_bare_named_params_ = true;
   bool allow_unknown_named_params_ = false;
+  bool defensive_ = false;
 };
 
 // Main database class
@@ -148,6 +152,9 @@ class DatabaseSync : public Napi::ObjectWrap<DatabaseSync> {
   Napi::Value EnableLoadExtension(const Napi::CallbackInfo &info);
   Napi::Value LoadExtension(const Napi::CallbackInfo &info);
 
+  // Defensive mode
+  Napi::Value EnableDefensive(const Napi::CallbackInfo &info);
+
   // Session support
   Napi::Value CreateSession(const Napi::CallbackInfo &info);
   Napi::Value ApplyChangeset(const Napi::CallbackInfo &info);

test/database.test.ts

@@ -724,3 +724,79 @@ describe("Database Configuration Tests", () => {
     db.close();
   });
 });
+
+describe("Defensive Mode", () => {
+  /**
+   * Check if defensive mode is active by testing if journal_mode can be changed.
+   * When defensive mode is ON, changing journal_mode to OFF is blocked.
+   * This matches the test approach used in Node.js test-sqlite-config.js
+   */
+  function checkDefensiveMode(db: InstanceType<typeof DatabaseSync>): boolean {
+    const journalMode = (): string =>
+      (db.prepare("PRAGMA journal_mode").get() as { journal_mode: string })
+        .journal_mode;
+
+    // In-memory databases start with journal_mode = 'memory'
+    expect(journalMode()).toBe("memory");
+
+    // Try to change journal_mode to OFF
+    db.exec("PRAGMA journal_mode=OFF");
+
+    // If defensive mode is active, journal_mode stays 'memory'
+    // If defensive mode is off, journal_mode changes to 'off'
+    return journalMode() === "memory";
+  }
+
+  test("by default, defensive mode is off", () => {
+    const db = new DatabaseSync(":memory:");
+    expect(checkDefensiveMode(db)).toBe(false);
+    db.close();
+  });
+
+  test("when passing { defensive: true } as config, defensive mode is on", () => {
+    const db = new DatabaseSync(":memory:", {
+      defensive: true,
+    });
+    expect(checkDefensiveMode(db)).toBe(true);
+    db.close();
+  });
+
+  test("defensive mode on after calling db.enableDefensive(true)", () => {
+    const db = new DatabaseSync(":memory:");
+    db.enableDefensive(true);
+    expect(checkDefensiveMode(db)).toBe(true);
+    db.close();
+  });
+
+  test("defensive mode should be off after calling db.enableDefensive(false)", () => {
+    const db = new DatabaseSync(":memory:", {
+      defensive: true,
+    });
+    db.enableDefensive(false);
+    expect(checkDefensiveMode(db)).toBe(false);
+    db.close();
+  });
+
+  test("throws if options.defensive is provided but is not a boolean", () => {
+    expect(() => {
+      // @ts-expect-error - testing invalid type
+      new DatabaseSync(":memory:", { defensive: 42 });
+    }).toThrow(/boolean/);
+  });
+
+  test("enableDefensive throws if argument is not a boolean", () => {
+    const db = new DatabaseSync(":memory:");
+    expect(() => {
+      // @ts-expect-error - testing invalid type
+      db.enableDefensive("yes");
+    }).toThrow(/boolean/);
+    db.close();
+  });
+
+  test("enableDefensive throws if database is not open", () => {
+    const db = new DatabaseSync(":memory:", { open: false });
+    expect(() => {
+      db.enableDefensive(true);
+    }).toThrow(/not open/);
+  });
+});