sqlite: add diagnostic channel

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
PR-URL: #62241
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

Author: araujogui

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {

benchmark/sqlite/sqlite-diagnostic-channel.js

@@ -0,0 +1,42 @@
+'use strict';
+constcommon=require('../common.js');
+constsqlite=require('node:sqlite');
+constdc=require('node:diagnostics_channel');
+constassert=require('node:assert');
+
+constbench=common.createBenchmark(main,{
+n: [1e5],
+mode: ['none','subscribed','unsubscribed'],
+});
+
+functionmain(conf){
+const{ n, mode }=conf;
+
+constdb=newsqlite.DatabaseSync(':memory:');
+db.exec('CREATE TABLE t (x INTEGER)');
+constinsert=db.prepare('INSERT INTO t VALUES (?)');
+
+letsubscriber;
+if(mode==='subscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+}elseif(mode==='unsubscribed'){
+subscriber=()=>{};
+dc.subscribe('sqlite.db.query',subscriber);
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+// mode === 'none': no subscription ever made
+
+letresult;
+bench.start();
+for(leti=0;i<n;i++){
+result=insert.run(i);
+}
+bench.end(n);
+
+if(mode==='subscribed'){
+dc.unsubscribe('sqlite.db.query',subscriber);
+}
+
+assert.ok(result!==undefined);
+}

doc/api/diagnostics_channel.md

@@ -1922,10 +1922,47 @@ added: v16.18.0
 
 Emitted when a new thread is created.
 
+#### SQLite
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+##### Event: `'sqlite.db.query'`
+
+*`sql` {string} The expanded SQL with bound parameter values substituted.
+ If expansion fails, the source SQL with unsubstituted placeholders is used
+ instead.
+*`database` {DatabaseSync} The [`DatabaseSync`][] instance that executed the
+ statement.
+*`duration` {number} SQLite's internal estimate of the statement run time in
+ nanoseconds. This reflects C-layer execution time only and does not include
+ JavaScript binding overhead such as argument marshaling or result-row
+ construction.
+
+Emitted after a SQL statement finishes executing against a [`DatabaseSync`][]
+instance. This is a **profiling** event: it fires once per statement upon
+completion and reports an estimated duration from SQLite's internal profiler.
+It is not a distributed-tracing span. There is no corresponding start event,
+no async context propagation, and no parent-span linkage. If you need
+OpenTelemetry-compatible spans or async context propagation, wrap your SQLite
+calls with a [`TracingChannel`][] at the JavaScript layer instead.
+
+Publishing is zero-overhead when there are no subscribers.
+
+No event is emitted for a statement that is abandoned mid-iteration and later
+finalized, either explicitly through [`statement.close()`][] or when the
+statement is garbage collected. Subscribers must not close the database or the
+statement, since both are still in use while the event is being delivered; see
+[`database.close()`][] and [`statement.close()`][].
+
 [BoundedChannel Channels]: #boundedchannel-channels
 [TracingChannel Channels]: #tracingchannel-channels
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`BoundedChannel`]: #class-boundedchannel
+[`DatabaseSync`]: sqlite.md#class-databasesync
 [`TracingChannel`]: #class-tracingchannel
 [`asyncEnd` event]: #asyncendevent
 [`asyncStart` event]: #asyncstartevent
@@ -1936,6 +1973,7 @@ Emitted when a new thread is created.
 [`channel.unsubscribe(onMessage)`]: #channelunsubscribeonmessage
 [`channel.withStoreScope(data)`]: #channelwithstorescopedata
 [`child_process.spawn()`]: child_process.md#child_processspawncommand-args-options
+[`database.close()`]: sqlite.md#databaseclose
 [`diagnostics_channel.channel(name)`]: #diagnostics_channelchannelname
 [`diagnostics_channel.subscribe(name, onMessage)`]: #diagnostics_channelsubscribename-onmessage
 [`diagnostics_channel.tracingChannel()`]: #diagnostics_channeltracingchannelnameorchannels
@@ -1945,6 +1983,7 @@ Emitted when a new thread is created.
 [`net.Server.listen()`]: net.md#serverlisten
 [`process.execve()`]: process.md#processexecvefile-args-env
 [`start` event]: #startevent
+[`statement.close()`]: sqlite.md#statementclose
 [`worker_threads.locks`]: worker_threads.md#worker_threadslocks
 [context loss]: async_context.md#troubleshooting-context-loss
 [thenable object]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables

doc/api/sqlite.md

@@ -30,7 +30,9 @@ import sqlite from 'node:sqlite';
 constsqlite=require('node:sqlite');
 ```
 
-This module is only available under the `node:` scheme.
+This module is only available under the `node:` scheme. SQL trace events can
+be observed via the [`diagnostics_channel`][] module. See
+[`'sqlite.db.query'`][] for details.
 
 The following example shows the basic usage of the `node:sqlite` module to open
 an in-memory database, write data to the database, and then read the data back.
@@ -309,8 +311,8 @@ added: v22.5.0
 Closes the database connection. An exception is thrown if the database is not
 open. An [`ERR_INVALID_STATE`][] error is thrown if the method is called while
 a statement is executing, such as inside a user-defined function, an aggregate
-function, or an authorizer callback. This method is a wrapper around
-[`sqlite3_close_v2()`][].
+function, an authorizer callback, or a [`'sqlite.db.query'`][] subscriber. This
+method is a wrapper around [`sqlite3_close_v2()`][].
 
 ### `database.loadExtension(path[, entryPoint])`
 
@@ -1114,7 +1116,12 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. An exception is thrown if the statement is
-already finalized. This method is a wrapper around [`sqlite3_finalize()`][].
+already finalized. An [`ERR_INVALID_STATE`][] error is thrown if this statement
+is currently executing, which happens when the method is called from a callback
+that the statement itself triggered, such as a user-defined function, an
+aggregate function, or a [`'sqlite.db.query'`][] subscriber. Other statements
+on the same connection can be finalized from such a callback. This method is a
+wrapper around [`sqlite3_finalize()`][].
 
 ### `statement.columns()`
 
@@ -1361,7 +1368,9 @@ added: REPLACEME
 -->
 
 Finalizes the prepared statement. If the prepared statement is already
-finalized, then this is a no-op.
+finalized, then this is a no-op. An [`ERR_INVALID_STATE`][] error is thrown if
+this statement is currently executing, under the same conditions as
+[`statement.close()`][].
 
 ### `statement.stat(counter)`
 
@@ -1882,6 +1891,7 @@ callback function to indicate what type of operation is being authorized.
 [Run-Time Limits]: https://www.sqlite.org/c3ref/limit.html
 [SQL injection]: https://en.wikipedia.org/wiki/SQL_injection
 [Type conversion between JavaScript and SQLite]: #type-conversion-between-javascript-and-sqlite
+[`'sqlite.db.query'`]: diagnostics_channel.md#event-sqlitedbquery
 [`ATTACH DATABASE`]: https://www.sqlite.org/lang_attach.html
 [`ERR_INVALID_STATE`]: errors.md#err_invalid_state
 [`PRAGMA foreign_keys`]: https://www.sqlite.org/pragma.html#pragma_foreign_keys
@@ -1895,6 +1905,7 @@ callback function to indicate what type of operation is being authorized.
 [`database.createTagStore()`]: #databasecreatetagstoremaxsize
 [`database.serialize()`]: #databaseserializedbname
 [`database.setAuthorizer()`]: #databasesetauthorizercallback
+[`diagnostics_channel`]: diagnostics_channel.md
 [`sqlite3_backup_finish()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupfinish
 [`sqlite3_backup_init()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupinit
 [`sqlite3_backup_step()`]: https://www.sqlite.org/c3ref/backup_finish.html#sqlite3backupstep
@@ -1926,6 +1937,7 @@ callback function to indicate what type of operation is being authorized.
 [`sqlite3session_create()`]: https://www.sqlite.org/session/sqlite3session_create.html
 [`sqlite3session_delete()`]: https://www.sqlite.org/session/sqlite3session_delete.html
 [`sqlite3session_patchset()`]: https://www.sqlite.org/session/sqlite3session_patchset.html
+[`statement.close()`]: #statementclose
 [`statement.setAllowBareNamedParameters()`]: #statementsetallowbarenamedparametersenabled
 [`statement.setAllowUnknownNamedParameters()`]: #statementsetallowunknownnamedparametersenabled
 [`statement.stat()`]: #statementstatcounter

lib/diagnostics_channel.js

@@ -73,11 +73,19 @@ function markActive(channel) {
 ObjectSetPrototypeOf(channel,ActiveChannel.prototype);
 channel._subscribers=[];
 channel._stores=newSafeMap();
+
+// Notify native modules that this channel just got its first subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelActive(channel._index);
 }
 
 functionmaybeMarkInactive(channel){
 // When there are no more active subscribers or bound, restore to fast prototype.
 if(!channel._subscribers.length&&!channel._stores.size){
+// Notify native modules that this channel just lost its last subscriber.
+if(channel._index!==undefined)
+dc_binding.notifyChannelInactive(channel._index);
+
 // eslint-disable-next-line no-use-before-define
 ObjectSetPrototypeOf(channel,Channel.prototype);
 channel._subscribers=undefined;

src/base_object_types.h

@@ -24,7 +24,8 @@ namespace node {
 #defineUNSERIALIZABLE_BINDING_TYPES(V) \
 V(http2_binding_data, http2::BindingData) \
 V(http_parser_binding_data, http_parser::BindingData) \
-V(quic_binding_data, quic::BindingData)
+V(quic_binding_data, quic::BindingData) \
+V(sqlite_binding_data, sqlite::BindingData)
 
 // List of (non-binding) BaseObjects that are serializable in the snapshot.
 // The first argument should match what the type passes to

src/env_properties.h

@@ -143,6 +143,7 @@
  V(crypto_rsa_pss_string, "rsa-pss") \
  V(cwd_string, "cwd") \
  V(data_string, "data") \
+ V(database_string, "database") \
  V(default_is_true_string, "defaultIsTrue") \
  V(defensive_string, "defensive") \
  V(deserialize_info_string, "deserializeInfo") \
@@ -359,6 +360,7 @@
  V(source_map_url_string, "sourceMapURL") \
  V(source_url_string, "sourceURL") \
  V(specifier_string, "specifier") \
+ V(sql_string, "sql") \
  V(stack_string, "stack") \
  V(start_string, "start") \
  V(state_string, "state") \

src/node_diagnostics_channel.cc

@@ -127,10 +127,38 @@ void BindingData::Deserialize(Local<Context> context,
 CHECK_NOT_NULL(binding);
 }
 
+voidBindingData::SetChannelStatusCallback(uint32_t index,
+ ChannelStatusCallback cb) {
+ channel_status_callbacks_[index] = std::move(cb);
+}
+
+voidBindingData::NotifyChannelActive(const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(true);
+}
+
+voidBindingData::NotifyChannelInactive(
+const FunctionCallbackInfo<Value>& args) {
+ Realm* realm = Realm::GetCurrent(args);
+ BindingData* binding = realm->GetBindingData<BindingData>();
+if (binding == nullptr) return;
+CHECK(args[0]->IsUint32());
+uint32_t index = args[0].As<v8::Uint32>()->Value();
+auto it = binding->channel_status_callbacks_.find(index);
+if (it != binding->channel_status_callbacks_.end()) it->second(false);
+}
+
 voidBindingData::CreatePerIsolateProperties(IsolateData* isolate_data,
  Local<ObjectTemplate> target) {
  Isolate* isolate = isolate_data->isolate();
 SetMethod(isolate, target, "linkNativeChannel", LinkNativeChannel);
+SetMethod(isolate, target, "notifyChannelActive", NotifyChannelActive);
+SetMethod(isolate, target, "notifyChannelInactive", NotifyChannelInactive);
 }
 
 voidBindingData::CreatePerContextProperties(Local<Object> target,
@@ -145,6 +173,8 @@ void BindingData::CreatePerContextProperties(Local<Object> target,
 voidBindingData::RegisterExternalReferences(
  ExternalReferenceRegistry* registry) {
  registry->Register(LinkNativeChannel);
+ registry->Register(NotifyChannelActive);
+ registry->Register(NotifyChannelInactive);
 }
 
 Channel::Channel(Environment* env,

src/node_diagnostics_channel.h

@@ -4,6 +4,7 @@
 #if defined(NODE_WANT_INTERNALS) && NODE_WANT_INTERNALS
 
 #include<cinttypes>
+#include<functional>
 #include<string>
 #include<unordered_map>
 #include<vector>
@@ -52,6 +53,14 @@ class BindingData : public SnapshotableObject {
 staticvoidLinkNativeChannel(
 const v8::FunctionCallbackInfo<v8::Value>& args);
 
+using ChannelStatusCallback = std::function<void(bool is_active)>;
+voidSetChannelStatusCallback(uint32_t index, ChannelStatusCallback cb);
+
+staticvoidNotifyChannelActive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+staticvoidNotifyChannelInactive(
+const v8::FunctionCallbackInfo<v8::Value>& args);
+
 staticvoidCreatePerIsolateProperties(IsolateData* isolate_data,
  v8::Local<v8::ObjectTemplate> target);
 staticvoidCreatePerContextProperties(v8::Local<v8::Object> target,
@@ -62,6 +71,7 @@ class BindingData : public SnapshotableObject {
 
 private:
  InternalFieldInfo* internal_field_info_ = nullptr;
+ std::unordered_map<uint32_t, ChannelStatusCallback> channel_status_callbacks_;
 };
 
 classChannel : publicBaseObject {