mssql 12.3.0 → 12.4.0

package/lib/base/request.js

@@ -3,11 +3,12 @@
 const debug = require('debug')('mssql:base')
 const { EventEmitter } = require('node:events')
 const { Readable } = require('node:stream')
-const { IDS, objectHasProperty } = require('../utils')
+const { IDS, objectHasProperty, getPoolId } = require('../utils')
 const globalConnection = require('../global-connection')
 const { RequestError, ConnectionError } = require('../error')
 const { TYPES } = require('../datatypes')
 const shared = require('../shared')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class Request.
@@ -37,6 +38,7 @@ class Request extends EventEmitter {
 
     this.canceled = false
     this._paused = false
+    this._internal = false
     this.parent = parent || globalConnection.pool
     this.parameters = {}
     this.stream = null
@@ -218,6 +220,24 @@ class Request extends EventEmitter {
     return this.output(name, type, value)
   }
 
+  _getParameterNames () {
+    return Object.keys(this.parameters)
+  }
+
+  _tracedPromise (channel, contextFactory, fn) {
+    if (this._internal) {
+      return fn()
+    }
+    return tracePromise(channel, fn, contextFactory)
+  }
+
+  _tracedCallback (channel, contextFactory, fn, position, args) {
+    if (this._internal) {
+      return fn.apply(this, args)
+    }
+    return traceCallback(channel, fn, position, contextFactory, this, args)
+  }
+
   /**
    * Execute the SQL batch.
    *
@@ -232,7 +252,11 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._batch(batch, (err, recordsets, output, rowsAffected) => {
+      this._tracedCallback(CHANNELS.TRACE_BATCH, () => ({
+        command: batch,
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._batch, 1, [batch, (err, recordsets, output, rowsAffected) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -250,7 +274,7 @@ class Request extends EventEmitter {
           output,
           rowsAffected
         })
-      })
+      }])
       return this
     }
 
@@ -261,24 +285,31 @@ class Request extends EventEmitter {
       batch = this._template(strings, values)
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._batch(batch, (err, recordsets, output, rowsAffected) => {
-        if (this.stream) {
-          if (err) this.emit('error', err)
-          err = null
+    const batchCommand = batch
+    return this._tracedPromise(CHANNELS.TRACE_BATCH, () => ({
+      command: batchCommand,
+      requestId: IDS.get(this),
+      poolId: getPoolId(this)
+    }), () => {
+      return new shared.Promise((resolve, reject) => {
+        this._batch(batchCommand, (err, recordsets, output, rowsAffected) => {
+          if (this.stream) {
+            if (err) this.emit('error', err)
+            err = null
+
+            this.emit('done', {
+              output,
+              rowsAffected
+            })
+          }
 
-          this.emit('done', {
+          if (err) return reject(err)
+          resolve({
+            recordsets,
+            recordset: recordsets && recordsets[0],
             output,
             rowsAffected
           })
-        }
-
-        if (err) return reject(err)
-        resolve({
-          recordsets,
-          recordset: recordsets && recordsets[0],
-          output,
-          rowsAffected
         })
       })
     })
@@ -324,7 +355,12 @@ class Request extends EventEmitter {
     if (this.arrayRowMode === null && this.parent) this.arrayRowMode = this.parent.config.arrayRowMode
 
     if (this.stream || typeof callback === 'function') {
-      this._bulk(table, options, (err, rowsAffected) => {
+      this._tracedCallback(CHANNELS.TRACE_BULK, () => ({
+        table: table.path || table.name,
+        rowCount: table.rows ? table.rows.length : 0,
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._bulk, 2, [table, options, (err, rowsAffected) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           return this.emit('done', {
@@ -336,15 +372,22 @@ class Request extends EventEmitter {
         callback(null, {
           rowsAffected
         })
-      })
+      }])
       return this
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._bulk(table, options, (err, rowsAffected) => {
-        if (err) return reject(err)
-        resolve({
-          rowsAffected
+    return this._tracedPromise(CHANNELS.TRACE_BULK, () => ({
+      table: table.path || table.name,
+      rowCount: table.rows ? table.rows.length : 0,
+      requestId: IDS.get(this),
+      poolId: getPoolId(this)
+    }), () => {
+      return new shared.Promise((resolve, reject) => {
+        this._bulk(table, options, (err, rowsAffected) => {
+          if (err) return reject(err)
+          resolve({
+            rowsAffected
+          })
         })
       })
     })
@@ -429,7 +472,12 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._query(command, (err, recordsets, output, rowsAffected, columns) => {
+      this._tracedCallback(CHANNELS.TRACE_QUERY, () => ({
+        command,
+        parameters: this._getParameterNames(),
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._query, 1, [command, (err, recordsets, output, rowsAffected, columns) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -449,7 +497,7 @@ class Request extends EventEmitter {
         }
         if (this.arrayRowMode) result.columns = columns
         callback(null, result)
-      })
+      }])
       return this
     }
 
@@ -460,27 +508,34 @@ class Request extends EventEmitter {
       command = this._template(strings, values)
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._query(command, (err, recordsets, output, rowsAffected, columns) => {
-        if (this.stream) {
-          if (err) this.emit('error', err)
-          err = null
+    return this._tracedPromise(CHANNELS.TRACE_QUERY, () => ({
+      command,
+      parameters: this._getParameterNames(),
+      requestId: IDS.get(this),
+      poolId: getPoolId(this)
+    }), () => {
+      return new shared.Promise((resolve, reject) => {
+        this._query(command, (err, recordsets, output, rowsAffected, columns) => {
+          if (this.stream) {
+            if (err) this.emit('error', err)
+            err = null
+
+            this.emit('done', {
+              output,
+              rowsAffected
+            })
+          }
 
-          this.emit('done', {
+          if (err) return reject(err)
+          const result = {
+            recordsets,
+            recordset: recordsets && recordsets[0],
             output,
             rowsAffected
-          })
-        }
-
-        if (err) return reject(err)
-        const result = {
-          recordsets,
-          recordset: recordsets && recordsets[0],
-          output,
-          rowsAffected
-        }
-        if (this.arrayRowMode) result.columns = columns
-        resolve(result)
+          }
+          if (this.arrayRowMode) result.columns = columns
+          resolve(result)
+        })
       })
     })
   }
@@ -518,7 +573,12 @@ class Request extends EventEmitter {
     this.rowsAffected = 0
 
     if (typeof callback === 'function') {
-      this._execute(command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
+      this._tracedCallback(CHANNELS.TRACE_EXECUTE, () => ({
+        procedure: command,
+        parameters: this._getParameterNames(),
+        requestId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this._execute, 1, [command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
         if (this.stream) {
           if (err) this.emit('error', err)
           err = null
@@ -540,33 +600,40 @@ class Request extends EventEmitter {
         }
         if (this.arrayRowMode) result.columns = columns
         callback(null, result)
-      })
+      }])
       return this
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._execute(command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
-        if (this.stream) {
-          if (err) this.emit('error', err)
-          err = null
+    return this._tracedPromise(CHANNELS.TRACE_EXECUTE, () => ({
+      procedure: command,
+      parameters: this._getParameterNames(),
+      requestId: IDS.get(this),
+      poolId: getPoolId(this)
+    }), () => {
+      return new shared.Promise((resolve, reject) => {
+        this._execute(command, (err, recordsets, output, returnValue, rowsAffected, columns) => {
+          if (this.stream) {
+            if (err) this.emit('error', err)
+            err = null
+
+            this.emit('done', {
+              output,
+              rowsAffected,
+              returnValue
+            })
+          }
 
-          this.emit('done', {
+          if (err) return reject(err)
+          const result = {
+            recordsets,
+            recordset: recordsets && recordsets[0],
             output,
             rowsAffected,
             returnValue
-          })
-        }
-
-        if (err) return reject(err)
-        const result = {
-          recordsets,
-          recordset: recordsets && recordsets[0],
-          output,
-          rowsAffected,
-          returnValue
-        }
-        if (this.arrayRowMode) result.columns = columns
-        resolve(result)
+          }
+          if (this.arrayRowMode) result.columns = columns
+          resolve(result)
+        })
       })
     })
   }
@@ -598,6 +665,11 @@ class Request extends EventEmitter {
 
   cancel () {
     this._cancel()
+    if (!this._internal) {
+      publish(CHANNELS.REQUEST_CANCEL, () => ({
+        requestId: IDS.get(this)
+      }))
+    }
     return true
   }
 

package/lib/base/transaction.js

@@ -2,11 +2,16 @@
 
 const debug = require('debug')('mssql:base')
 const { EventEmitter } = require('node:events')
-const { IDS } = require('../utils')
+const { IDS, getPoolId } = require('../utils')
 const globalConnection = require('../global-connection')
 const { TransactionError } = require('../error')
 const shared = require('../shared')
 const ISOLATION_LEVEL = require('../isolationlevel')
+const { CHANNELS, publish } = require('../diagnostics')
+
+const ISOLATION_LEVEL_NAMES = Object.fromEntries(
+  Object.entries(ISOLATION_LEVEL).map(([name, value]) => [value, name])
+)
 
 /**
  * Class Transaction.
@@ -101,6 +106,12 @@ class Transaction extends EventEmitter {
     if (typeof callback === 'function') {
       this._begin(isolationLevel, err => {
         if (!err) {
+          publish(CHANNELS.TRANSACTION_BEGIN, () => ({
+            transactionId: IDS.get(this),
+            isolationLevel: this.isolationLevel,
+            isolationLevelName: ISOLATION_LEVEL_NAMES[this.isolationLevel],
+            poolId: getPoolId(this)
+          }))
           this.emit('begin')
         }
         callback(err)
@@ -111,6 +122,12 @@ class Transaction extends EventEmitter {
     return new shared.Promise((resolve, reject) => {
       this._begin(isolationLevel, err => {
         if (err) return reject(err)
+        publish(CHANNELS.TRANSACTION_BEGIN, () => ({
+          transactionId: IDS.get(this),
+          isolationLevel: this.isolationLevel,
+          isolationLevelName: ISOLATION_LEVEL_NAMES[this.isolationLevel],
+          poolId: getPoolId(this)
+        }))
         this.emit('begin')
         resolve(this)
       })
@@ -155,6 +172,9 @@ class Transaction extends EventEmitter {
     if (typeof callback === 'function') {
       this._commit(err => {
         if (!err) {
+          publish(CHANNELS.TRANSACTION_COMMIT, () => ({
+            transactionId: IDS.get(this)
+          }))
           this.emit('commit')
         }
         callback(err)
@@ -165,6 +185,9 @@ class Transaction extends EventEmitter {
     return new shared.Promise((resolve, reject) => {
       this._commit(err => {
         if (err) return reject(err)
+        publish(CHANNELS.TRANSACTION_COMMIT, () => ({
+          transactionId: IDS.get(this)
+        }))
         this.emit('commit')
         resolve()
       })
@@ -214,6 +237,10 @@ class Transaction extends EventEmitter {
     if (typeof callback === 'function') {
       this._rollback(err => {
         if (!err) {
+          publish(CHANNELS.TRANSACTION_ROLLBACK, () => ({
+            transactionId: IDS.get(this),
+            aborted: this._aborted
+          }))
           this.emit('rollback', this._aborted)
         }
         callback(err)
@@ -224,6 +251,10 @@ class Transaction extends EventEmitter {
     return new shared.Promise((resolve, reject) => {
       return this._rollback(err => {
         if (err) return reject(err)
+        publish(CHANNELS.TRANSACTION_ROLLBACK, () => ({
+          transactionId: IDS.get(this),
+          aborted: this._aborted
+        }))
         this.emit('rollback', this._aborted)
         resolve()
       })

package/lib/diagnostics.js

@@ -0,0 +1,153 @@
+'use strict'
+
+const dc = require('node:diagnostics_channel')
+
+// TracingChannel names
+const TRACE_QUERY = 'mssql:query'
+const TRACE_BATCH = 'mssql:batch'
+const TRACE_EXECUTE = 'mssql:execute'
+const TRACE_BULK = 'mssql:bulk'
+const TRACE_CONNECT = 'mssql:connect'
+const TRACE_POOL_ACQUIRE = 'mssql:pool:acquire'
+const TRACE_PREPARED_STATEMENT_PREPARE = 'mssql:prepared-statement:prepare'
+const TRACE_PREPARED_STATEMENT_EXECUTE = 'mssql:prepared-statement:execute'
+
+// Point-event channel names
+const CONNECTION_ACQUIRE = 'mssql:connection:acquire'
+const CONNECTION_RELEASE = 'mssql:connection:release'
+const CONNECTION_CREATE = 'mssql:connection:create'
+const CONNECTION_DESTROY = 'mssql:connection:destroy'
+const POOL_CLOSE = 'mssql:pool:close'
+const TRANSACTION_BEGIN = 'mssql:transaction:begin'
+const TRANSACTION_COMMIT = 'mssql:transaction:commit'
+const TRANSACTION_ROLLBACK = 'mssql:transaction:rollback'
+const REQUEST_CANCEL = 'mssql:request:cancel'
+const PREPARED_STATEMENT_UNPREPARE = 'mssql:prepared-statement:unprepare'
+
+const CHANNELS = Object.freeze({
+  TRACE_QUERY,
+  TRACE_BATCH,
+  TRACE_EXECUTE,
+  TRACE_BULK,
+  TRACE_CONNECT,
+  TRACE_POOL_ACQUIRE,
+  TRACE_PREPARED_STATEMENT_PREPARE,
+  TRACE_PREPARED_STATEMENT_EXECUTE,
+  CONNECTION_ACQUIRE,
+  CONNECTION_RELEASE,
+  CONNECTION_CREATE,
+  CONNECTION_DESTROY,
+  POOL_CLOSE,
+  TRANSACTION_BEGIN,
+  TRANSACTION_COMMIT,
+  TRANSACTION_ROLLBACK,
+  REQUEST_CANCEL,
+  PREPARED_STATEMENT_UNPREPARE
+})
+
+// Pre-create TracingChannel instances at module load time
+const tracingChannels = {
+  [TRACE_QUERY]: dc.tracingChannel(TRACE_QUERY),
+  [TRACE_BATCH]: dc.tracingChannel(TRACE_BATCH),
+  [TRACE_EXECUTE]: dc.tracingChannel(TRACE_EXECUTE),
+  [TRACE_BULK]: dc.tracingChannel(TRACE_BULK),
+  [TRACE_CONNECT]: dc.tracingChannel(TRACE_CONNECT),
+  [TRACE_POOL_ACQUIRE]: dc.tracingChannel(TRACE_POOL_ACQUIRE),
+  [TRACE_PREPARED_STATEMENT_PREPARE]: dc.tracingChannel(TRACE_PREPARED_STATEMENT_PREPARE),
+  [TRACE_PREPARED_STATEMENT_EXECUTE]: dc.tracingChannel(TRACE_PREPARED_STATEMENT_EXECUTE)
+}
+
+// Pre-create point-event channel instances at module load time
+const pointChannels = {
+  [CONNECTION_ACQUIRE]: dc.channel(CONNECTION_ACQUIRE),
+  [CONNECTION_RELEASE]: dc.channel(CONNECTION_RELEASE),
+  [CONNECTION_CREATE]: dc.channel(CONNECTION_CREATE),
+  [CONNECTION_DESTROY]: dc.channel(CONNECTION_DESTROY),
+  [POOL_CLOSE]: dc.channel(POOL_CLOSE),
+  [TRANSACTION_BEGIN]: dc.channel(TRANSACTION_BEGIN),
+  [TRANSACTION_COMMIT]: dc.channel(TRANSACTION_COMMIT),
+  [TRANSACTION_ROLLBACK]: dc.channel(TRANSACTION_ROLLBACK),
+  [REQUEST_CANCEL]: dc.channel(REQUEST_CANCEL),
+  [PREPARED_STATEMENT_UNPREPARE]: dc.channel(PREPARED_STATEMENT_UNPREPARE)
+}
+
+// TracingChannel.hasSubscribers was added in Node 22. On 18.19 / 20 the
+// aggregate property is undefined, so we fall back to checking the
+// sub-channels directly (these have existed since the original
+// diagnostics_channel API). Preserves the zero-cost fast path across all
+// supported runtimes.
+function tracingChannelHasSubscribers (tc) {
+  if (typeof tc.hasSubscribers === 'boolean') return tc.hasSubscribers
+  return tc.start.hasSubscribers ||
+    tc.end.hasSubscribers ||
+    tc.asyncStart.hasSubscribers ||
+    tc.asyncEnd.hasSubscribers ||
+    tc.error.hasSubscribers
+}
+
+/**
+ * Trace an async operation using a TracingChannel.
+ *
+ * When subscribers are active, wraps `fn` with TracingChannel.tracePromise().
+ * When no subscribers are active, calls `fn` directly with zero overhead
+ * (no context allocation).
+ *
+ * @param {string} name - TracingChannel name (one of CHANNELS.TRACE_*)
+ * @param {Function} fn - The function to trace (must return a Promise)
+ * @param {Function} contextFactory - Factory function returning the context object
+ * @returns {Promise} The return value of fn
+ */
+function tracePromise (name, fn, contextFactory) {
+  const channel = tracingChannels[name]
+  if (tracingChannelHasSubscribers(channel)) {
+    return channel.tracePromise(fn, contextFactory())
+  }
+  return fn()
+}
+
+/**
+ * Trace a callback-style async operation using a TracingChannel.
+ *
+ * When subscribers are active, delegates to TracingChannel.traceCallback,
+ * which replaces the callback at `position` in `args` with a wrapped
+ * version that publishes to start/end/asyncStart/asyncEnd/error. When
+ * no subscribers are active, calls `fn` directly with zero overhead.
+ *
+ * @param {string} name - TracingChannel name (one of CHANNELS.TRACE_*)
+ * @param {Function} fn - The function to call (receives callback at `position`)
+ * @param {number} position - Index of the callback within `args`
+ * @param {Function} contextFactory - Factory function returning the context object
+ * @param {*} thisArg - `this` binding for fn
+ * @param {Array} args - Arguments to pass to fn (includes the callback at `position`)
+ * @returns {*} The return value of fn
+ */
+function traceCallback (name, fn, position, contextFactory, thisArg, args) {
+  const channel = tracingChannels[name]
+  if (tracingChannelHasSubscribers(channel)) {
+    return channel.traceCallback(fn, position, contextFactory(), thisArg, ...args)
+  }
+  return fn.apply(thisArg, args)
+}
+
+/**
+ * Publish a point event on a named channel.
+ *
+ * Only allocates the message object when subscribers are active.
+ *
+ * @param {string} name - Point-event channel name (one of CHANNELS.*)
+ * @param {Function} factory - Factory function that returns the message object
+ */
+function publish (name, factory) {
+  const channel = pointChannels[name]
+  if (channel.hasSubscribers) {
+    channel.publish(factory())
+  }
+}
+
+module.exports = {
+  CHANNELS,
+  tracingChannels,
+  tracePromise,
+  traceCallback,
+  publish
+}

package/lib/msnodesqlv8/connection-pool.js

@@ -8,6 +8,7 @@ const shared = require('../shared')
 const ConnectionError = require('../error/connection-error')
 const { platform } = require('node:os')
 const { build } = require('@tediousjs/connection-string')
+const { CHANNELS, publish } = require('../diagnostics')
 
 const DEFAULT_CONNECTION_DRIVER = ['darwin', 'linux'].includes(platform()) ? 'ODBC Driver 17 for SQL Server' : 'SQL Server Native Client 11.0'
 
@@ -58,6 +59,12 @@ class ConnectionPool extends BaseConnectionPool {
         IDS.add(tds, 'Connection', connedtionId)
         tds.setUseUTC(this.config.options.useUTC)
         debug('connection(%d): established', IDS.get(tds))
+        publish(CHANNELS.CONNECTION_CREATE, () => ({
+          connectionId: IDS.get(tds),
+          poolId: IDS.get(this),
+          server: this.config.server,
+          database: this.config.database
+        }))
         resolve(tds)
       })
     })
