mssql 12.3.1 → 12.5.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)
@@ -855,11 +856,22 @@ const config = sql.ConnectionPool.parseConnectionString('Server=localhost,1433;D
 ## Request
 
 ```javascript
-const request = new sql.Request(/* [pool or transaction] */)
+const request = new sql.Request(/* [pool or transaction], [options] */)
 ```
 
 If you omit pool/transaction argument, global pool is used instead.
 
+The optional `options` argument allows per-request configuration overrides:
+
+- **requestTimeout** - Override the pool's default request timeout (in ms) for this request only. This applies to queries and stored procedure executions; it does not apply to bulk data transfers (`request.bulk()`), which stream to completion as long as the connection is healthy. If you need to bound a bulk transfer, wrap the call with your own timer and call `request.cancel()`.
+
+```javascript
+// Request with a 60-second timeout instead of the pool default
+const request = new sql.Request(pool, { requestTimeout: 60000 })
+```
+
+**Note:** When using the global pool, you must still pass `undefined` as the first argument to use options: `new sql.Request(undefined, { requestTimeout: 60000 })`.
+
 ### Events
 
 - **recordset(columns)** - Dispatched when metadata for new recordset are parsed.
@@ -1225,11 +1237,13 @@ request.cancel()
 **IMPORTANT:** always use `Transaction` class to create transactions - it ensures that all your requests are executed on one connection. Once you call `begin`, a single connection is acquired from the connection pool and all subsequent requests (initialized with the `Transaction` object) are executed exclusively on this connection. After you call `commit` or `rollback`, connection is then released back to the connection pool.
 
 ```javascript
-const transaction = new sql.Transaction(/* [pool] */)
+const transaction = new sql.Transaction(/* [pool], [options] */)
 ```
 
 If you omit connection argument, global connection is used instead.
 
+The optional `options` argument allows per-transaction configuration overrides (e.g. `{ requestTimeout: 60000 }`). These are inherited by any requests created from this transaction unless overridden at the request level. Note that the timeout applies to data requests only, not to the `begin`/`commit`/`rollback` operations themselves.
+
 __Example__
 
 ```javascript
@@ -1377,11 +1391,13 @@ __Errors__
 **IMPORTANT:** always use `PreparedStatement` class to create prepared statements - it ensures that all your executions of prepared statement are executed on one connection. Once you call `prepare`, a single connection is acquired from the connection pool and all subsequent executions are executed exclusively on this connection. After you call `unprepare`, the connection is then released back to the connection pool.
 
 ```javascript
-const ps = new sql.PreparedStatement(/* [pool] */)
+const ps = new sql.PreparedStatement(/* [pool], [options] */)
 ```
 
 If you omit the connection argument, the global connection is used instead.
 
+The optional `options` argument allows per-statement configuration overrides (e.g. `{ requestTimeout: 60000 }`). The timeout is applied to the `prepare`, `execute`, and `unprepare` operations.
+
 __Example__
 
 ```javascript
@@ -2220,6 +2236,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)
@@ -576,21 +627,23 @@ class ConnectionPool extends EventEmitter {
   /**
    * Returns new request using this connection.
    *
+   * @param {{ requestTimeout?: number }} [conf] Per-request overrides.
    * @return {Request}
    */
 
-  request () {
-    return new shared.driver.Request(this)
+  request (conf) {
+    return new shared.driver.Request(this, conf)
   }
 
   /**
    * Returns new transaction using this connection.
    *
+   * @param {{ requestTimeout?: number }} [conf] Per-transaction overrides, cascaded to child requests.
    * @return {Transaction}
    */
 
-  transaction () {
-    return new shared.driver.Transaction(this)
+  transaction (conf) {
+    return new shared.driver.Transaction(this, conf)
   }
 
   /**

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.
@@ -20,10 +21,11 @@ class PreparedStatement extends EventEmitter {
   /**
    * Creates a new Prepared Statement.
    *
-   * @param {ConnectionPool|Transaction} [holder]
+   * @param {ConnectionPool|Transaction} [parent]
+   * @param {{ requestTimeout?: number }} [overrides]
    */
 
-  constructor (parent) {
+  constructor (parent, overrides = {}) {
     super()
 
     IDS.add(this, 'PreparedStatement')
@@ -33,6 +35,10 @@ class PreparedStatement extends EventEmitter {
     this._handle = 0
     this.prepared = false
     this.parameters = {}
+    this.overrides = {}
+    if (Number.isFinite(overrides?.requestTimeout) && overrides.requestTimeout >= 0) {
+      this.overrides.requestTimeout = overrides.requestTimeout
+    }
   }
 
   get config () {
@@ -194,16 +200,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)
+    }))
   }
 
   /**
@@ -232,7 +250,8 @@ class PreparedStatement extends EventEmitter {
       this._acquiredConnection = connection
       this._acquiredConfig = config
 
-      const req = new shared.driver.Request(this)
+      const req = new shared.driver.Request(this, this.overrides)
+      req._internal = true
       req.stream = false
       req.output('handle', TYPES.Int)
       req.input('params', TYPES.NVarChar, ((() => {
@@ -276,15 +295,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)
+    }))
   }
 
   /**
@@ -294,7 +333,8 @@ class PreparedStatement extends EventEmitter {
    */
 
   _execute (values, callback) {
-    const req = new shared.driver.Request(this)
+    const req = new shared.driver.Request(this, this.overrides)
+    req._internal = true
     req.stream = this.stream
     req.arrayRowMode = this.arrayRowMode
     req.input('handle', TYPES.Int, this._handle)
@@ -334,13 +374,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()
       })
     })
@@ -362,7 +414,8 @@ class PreparedStatement extends EventEmitter {
       return setImmediate(callback, new TransactionError("Can't unprepare the statement. There is a request in progress.", 'EREQINPROG'))
     }
 
-    const req = new shared.driver.Request(this)
+    const req = new shared.driver.Request(this, this.overrides)
+    req._internal = true
     req.stream = false
     req.input('handle', TYPES.Int, this._handle)
     req.execute('sp_unprepare', err => {