mssql 12.3.1 → 12.4.0

package/README.md

@@ -185,6 +185,7 @@ const config = {
 * [Metadata](#metadata)
 * [Data Types](#data-types)
 * [SQL injection](#sql-injection)
+* [Diagnostics Channel](#diagnostics-channel)
 * [Contributing](https://github.com/tediousjs/node-mssql/wiki/Contributing)
 * [11.x to 12.x changes](#11x-to-12x-changes)
 * [10.x to 11.x changes](#10x-to-11x-changes)
@@ -2220,6 +2221,103 @@ request.query('select @myval as myval', (err, result) => {
 })
 ```
 
+## Diagnostics Channel
+
+node-mssql publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), enabling APM tools and custom instrumentation to observe queries, connections, and internal events without modifying application code. When no subscribers are active, overhead is near-zero.
+
+All channel name constants are exported from the package:
+
+```js
+const { CHANNELS } = require('mssql')
+```
+
+### TracingChannels (async lifecycle)
+
+These use [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel) to wrap async operations, emitting `start`, `end`, `asyncStart`, `asyncEnd`, and `error` sub-events. Subscribe via `tracing:<name>:<event>`:
+
+```js
+const dc = require('node:diagnostics_channel')
+const { CHANNELS } = require('mssql')
+
+dc.subscribe(`tracing:${CHANNELS.TRACE_QUERY}:start`, ({ command, requestId }) => {
+  console.log(`[${requestId}] Query: ${command}`)
+})
+
+dc.subscribe(`tracing:${CHANNELS.TRACE_QUERY}:error`, ({ requestId, error }) => {
+  console.error(`[${requestId}] Failed:`, error.message)
+})
+```
+
+| Constant | Channel name | Wraps |
+|---|---|---|
+| `TRACE_QUERY` | `mssql:query` | `request.query()` |
+| `TRACE_BATCH` | `mssql:batch` | `request.batch()` |
+| `TRACE_EXECUTE` | `mssql:execute` | `request.execute()` |
+| `TRACE_BULK` | `mssql:bulk` | `request.bulk()` |
+| `TRACE_CONNECT` | `mssql:connect` | `pool.connect()` |
+| `TRACE_POOL_ACQUIRE` | `mssql:pool:acquire` | Pool connection acquire (wait time) |
+| `TRACE_PREPARED_STATEMENT_PREPARE` | `mssql:prepared-statement:prepare` | `ps.prepare()` |
+| `TRACE_PREPARED_STATEMENT_EXECUTE` | `mssql:prepared-statement:execute` | `ps.execute()` |
+
+TracingChannel contexts include identifiers (`requestId`, `poolId`), operation details (SQL text, procedure name, parameter names), and — on completion — `result` or `error`. Parameter **values** are never included (only their names).
+
+> **Note on SQL text in trace contexts:** `command` / `procedure` / `statement` fields contain the SQL text as sent to the server, to support OTel `db.query.text` conventions. Because node-mssql is parameterised-query-first, user-supplied values flow through `parameters` and do not appear in the SQL text. Avoid hard-coding credentials, tokens, or PII as inline SQL literals — anything hard-coded into a raw query will appear verbatim in trace contexts.
+
+> **Note on identifiers:** `connectionId`, `poolId`, `requestId`, `transactionId`, and `preparedStatementId` are monotonically increasing integers scoped to the current node process. They are not stable across restarts and cannot be used to correlate activity across processes.
+
+> **Note:** TracingChannel instrumentation fires for both the promise and callback APIs. The callback API is traced via Node's `TracingChannel#traceCallback`, which emits the same `start` / `end` / `asyncStart` / `asyncEnd` / `error` sub-events as the promise path, so subscribers do not need to branch by API style. Point-event channels (connection, transaction, pool lifecycle) likewise fire regardless of API style.
+
+### Point-event channels
+
+These emit single events at state transitions via `dc.subscribe()`:
+
+```js
+dc.subscribe(CHANNELS.CONNECTION_RELEASE, ({ connectionId, poolId }) => {
+  console.log(`Pool ${poolId}: connection ${connectionId} released`)
+})
+```
+
+| Constant | Channel name | Description |
+|---|---|---|
+| `CONNECTION_ACQUIRE` | `mssql:connection:acquire` | Connection borrowed from pool |
+| `CONNECTION_RELEASE` | `mssql:connection:release` | Connection returned to pool |
+| `CONNECTION_CREATE` | `mssql:connection:create` | New connection created in pool |
+| `CONNECTION_DESTROY` | `mssql:connection:destroy` | Connection destroyed |
+| `POOL_CLOSE` | `mssql:pool:close` | Pool closed (includes `reason`: `'closed'` or `'error'`; `error` on failure) |
+| `TRANSACTION_BEGIN` | `mssql:transaction:begin` | Transaction begun (includes numeric `isolationLevel` and `isolationLevelName`) |
+| `TRANSACTION_COMMIT` | `mssql:transaction:commit` | Transaction committed |
+| `TRANSACTION_ROLLBACK` | `mssql:transaction:rollback` | Transaction rolled back (includes `aborted` flag) |
+| `REQUEST_CANCEL` | `mssql:request:cancel` | Request cancelled |
+| `PREPARED_STATEMENT_UNPREPARE` | `mssql:prepared-statement:unprepare` | Prepared statement released |
+
+### Example: OpenTelemetry Spans
+
+```js
+const dc = require('node:diagnostics_channel')
+const { trace, SpanKind, SpanStatusCode } = require('@opentelemetry/api')
+const { CHANNELS } = require('mssql')
+
+const tracer = trace.getTracer('mssql')
+const queryTC = dc.tracingChannel(CHANNELS.TRACE_QUERY)
+
+queryTC.subscribe({
+  start (ctx) {
+    ctx.span = tracer.startSpan('mssql.query', {
+      kind: SpanKind.CLIENT,
+      attributes: { 'db.system': 'mssql', 'db.query.text': ctx.command },
+    })
+  },
+  asyncEnd (ctx) { ctx.span?.end() },
+  error (ctx) {
+    if (ctx.span) {
+      ctx.span.recordException(ctx.error)
+      ctx.span.setStatus({ code: SpanStatusCode.ERROR })
+      ctx.span.end()
+    }
+  },
+})
+```
+
 ## 11.x to 12.x changes
 
 - Config objects are no longer cloned by the library. Mutating a config object after passing it to a `ConnectionPool` results in undefined behaviour.

package/lib/base/connection-pool.js

@@ -8,6 +8,7 @@ const { IDS } = require('../utils')
 const ConnectionError = require('../error/connection-error')
 const shared = require('../shared')
 const { MSSQLError } = require('../error')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class ConnectionPool.
@@ -371,10 +372,26 @@ class ConnectionPool extends EventEmitter {
    */
 
   acquire (requester, callback) {
-    const acquirePromise = shared.Promise.resolve(this._acquire()).catch(err => {
-      this.emit('error', err)
-      throw err
-    })
+    const requestId = IDS.get(requester)
+    const poolId = IDS.get(this)
+
+    const acquirePromise = tracePromise(CHANNELS.TRACE_POOL_ACQUIRE, () => {
+      return shared.Promise.resolve(this._acquire()).catch(err => {
+        this.emit('error', err)
+        throw err
+      }).then(connection => {
+        publish(CHANNELS.CONNECTION_ACQUIRE, () => ({
+          connectionId: IDS.get(connection),
+          requestId,
+          poolId
+        }))
+        return connection
+      })
+    }, () => ({
+      poolId,
+      requestId
+    }))
+
     if (typeof callback === 'function') {
       acquirePromise.then(connection => callback(null, connection, this.config)).catch(callback)
       return this
@@ -403,6 +420,11 @@ class ConnectionPool extends EventEmitter {
   release (connection) {
     debug('connection(%d): released', IDS.get(connection))
 
+    publish(CHANNELS.CONNECTION_RELEASE, () => ({
+      connectionId: IDS.get(connection),
+      poolId: IDS.get(this)
+    }))
+
     if (this.pool) {
       this.pool.release(connection)
     }
@@ -418,16 +440,36 @@ class ConnectionPool extends EventEmitter {
 
   connect (callback) {
     if (typeof callback === 'function') {
-      this._connect(callback)
+      traceCallback(CHANNELS.TRACE_CONNECT, this._connect, 0, () => ({
+        server: this.config.server,
+        port: this.config.port,
+        database: this.config.database,
+        poolId: IDS.get(this),
+        poolConfig: {
+          min: (this.config.pool && this.config.pool.min) || 0,
+          max: (this.config.pool && this.config.pool.max) || 10
+        }
+      }), this, [callback])
       return this
     }
 
-    return new shared.Promise((resolve, reject) => {
-      return this._connect(err => {
-        if (err) return reject(err)
-        resolve(this)
+    return tracePromise(CHANNELS.TRACE_CONNECT, () => {
+      return new shared.Promise((resolve, reject) => {
+        return this._connect(err => {
+          if (err) return reject(err)
+          resolve(this)
+        })
       })
-    })
+    }, () => ({
+      server: this.config.server,
+      port: this.config.port,
+      database: this.config.database,
+      poolId: IDS.get(this),
+      poolConfig: {
+        min: (this.config.pool && this.config.pool.min) || 0,
+        max: (this.config.pool && this.config.pool.max) || 10
+      }
+    }))
   }
 
   /**
@@ -559,11 +601,20 @@ class ConnectionPool extends EventEmitter {
 
     this.pool.destroy().then(() => {
       debug('pool(%d): pool closed, removing pool reference and executing close callbacks', IDS.get(this))
+      publish(CHANNELS.POOL_CLOSE, () => ({
+        poolId: IDS.get(this),
+        reason: 'closed'
+      }))
       this.pool = null
       this._closeStack.forEach(cb => {
         setImmediate(cb, null)
       })
     }).catch(err => {
+      publish(CHANNELS.POOL_CLOSE, () => ({
+        poolId: IDS.get(this),
+        reason: 'error',
+        error: err
+      }))
       this.pool = null
       this._closeStack.forEach(cb => {
         setImmediate(cb, err)

package/lib/base/index.js

@@ -10,6 +10,7 @@ const Table = require('../table')
 const ISOLATION_LEVEL = require('../isolationlevel')
 const { TYPES } = require('../datatypes')
 const { connect, close, on, off, removeListener, query, batch } = require('../global-connection')
+const { CHANNELS } = require('../diagnostics')
 
 module.exports = {
   ConnectionPool,
@@ -31,6 +32,7 @@ module.exports = {
     Table,
     ISOLATION_LEVEL,
     TYPES,
+    CHANNELS,
     MAX: 65535, // (1 << 16) - 1
     map: shared.map,
     getTypeByValue: shared.getTypeByValue,

package/lib/base/prepared-statement.js

@@ -2,11 +2,12 @@
 
 const debug = require('debug')('mssql:base')
 const { EventEmitter } = require('node:events')
-const { IDS, objectHasProperty } = require('../utils')
+const { IDS, objectHasProperty, getPoolId } = require('../utils')
 const globalConnection = require('../global-connection')
 const { TransactionError, PreparedStatementError } = require('../error')
 const shared = require('../shared')
 const { TYPES, declare } = require('../datatypes')
+const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
 
 /**
  * Class PreparedStatement.
@@ -194,16 +195,28 @@ class PreparedStatement extends EventEmitter {
 
   prepare (statement, callback) {
     if (typeof callback === 'function') {
-      this._prepare(statement, callback)
+      traceCallback(CHANNELS.TRACE_PREPARED_STATEMENT_PREPARE, this._prepare, 1, () => ({
+        statement: statement || this.statement,
+        parameters: Object.keys(this.parameters),
+        preparedStatementId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this, [statement, callback])
       return this
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._prepare(statement, err => {
-        if (err) return reject(err)
-        resolve(this)
+    return tracePromise(CHANNELS.TRACE_PREPARED_STATEMENT_PREPARE, () => {
+      return new shared.Promise((resolve, reject) => {
+        this._prepare(statement, err => {
+          if (err) return reject(err)
+          resolve(this)
+        })
       })
-    })
+    }, () => ({
+      statement: statement || this.statement,
+      parameters: Object.keys(this.parameters),
+      preparedStatementId: IDS.get(this),
+      poolId: getPoolId(this)
+    }))
   }
 
   /**
@@ -233,6 +246,7 @@ class PreparedStatement extends EventEmitter {
       this._acquiredConfig = config
 
       const req = new shared.driver.Request(this)
+      req._internal = true
       req.stream = false
       req.output('handle', TYPES.Int)
       req.input('params', TYPES.NVarChar, ((() => {
@@ -276,15 +290,35 @@ class PreparedStatement extends EventEmitter {
 
   execute (values, callback) {
     if (this.stream || (typeof callback === 'function')) {
-      return this._execute(values, callback)
+      if (typeof callback !== 'function') {
+        // Stream mode without a callback: no async boundary for traceCallback
+        // to hook — fall through to the untraced call. Subscribers interested
+        // in streaming completion should listen to Request events.
+        return this._execute(values, callback)
+      }
+      return traceCallback(CHANNELS.TRACE_PREPARED_STATEMENT_EXECUTE, this._execute, 1, () => ({
+        statement: this.statement,
+        parameters: Object.keys(this.parameters),
+        handle: this._handle,
+        preparedStatementId: IDS.get(this),
+        poolId: getPoolId(this)
+      }), this, [values, callback])
     }
 
-    return new shared.Promise((resolve, reject) => {
-      this._execute(values, (err, recordset) => {
-        if (err) return reject(err)
-        resolve(recordset)
+    return tracePromise(CHANNELS.TRACE_PREPARED_STATEMENT_EXECUTE, () => {
+      return new shared.Promise((resolve, reject) => {
+        this._execute(values, (err, recordset) => {
+          if (err) return reject(err)
+          resolve(recordset)
+        })
       })
-    })
+    }, () => ({
+      statement: this.statement,
+      parameters: Object.keys(this.parameters),
+      handle: this._handle,
+      preparedStatementId: IDS.get(this),
+      poolId: getPoolId(this)
+    }))
   }
 
   /**
@@ -295,6 +329,7 @@ class PreparedStatement extends EventEmitter {
 
   _execute (values, callback) {
     const req = new shared.driver.Request(this)
+    req._internal = true
     req.stream = this.stream
     req.arrayRowMode = this.arrayRowMode
     req.input('handle', TYPES.Int, this._handle)
@@ -334,13 +369,25 @@ class PreparedStatement extends EventEmitter {
 
   unprepare (callback) {
     if (typeof callback === 'function') {
-      this._unprepare(callback)
+      this._unprepare(err => {
+        if (!err) {
+          publish(CHANNELS.PREPARED_STATEMENT_UNPREPARE, () => ({
+            preparedStatementId: IDS.get(this),
+            poolId: getPoolId(this)
+          }))
+        }
+        callback(err)
+      })
       return this
     }
 
     return new shared.Promise((resolve, reject) => {
       this._unprepare(err => {
         if (err) return reject(err)
+        publish(CHANNELS.PREPARED_STATEMENT_UNPREPARE, () => ({
+          preparedStatementId: IDS.get(this),
+          poolId: getPoolId(this)
+        }))
         resolve()
       })
     })
@@ -363,6 +410,7 @@ class PreparedStatement extends EventEmitter {
     }
 
     const req = new shared.driver.Request(this)
+    req._internal = true
     req.stream = false
     req.input('handle', TYPES.Int, this._handle)
     req.execute('sp_unprepare', err => {

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()
         })
 

package/lib/tedious/transaction.js

@@ -4,6 +4,7 @@ const debug = require('debug')('mssql:tedi')
 const BaseTransaction = require('../base/transaction')
 const { IDS } = require('../utils')
 const TransactionError = require('../error/transaction-error')
+const { CHANNELS, publish } = require('../diagnostics')
 
 class Transaction extends BaseTransaction {
   constructor (parent) {
@@ -23,6 +24,10 @@ class Transaction extends BaseTransaction {
         this._acquiredConfig = null
         this._aborted = true
 
+        publish(CHANNELS.TRANSACTION_ROLLBACK, () => ({
+          transactionId: IDS.get(this),
+          aborted: true
+        }))
         this.emit('rollback', true)
       }
     }

package/lib/udt.js

@@ -44,6 +44,12 @@ const SEGMENT = {
   FIRST_ARC: 0x03
 }; */
 
+const ensureBytes = (buffer, needed) => {
+  if (buffer.position + needed > buffer.length) {
+    throw new Error(`Corrupt or truncated spatial data: expected ${needed} bytes at position ${buffer.position}, but only ${buffer.length - buffer.position} bytes remain`)
+  }
+}
+
 class Point {
   constructor () {
     this.x = 0
@@ -64,6 +70,8 @@ const parsePoints = (buffer, count, isGeometryPoint) => {
     return points
   }
 
+  ensureBytes(buffer, count * 16)
+
   if (isGeometryPoint) {
     // GEOMETRY POINT (s2.1.6): x then y.
     for (let i = 1; i <= count; i++) {
@@ -101,6 +109,8 @@ const parseZ = (buffer, points) => {
     return
   }
 
+  ensureBytes(buffer, points.length * 8)
+
   points.forEach(point => {
     point.z = buffer.readDoubleLE(buffer.position)
     buffer.position += 8
@@ -114,6 +124,8 @@ const parseM = (buffer, points) => {
     return
   }
 
+  ensureBytes(buffer, points.length * 8)
+
   points.forEach(point => {
     point.m = buffer.readDoubleLE(buffer.position)
     buffer.position += 8
@@ -139,6 +151,8 @@ const parseFigures = (buffer, count, properties) => {
       pointOffset: 0
     })
   } else {
+    ensureBytes(buffer, count * 5)
+
     for (let i = 1; i <= count; i++) {
       figures.push({
         attribute: buffer.readUInt8(buffer.position),
@@ -173,6 +187,8 @@ const parseShapes = (buffer, count, properties) => {
       type: 0x02
     })
   } else {
+    ensureBytes(buffer, count * 9)
+
     for (let i = 1; i <= count; i++) {
       shapes.push({
         parentOffset: buffer.readInt32LE(buffer.position),
@@ -195,6 +211,8 @@ const parseSegments = (buffer, count) => {
     return segments
   }
 
+  ensureBytes(buffer, count)
+
   for (let i = 1; i <= count; i++) {
     segments.push({ type: buffer.readUInt8(buffer.position) })
 
@@ -207,6 +225,8 @@ const parseSegments = (buffer, count) => {
 const parseGeography = (buffer, isUsingGeometryPoints) => {
   // s2.1.1 + s.2.1.2
 
+  ensureBytes(buffer, 6)
+
   const srid = buffer.readInt32LE(0)
   if (srid === -1) {
     return null
@@ -220,9 +240,6 @@ const parseGeography = (buffer, isUsingGeometryPoints) => {
   const flags = buffer.readUInt8(5)
   buffer.position = 6
 
-  // console.log("srid", srid)
-  // console.log("version", version)
-
   const properties = {
     Z: (flags & (1 << 0)) > 0,
     M: (flags & (1 << 1)) > 0,
@@ -232,23 +249,20 @@ const parseGeography = (buffer, isUsingGeometryPoints) => {
   }
 
   if (value.version === 2) {
-    properties.H = (flags & (1 << 3)) > 0
+    properties.H = (flags & (1 << 5)) > 0
   }
 
-  // console.log("properties", properties);
-
   let numberOfPoints
   if (properties.P) {
     numberOfPoints = 1
   } else if (properties.L) {
     numberOfPoints = 2
   } else {
+    ensureBytes(buffer, 4)
     numberOfPoints = buffer.readUInt32LE(buffer.position)
     buffer.position += 4
   }
 
-  // console.log("numberOfPoints", numberOfPoints)
-
   value.points = parsePoints(buffer, numberOfPoints, isUsingGeometryPoints)
 
   if (properties.Z) {
@@ -259,49 +273,37 @@ const parseGeography = (buffer, isUsingGeometryPoints) => {
     parseM(buffer, value.points)
   }
 
-  // console.log("points", points)
-
   let numberOfFigures
   if (properties.P) {
     numberOfFigures = 1
   } else if (properties.L) {
     numberOfFigures = 1
   } else {
+    ensureBytes(buffer, 4)
     numberOfFigures = buffer.readUInt32LE(buffer.position)
     buffer.position += 4
   }
 
-  // console.log("numberOfFigures", numberOfFigures)
-
   value.figures = parseFigures(buffer, numberOfFigures, properties)
 
-  // console.log("figures", figures)
-
   let numberOfShapes
   if (properties.P) {
     numberOfShapes = 1
   } else if (properties.L) {
     numberOfShapes = 1
   } else {
+    ensureBytes(buffer, 4)
     numberOfShapes = buffer.readUInt32LE(buffer.position)
     buffer.position += 4
   }
 
-  // console.log("numberOfShapes", numberOfShapes)
-
   value.shapes = parseShapes(buffer, numberOfShapes, properties)
 
-  // console.log( "shapes", shapes)
-
-  if (value.version === 2 && buffer.position < buffer.length) {
+  if (value.version === 2 && buffer.position + 4 <= buffer.length) {
     const numberOfSegments = buffer.readUInt32LE(buffer.position)
     buffer.position += 4
 
-    // console.log("numberOfSegments", numberOfSegments)
-
     value.segments = parseSegments(buffer, numberOfSegments)
-
-    // console.log("segments", segments)
   } else {
     value.segments = []
   }

package/lib/utils.js

@@ -9,6 +9,14 @@ const INCREMENT = {
   PreparedStatement: 1
 }
 
+const getPoolId = (obj) => {
+  let parent = obj && obj.parent
+  while (parent && !parent.pool) {
+    parent = parent.parent
+  }
+  return parent ? IDS.get(parent) : undefined
+}
+
 module.exports = {
   objectHasProperty: (object, property) => Object.prototype.hasOwnProperty.call(object, property),
   INCREMENT,
@@ -18,5 +26,6 @@ module.exports = {
       if (id) return IDS.set(object, id)
       IDS.set(object, INCREMENT[type]++)
     }
-  }
+  },
+  getPoolId
 }

package/package.json

@@ -21,7 +21,7 @@
     "azure",
     "node-mssql"
   ],
-  "version": "12.3.1",
+  "version": "12.4.0",
   "main": "index.js",
   "type": "commonjs",
   "repository": {
@@ -52,7 +52,7 @@
     "standard": "^17.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.19.0"
   },
   "files": [
     "lib/",