mssql 12.2.3 → 12.3.1

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:
 
@@ -133,9 +133,12 @@ const config = {
 ### Connections
 
 * [Pool Management](#pool-management)
+* [Connection Validation](#connection-validation)
 * [ConnectionPool](#connections-1)
 * [connect](#connect-callback)
 * [close](#close)
+* [Pool properties](#pool-properties)
+* [parseConnectionString](#connectionpoolparseconnectionstring-connectionstring)
 
 ### Requests
 
@@ -143,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)
@@ -180,8 +185,10 @@ const config = {
 * [Metadata](#metadata)
 * [Data Types](#data-types)
 * [SQL injection](#sql-injection)
-* [Known Issues](#known-issues)
 * [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)
@@ -574,6 +581,30 @@ sql.query('SELECT * FROM [example]').then((result) => {
 })
 ```
 
+### Connection Validation
+
+When a connection is acquired from the pool, it can be validated to ensure it is still usable. This is controlled by the `validateConnection` config option.
+
+```javascript
+const config = {
+    server: 'localhost',
+    // ...
+    validateConnection: true // default
+}
+```
+
+The following values are supported:
+
+| Value | Description |
+|---|---|
+| `true` (default) | Executes `SELECT 1` against the connection before handing it to the caller. This is the most thorough check — it verifies end-to-end connectivity — but adds a round-trip query for every pool acquisition. |
+| `'socket'` | Performs a lightweight, synchronous check of the underlying connection state and TCP socket health. No SQL query is executed. This is significantly cheaper at scale and catches most failure modes (closed connections, destroyed sockets, wrong protocol state), but will not detect issues like server-side session invalidation. **Tedious driver only** — with msnodesqlv8, this value falls back to `SELECT 1` behaviour because native ODBC connections do not expose socket-level properties. |
+| `false` | Disables validation entirely. The connection is assumed to be healthy if it has not been flagged as closed or errored. Use this only if your application already handles stale connection errors gracefully. |
+
+#### When to use `'socket'` mode
+
+If your application maintains a large connection pool and you see high volumes of `SELECT 1` queries in your SQL Server monitoring, switching to `'socket'` mode can dramatically reduce overhead. TCP keepalive (enabled by default in tedious at 30-second intervals) will independently detect and close dead connections over time, so the socket-level check provides a good balance between reliability and performance.
+
 ## Configuration
 
 The following is an example configuration object:
@@ -608,6 +639,7 @@ const config = {
 - **pool.min** - The minimum of connections there can be in the pool (default: `0`).
 - **pool.idleTimeoutMillis** - The Number of milliseconds before closing an unused connection (default: `30000`).
 - **arrayRowMode** - Return row results as a an array instead of a keyed object. Also adds `columns` array. (default: `false`) See [Handling Duplicate Column Names](#handling-duplicate-column-names)
+- **validateConnection** - Controls how connections are validated when acquired from the pool. See [Connection Validation](#connection-validation) for details. (default: `true`)
 
 Complete list of pool options can be found [here](https://github.com/vincit/tarn.js/#usage).
 
@@ -698,7 +730,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:**
 
@@ -790,6 +822,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
@@ -877,6 +939,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
@@ -920,6 +989,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
@@ -1018,7 +1127,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.
 
@@ -1046,8 +1155,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])
@@ -2113,12 +2220,12 @@ request.query('select @myval as myval', (err, result) => {
 })
 ```
 
-## Known issues
-
-### Tedious
+## 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
 
@@ -2194,10 +2301,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/tedious/connection-pool.js

@@ -117,15 +117,36 @@ class ConnectionPool extends BaseConnectionPool {
   }
 
   _poolValidate (tedious) {
-    if (tedious && !tedious.closed && !tedious.hasError) {
-      return !this.config.validateConnection || new shared.Promise((resolve) => {
-        const req = new tds.Request('SELECT 1;', (err) => {
-          resolve(!err)
-        })
-        tedious.execSql(req)
-      })
+    if (!tedious || tedious.closed || tedious.hasError) {
+      return false
+    }
+
+    const mode = this.config.validateConnection
+
+    if (!mode) {
+      return true
+    }
+
+    // Socket-level validation: check connection state and socket health
+    // without executing a SQL query. Much cheaper than SELECT 1 at scale.
+    if (mode === 'socket') {
+      if (tedious.state !== tedious.STATE.LOGGED_IN) {
+        return false
+      }
+      if (!tedious.socket || tedious.socket.destroyed || !tedious.socket.writable) {
+        return false
+      }
+      return true
     }
-    return false
+
+    // SQL-level validation (default): execute SELECT 1 to verify the
+    // connection is fully functional end-to-end.
+    return new shared.Promise((resolve) => {
+      const req = new tds.Request('SELECT 1;', (err) => {
+        resolve(!err)
+      })
+      tedious.execSql(req)
+    })
   }
 
   _poolDestroy (tedious) {

package/lib/tedious/request.js

@@ -200,9 +200,13 @@ const parameterCorrection = function (value) {
     }
 
     for (const col of value.columns) {
+      const tediousType = getTediousType(col.type)
+      if (tediousType === tds.TYPES.Variant) {
+        throw new RequestError(`Column '${col.name}' in TVP '${value.schema ? value.schema + '.' : ''}${value.name}' uses sql_variant which is not supported by the tedious driver for TVP column types. Consider using a more specific data type.`, 'EARGS')
+      }
       tvp.columns.push({
         name: col.name,
-        type: getTediousType(col.type),
+        type: tediousType,
         length: col.length,
         scale: col.scale,
         precision: col.precision
@@ -664,9 +668,18 @@ class Request extends BaseRequest {
               } catch (e) {
                 e.message = `Validation failed for parameter '${name}'. ${e.message}`
                 const err = new RequestError(e, 'EPARAM')
+                delete this._cancel
+
+                if (!hasReturned) {
+                  for (const event in errorHandlers) {
+                    connection.removeListener(event, errorHandlers[event])
+                  }
 
-                this.parent.release(connection)
-                return callback(err)
+                  this.parent.release(connection)
+                  hasReturned = true
+                  return callback(err)
+                }
+                return
               }
             }
 
@@ -703,21 +716,23 @@ class Request extends BaseRequest {
 
             req.sqlTextOrProcedure = `declare ${declarations.join(', ')};select ${assigns.join(', ')};${req.sqlTextOrProcedure};${batchHasOutput ? (`select 1 as [___return___], ${selects.join(', ')}`) : ''}`
           }
-        } else {
-          for (const name in this.parameters) {
-            if (!objectHasProperty(this.parameters, name)) {
-              continue
-            }
-            const param = this.parameters[name]
-            if (param.io === 1) {
-              req.addParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
-            } else {
-              req.addOutputParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
-            }
-          }
         }
 
         try {
+          if (!this._isBatch) {
+            for (const name in this.parameters) {
+              if (!objectHasProperty(this.parameters, name)) {
+                continue
+              }
+              const param = this.parameters[name]
+              if (param.io === 1) {
+                req.addParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
+              } else {
+                req.addOutputParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
+              }
+            }
+          }
+
           connection[this._isBatch ? 'execSqlBatch' : 'execSql'](req)
         } catch (error) {
           handleError(true, connection, error)
@@ -983,19 +998,34 @@ class Request extends BaseRequest {
           output[parameterName] = value
         })
 
-        for (const name in this.parameters) {
-          if (!objectHasProperty(this.parameters, name)) {
-            continue
+        try {
+          for (const name in this.parameters) {
+            if (!objectHasProperty(this.parameters, name)) {
+              continue
+            }
+            const param = this.parameters[name]
+            if (param.io === 1) {
+              req.addParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
+            } else {
+              req.addOutputParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
+            }
           }
-          const param = this.parameters[name]
-          if (param.io === 1) {
-            req.addParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
-          } else {
-            req.addOutputParameter(param.name, getTediousType(param.type), parameterCorrection(param.value), { length: param.length, scale: param.scale, precision: param.precision })
+
+          connection.callProcedure(req)
+        } catch (error) {
+          const err = error instanceof RequestError ? error : new RequestError(error, 'EREQUEST')
+          delete this._cancel
+
+          if (!hasReturned) {
+            for (const event in errorHandlers) {
+              connection.removeListener(event, errorHandlers[event])
+            }
+
+            this.parent.release(connection)
+            hasReturned = true
+            callback(err)
           }
         }
-
-        connection.callProcedure(req)
       })
     })
   }

package/package.json

@@ -21,7 +21,7 @@
     "azure",
     "node-mssql"
   ],
-  "version": "12.2.3",
+  "version": "12.3.1",
   "main": "index.js",
   "type": "commonjs",
   "repository": {