mssql 12.3.0 → 12.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Microsoft SQL Server client for Node.js**
 
-[![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![Appveyor CI][appveyor-image]][appveyor-url] [![Join the chat at https://gitter.im/patriksimek/node-mssql](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/patriksimek/node-mssql?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url]
 
 Supported TDS drivers:
 
@@ -137,6 +137,8 @@ const config = {
 * [ConnectionPool](#connections-1)
 * [connect](#connect-callback)
 * [close](#close)
+* [Pool properties](#pool-properties)
+* [parseConnectionString](#connectionpoolparseconnectionstring-connectionstring)
 
 ### Requests
 
@@ -144,6 +146,8 @@ const config = {
 * [execute](#execute-procedure-callback)
 * [input](#input-name-type-value)
 * [output](#output-name-type-value)
+* [replaceInput](#replaceinput-name-type-value-1)
+* [replaceOutput](#replaceoutput-name-type-value)
 * [toReadableStream](#toReadableStream)
 * [pipe](#pipe-stream)
 * [query](#query-command-callback)
@@ -181,8 +185,11 @@ const config = {
 * [Metadata](#metadata)
 * [Data Types](#data-types)
 * [SQL injection](#sql-injection)
-* [Known Issues](#known-issues)
+* [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)
+* [9.x to 10.x changes](#9x-to-10x-changes)
 * [8.x to 9.x changes](#8x-to-9x-changes)
 * [7.x to 8.x changes](#7x-to-8x-changes)
 * [6.x to 7.x changes](#6x-to-7x-changes)
@@ -724,7 +731,7 @@ ___
 
 ### MSNodeSQLv8
 
-Alternative driver, requires Node.js v10+ or newer; Windows (32 or 64-bit) or Linux/macOS (64-bit only). It's not part of the default package so it must be [installed](#msnodesqlv8-driver) in addition. Supports [Windows/Trusted Connection authentication](#windows-authentication-example-using-msnodesqlv8).
+Alternative driver for Windows (32 or 64-bit) or Linux/macOS (64-bit only). It's not part of the default package so it must be [installed](#msnodesqlv8-driver) in addition. Supports [Windows/Trusted Connection authentication](#windows-authentication-example-using-msnodesqlv8).
 
 **To use this driver you must use this `require` statement:**
 
@@ -816,6 +823,36 @@ __Example__
 pool.close()
 ```
 
+---------------------------------------
+
+### Pool properties
+
+These properties are available on a connected `ConnectionPool` instance (after `connect()` has resolved):
+
+- **pool.healthy** - `Boolean` - Whether the pool is able to create new connections.
+- **pool.size** - `Number` - Total number of connections in the pool (free + used + pending creation).
+- **pool.available** - `Number` - Number of free connections in the pool.
+- **pool.pending** - `Number` - Number of pending connection acquisition requests.
+- **pool.borrowed** - `Number` - Number of connections currently in use.
+- **pool.connected** - `Boolean` - Whether the pool is connected.
+- **pool.connecting** - `Boolean` - Whether the pool is currently connecting.
+
+---------------------------------------
+
+### ConnectionPool.parseConnectionString (connectionString)
+
+Parses a connection string into a configuration object. This is a static method.
+
+__Arguments__
+
+- **connectionString** - Classic or Azure AD connection string.
+
+__Example__
+
+```javascript
+const config = sql.ConnectionPool.parseConnectionString('Server=localhost,1433;Database=mydb;User Id=sa;Password=pwd')
+```
+
 ## Request
 
 ```javascript
@@ -903,6 +940,13 @@ __JS Data Type To SQL Data Type Map__
 
 Default data type for unknown object is `sql.NVarChar`.
 
+When a `Number` value is provided without an explicit type, the library inspects the value to choose the best SQL type:
+- Integers within the 32-bit signed range → `sql.Int`
+- Integers outside the 32-bit range → `sql.BigInt`
+- Non-integer numbers → `sql.Float`
+
+JavaScript `bigint` primitives follow the same range logic (`sql.Int` for values within the 32-bit signed range, `sql.BigInt` otherwise).
+
 You can define your own type map.
 
 ```javascript
@@ -946,6 +990,46 @@ __Errors__ (synchronous)
 
 ---------------------------------------
 
+### replaceInput (name, type, value)
+
+Replace an existing input parameter on the request. If the parameter was previously added with `input()`, it is removed and re-added with the new type and value. Useful when building queries dynamically or re-using a `Request` object.
+
+__Arguments__
+
+- **name** - Name of the input parameter without @ char.
+- **type** - SQL data type of input parameter.
+- **value** - Input parameter value.
+
+Unlike `input()`, `replaceInput()` requires an explicit SQL type — auto type inference is not supported.
+
+__Example__
+
+```javascript
+request.input('myval', sql.Int, 1)
+request.replaceInput('myval', sql.Int, 2)
+```
+
+---------------------------------------
+
+### replaceOutput (name, type, [value])
+
+Replace an existing output parameter on the request.
+
+__Arguments__
+
+- **name** - Name of the output parameter without @ char.
+- **type** - SQL data type of output parameter.
+- **value** - Output parameter value initial value. Optional.
+
+__Example__
+
+```javascript
+request.output('myval', sql.Int)
+request.replaceOutput('myval', sql.BigInt)
+```
+
+---------------------------------------
+
 ### toReadableStream
 
 Convert request to a Node.js ReadableStream
@@ -1044,7 +1128,7 @@ request.query('select 1 as number; select 2 as number', (err, result) => {
 
 ### batch (batch, [callback])
 
-Execute the SQL command. Unlike [query](#query-command-callback), it doesn't use `sp_executesql`, so is not likely that SQL Server will reuse the execution plan it generates for the SQL. Use this only in special cases, for example when you need to execute commands like `create procedure` which can't be executed with [query](#query-command-callback) or if you're executing statements longer than 4000 chars on SQL Server 2000. Also you should use this if you're plan to work with local temporary tables ([more information here](http://weblogs.sqlteam.com/mladenp/archive/2006/11/03/17197.aspx)).
+Execute the SQL command. Unlike [query](#query-command-callback), it doesn't use `sp_executesql`, so is not likely that SQL Server will reuse the execution plan it generates for the SQL. Use this only in special cases, for example when you need to execute commands like `create procedure` which can't be executed with [query](#query-command-callback). Also you should use this if you plan to work with local temporary tables ([more information here](http://weblogs.sqlteam.com/mladenp/archive/2006/11/03/17197.aspx)).
 
 NOTE: Table-Valued Parameter (TVP) is not supported in batch.
 
@@ -1072,8 +1156,6 @@ __Errors__
 - ENOTBEGUN (`TransactionError`) - Transaction has not begun.
 - EABORT (`TransactionError`) - Transaction was aborted (by user or because of an error).
 
-You can enable multiple recordsets in queries with the `request.multiple = true` command.
-
 ---------------------------------------
 
 ### bulk (table, [options,] [callback])
@@ -2139,12 +2221,109 @@ request.query('select @myval as myval', (err, result) => {
 })
 ```
 
-## Known issues
+## Diagnostics Channel
 
-### Tedious
+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
 
-- If you're facing problems with connecting SQL Server 2000, try setting the default TDS version to 7.1 with `config.options.tdsVersion = '7_1'` ([issue](https://github.com/tediousjs/node-mssql/issues/36))
-- If you're executing a statement longer than 4000 chars on SQL Server 2000, always use [batch](#batch-batch-callback) instead of [query](#query-command-callback) ([issue](https://github.com/tediousjs/node-mssql/issues/68))
+- Config objects are no longer cloned by the library. Mutating a config object after passing it to a `ConnectionPool` results in undefined behaviour.
+- Removed `rfdc` dependency
+- Upgraded to tedious version 19
+- Upgraded `@tediousjs/connection-string` to 0.6.x
 
 ## 10.x to 11.x changes
 
@@ -2220,10 +2399,6 @@ to create new connections or not
 [npm-url]: https://www.npmjs.com/package/mssql
 [downloads-image]: https://img.shields.io/npm/dm/mssql.svg?style=flat-square
 [downloads-url]: https://www.npmjs.com/package/mssql
-[david-image]: https://img.shields.io/david/tediousjs/node-mssql.svg?style=flat-square
-[david-url]: https://david-dm.org/tediousjs/node-mssql
-[appveyor-image]: https://ci.appveyor.com/api/projects/status/e5gq1a0ujwams9t7/branch/master?svg=true
-[appveyor-url]: https://ci.appveyor.com/project/tediousjs/node-mssql
 
 [tedious-url]: https://www.npmjs.com/package/tedious
 [msnodesqlv8-url]: https://www.npmjs.com/package/msnodesqlv8

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 => {