sqlite: rename to setSqlTraceHook

araujogui · araujogui · commit b68b4be2ca5c · 2026-03-13T15:29:57.000-03:00
diff --git a/doc/api/sqlite.md b/doc/api/sqlite.md
@@ -107,9 +107,6 @@ exposed by this class execute synchronously.
 <!-- YAML
 added: v22.5.0
 changes:
-  - version: REPLACEME
-    pr-url: https://github.com/nodejs/node/pull/62241
-    description: Add `trace` option.
   - version:
      - v25.5.0
      - v24.14.0
@@ -183,13 +180,6 @@ changes:
     * `likePatternLength` {number} Maximum length of a LIKE pattern.
     * `variableNumber` {number} Maximum number of SQL variables.
     * `triggerDepth` {number} Maximum trigger recursion depth.
-  * `trace` {Function} An optional callback function that is invoked for
-    every SQL statement executed against the database. The callback receives
-    the expanded SQL string (with bound parameter values substituted) as its
-    only argument. If expansion fails, the source SQL (with unsubstituted
-    placeholders) is passed instead. This is useful for logging and debugging.
-    This option is a wrapper around [`sqlite3_trace_v2()`][].
-    **Default:** `undefined`.
 
 Constructs a new `DatabaseSync` instance.
 
@@ -382,6 +372,56 @@ added:
 This method is used to create SQLite user-defined functions. This method is a
 wrapper around [`sqlite3_create_function_v2()`][].
 
+### `database.setSqlTraceHook(hook)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `hook` {Function|null} The trace function to set, or `null` to clear
+  the current hook.
+
+Sets a hook that SQLite invokes for every SQL statement executed against the
+database. The hook receives the expanded SQL string (with bound parameter
+values substituted) as its only argument. If expansion fails, the source SQL
+with unsubstituted placeholders is passed instead.
+
+This method is a wrapper around [`sqlite3_trace_v2()`][].
+
+```cjs
+const { DatabaseSync } = require('node:sqlite');
+const db = new DatabaseSync(':memory:');
+
+db.setSqlTraceHook((sql) => console.log(sql));
+
+db.exec('CREATE TABLE t (x INTEGER)');
+// Logs: CREATE TABLE t (x INTEGER)
+
+const stmt = db.prepare('INSERT INTO t VALUES (?)');
+stmt.run(42);
+// Logs: INSERT INTO t VALUES (42.0)
+
+// Clear the hook
+db.setSqlTraceHook(null);
+```
+
+```mjs
+import { DatabaseSync } from 'node:sqlite';
+const db = new DatabaseSync(':memory:');
+
+db.setSqlTraceHook((sql) => console.log(sql));
+
+db.exec('CREATE TABLE t (x INTEGER)');
+// Logs: CREATE TABLE t (x INTEGER)
+
+const stmt = db.prepare('INSERT INTO t VALUES (?)');
+stmt.run(42);
+// Logs: INSERT INTO t VALUES (42.0)
+
+// Clear the hook
+db.setSqlTraceHook(null);
+```
+
 ### `database.setAuthorizer(callback)`
 
 <!-- YAML
diff --git a/src/env_properties.h b/src/env_properties.h
@@ -370,7 +370,6 @@
   V(url_string, "url")                                                         \
   V(username_string, "username")                                               \
   V(value_string, "value")                                                     \
-  V(trace_string, "trace")                                                     \
   V(verify_error_string, "verifyError")                                        \
   V(version_string, "version")                                                 \
   V(windows_hide_string, "windowsHide")                                        \
diff --git a/src/node_sqlite.cc b/src/node_sqlite.cc
@@ -974,15 +974,6 @@ bool DatabaseSync::Open() {
         env()->isolate(), this, load_extension_ret, SQLITE_OK, false);
   }
 
-  {
-    Local<Value> cb =
-        object()->GetInternalField(kTraceCallback).template As<Value>();
-    if (cb->IsFunction()) {
-      sqlite3_trace_v2(
-          connection_, SQLITE_TRACE_STMT, DatabaseSync::TraceCallback, this);
-    }
-  }
-
   return true;
 }
 