@@ -80,9 +87,15 @@ class ConnectionPool extends BaseConnectionPool {
         resolve()
         return
       }
-      debug('connection(%d): destroying', IDS.get(tds))
+      const connectionId = IDS.get(tds)
+      const poolId = IDS.get(this)
+      debug('connection(%d): destroying', connectionId)
       tds.close(() => {
-        debug('connection(%d): destroyed', IDS.get(tds))
+        debug('connection(%d): destroyed', connectionId)
+        publish(CHANNELS.CONNECTION_DESTROY, () => ({
+          connectionId,
+          poolId
+        }))
         resolve()
       })
     })

package/lib/tedious/connection-pool.js

@@ -6,6 +6,7 @@ const BaseConnectionPool = require('../base/connection-pool')
 const { IDS } = require('../utils')
 const shared = require('../shared')
 const ConnectionError = require('../error/connection-error')
+const { CHANNELS, publish } = require('../diagnostics')
 
 class ConnectionPool extends BaseConnectionPool {
   _config () {
@@ -88,6 +89,12 @@ class ConnectionPool extends BaseConnectionPool {
 
         debug('connection(%d): established', IDS.get(tedious))
         this.collation = tedious.databaseCollation
+        publish(CHANNELS.CONNECTION_CREATE, () => ({
+          connectionId: IDS.get(tedious),
+          poolId: IDS.get(this),
+          server: this.config.server,
+          database: this.config.database
+        }))
         resolveOnce(tedious)
       })
       IDS.add(tedious, 'Connection')
@@ -156,6 +163,8 @@ class ConnectionPool extends BaseConnectionPool {
         return
       }
       debug('connection(%d): destroying', IDS.get(tedious))
+      const connectionId = IDS.get(tedious)
+      const poolId = IDS.get(this)
 
       if (tedious.closed) {
         debug('connection(%d): already closed', IDS.get(tedious))
@@ -163,6 +172,10 @@ class ConnectionPool extends BaseConnectionPool {
       } else {
         tedious.once('end', () => {
           debug('connection(%d): destroyed', IDS.get(tedious))
+          publish(CHANNELS.CONNECTION_DESTROY, () => ({
+            connectionId,
+            poolId
+          }))
           resolve()
         })