@@ -1348,21 +1339,6 @@ void DatabaseSync::New(const FunctionCallbackInfo<Value>& args) {
         }
       }
     }
-
-    // Parse trace option
-    Local<Value> trace_v;
-    if (!options->Get(env->context(), env->trace_string()).ToLocal(&trace_v)) {
-      return;
-    }
-    if (!trace_v->IsUndefined() && !trace_v->IsNull()) {
-      if (!trace_v->IsFunction()) {
-        THROW_ERR_INVALID_ARG_TYPE(
-            env->isolate(),
-            "The \"options.trace\" argument must be a function.");
-        return;
-      }
-      args.This()->SetInternalField(kTraceCallback, trace_v.As<Function>());
-    }
   }
 
   new DatabaseSync(
@@ -2309,6 +2285,30 @@ void DatabaseSync::LoadExtension(const FunctionCallbackInfo<Value>& args) {
   }
 }
 
+void DatabaseSync::SetSqlTraceHook(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");
+  Isolate* isolate = env->isolate();
+
+  if (args[0]->IsNull() || args[0]->IsUndefined()) {
+    sqlite3_trace_v2(db->connection_, 0, nullptr, nullptr);
+    db->object()->SetInternalField(kTraceCallback, Null(isolate));
+    return;
+  }
+
+  if (!args[0]->IsFunction()) {
+    THROW_ERR_INVALID_ARG_TYPE(isolate,
+                               "The \"hook\" argument must be a function.");
+    return;
+  }
+
+  db->object()->SetInternalField(kTraceCallback, args[0].As<Function>());
+  sqlite3_trace_v2(
+      db->connection_, SQLITE_TRACE_STMT, DatabaseSync::TraceCallback, db);
+}
+
 void DatabaseSync::SetAuthorizer(const FunctionCallbackInfo<Value>& args) {
   DatabaseSync* db;
   ASSIGN_OR_RETURN_UNWRAP(&db, args.This());
@@ -3838,6 +3838,8 @@ static void Initialize(Local<Object> target,
       isolate, db_tmpl, "enableDefensive", DatabaseSync::EnableDefensive);
   SetProtoMethod(
       isolate, db_tmpl, "loadExtension", DatabaseSync::LoadExtension);
+  SetProtoMethod(
+      isolate, db_tmpl, "setSqlTraceHook", DatabaseSync::SetSqlTraceHook);
   SetProtoMethod(
       isolate, db_tmpl, "setAuthorizer", DatabaseSync::SetAuthorizer);
   SetSideEffectFreeGetter(isolate,
diff --git a/src/node_sqlite.h b/src/node_sqlite.h
@@ -203,6 +203,7 @@ class DatabaseSync : public BaseObject {
                                 const char* param2,
                                 const char* param3,
                                 const char* param4);
+  static void SetSqlTraceHook(const v8::FunctionCallbackInfo<v8::Value>& args);
   static int TraceCallback(unsigned int type,
                            void* user_data,
                            void* p,
diff --git a/test/parallel/test-sqlite-trace.js b/test/parallel/test-sqlite-trace.js
@@ -7,27 +7,26 @@ const assert = require('node:assert');
 const { DatabaseSync } = require('node:sqlite');
 const { suite, it } = require('node:test');
 
-suite('DatabaseSync trace option', () => {
+suite('DatabaseSync.prototype.setSqlTraceHook()', () => {
   it('callback receives SQL string for exec() statements', (t) => {
     const calls = [];
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-    });
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x INTEGER)');
     db.exec('INSERT INTO t VALUES (1)');
 
     assert.strictEqual(calls.length, 2);
     assert.strictEqual(calls[0], 'CREATE TABLE t (x INTEGER)');
     assert.strictEqual(calls[1], 'INSERT INTO t VALUES (1)');
-    db.close();
   });
 
-  it('callback receives SQL string for prepared statement execution', (t) => {
+  it('callback receives SQL string for prepared INSERT statements', (t) => {
     let calls = [];
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-    });
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x INTEGER)');
     calls = []; // reset after setup
@@ -37,14 +36,13 @@ suite('DatabaseSync trace option', () => {
 
     assert.strictEqual(calls.length, 1);
     assert.strictEqual(calls[0], 'INSERT INTO t VALUES (42.0)');
-    db.close();
   });
 
-  it('callback receives SQL string for SELECT statements', () => {
+  it('callback receives SQL string for prepared SELECT statements', (t) => {
     let calls = [];
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-    });
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x INTEGER)');
     db.exec('INSERT INTO t VALUES (1)');
@@ -55,14 +53,13 @@ suite('DatabaseSync trace option', () => {
 
     assert.strictEqual(calls.length, 1);
     assert.strictEqual(calls[0], 'SELECT x FROM t WHERE x = 1.0');
-    db.close();
   });
 
-  it('callback receives SQL string for UPDATE statements', () => {
+  it('callback receives SQL string for prepared UPDATE statements', (t) => {
     let calls = [];
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-    });
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x INTEGER)');
     db.exec('INSERT INTO t VALUES (1)');
@@ -73,14 +70,13 @@ suite('DatabaseSync trace option', () => {
 
     assert.strictEqual(calls.length, 1);
     assert.strictEqual(calls[0], 'UPDATE t SET x = 2.0 WHERE x = 1.0');
-    db.close();
   });
 
-  it('callback receives SQL string for DELETE statements', () => {
+  it('callback receives SQL string for prepared DELETE statements', (t) => {
     let calls = [];
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-    });
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x INTEGER)');
     db.exec('INSERT INTO t VALUES (1)');
@@ -91,16 +87,27 @@ suite('DatabaseSync trace option', () => {
 
     assert.strictEqual(calls.length, 1);
     assert.strictEqual(calls[0], 'DELETE FROM t WHERE x = 1.0');
-    db.close();
   });
 
-  it('falls back to source SQL when expansion fails', () => {
-    let calls = [];
+  it('setSqlTraceHook(null) clears the callback', (t) => {
+    const calls = [];
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
-    const db = new DatabaseSync(':memory:', {
-      trace: (sql) => calls.push(sql),
-      limits: { length: 1000 },
-    });
+    db.exec('CREATE TABLE t (x INTEGER)');
+    assert.strictEqual(calls.length, 1);
+
+    db.setSqlTraceHook(null);
+    db.exec('INSERT INTO t VALUES (1)');
+    assert.strictEqual(calls.length, 1); // No new calls after clearing
+  });
+
+  it('falls back to source SQL when expansion fails', (t) => {
+    let calls = [];
+    const db = new DatabaseSync(':memory:', { limits: { length: 1000 } });
+    t.after(() => db.close());
+    db.setSqlTraceHook((sql) => calls.push(sql));
 
     db.exec('CREATE TABLE t (x TEXT)');
     calls = []; // reset after setup
@@ -113,22 +120,35 @@ suite('DatabaseSync trace option', () => {
     assert.strictEqual(calls.length, 1);
     // Falls back to source SQL with unexpanded '?' placeholder
     assert.strictEqual(calls[0], 'INSERT INTO t VALUES (?)');
-    db.close();
   });
 
-  it('invalid type for trace throws ERR_INVALID_ARG_TYPE', () => {
+  it('throws when the database is not open', () => {
+    const db = new DatabaseSync(':memory:', { open: false });
+
+    assert.throws(() => {
+      db.setSqlTraceHook(() => {});
+    }, {
+      code: 'ERR_INVALID_STATE',
+      message: /database is not open/,
+    });
+  });
+
+  it('throws ERR_INVALID_ARG_TYPE for non-function argument', (t) => {
+    const db = new DatabaseSync(':memory:');
+    t.after(() => db.close());
+
     assert.throws(() => {
-      new DatabaseSync(':memory:', { trace: 'not-a-function' });
+      db.setSqlTraceHook('not-a-function');
     }, {
       code: 'ERR_INVALID_ARG_TYPE',
-      message: /The "options\.trace" argument must be a function\./,
+      message: /The "hook" argument must be a function\./,
     });
 
     assert.throws(() => {
-      new DatabaseSync(':memory:', { trace: 42 });
+      db.setSqlTraceHook(42);
     }, {
       code: 'ERR_INVALID_ARG_TYPE',
-      message: /The "options\.trace" argument must be a function\./,
+      message: /The "hook" argument must be a function\./,
     });
   });
 });
