mssql 12.2.2 → 12.3.0

package/README.md

@@ -133,6 +133,7 @@ const config = {
 ### Connections
 
 * [Pool Management](#pool-management)
+* [Connection Validation](#connection-validation)
 * [ConnectionPool](#connections-1)
 * [connect](#connect-callback)
 * [close](#close)
@@ -574,6 +575,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 +633,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).
 

package/lib/base/connection-pool.js

@@ -2,7 +2,7 @@
 
 const { EventEmitter } = require('node:events')
 const debug = require('debug')('mssql:base')
-const { parseSqlConnectionString } = require('@tediousjs/connection-string')
+const { parse, MSSQL_SCHEMA } = require('@tediousjs/connection-string')
 const tarn = require('tarn')
 const { IDS } = require('../utils')
 const ConnectionError = require('../error/connection-error')
@@ -99,6 +99,7 @@ class ConnectionPool extends EventEmitter {
   }
 
   static _parseAuthenticationType (type, entries) {
+    if (!type) return 'default'
     switch (type.toLowerCase()) {
       case 'active directory integrated':
         if (entries.includes('token')) {
@@ -121,7 +122,15 @@ class ConnectionPool extends EventEmitter {
   }
 
   static _parseConnectionString (connectionString) {
-    const parsed = parseSqlConnectionString(connectionString, true, true)
+    const result = parse(connectionString)
+    const parsed = result.toSchema(MSSQL_SCHEMA)
+    // Include non-standard keys (client id, tenant id, token, msi endpoint, msi secret)
+    // that are used for authentication but not part of the MSSQL schema
+    for (const [key, value] of result) {
+      if (!(key in parsed)) {
+        parsed[key] = value
+      }
+    }
     return Object.entries(parsed).reduce((config, [key, value]) => {
       switch (key) {
         case 'application name':

package/lib/error/connection-error.js

@@ -18,12 +18,6 @@ class ConnectionError extends MSSQLError {
     super(message, code)
 
     this.name = 'ConnectionError'
-
-    let err = message?.details
-    if (err instanceof Array && (err = err.at(-1))) {
-      this.message = err.message
-      this.originalError = err
-    }
   }
 }
 

package/lib/msnodesqlv8/connection-pool.js

@@ -7,7 +7,7 @@ const { IDS, INCREMENT } = require('../utils')
 const shared = require('../shared')
 const ConnectionError = require('../error/connection-error')
 const { platform } = require('node:os')
-const { buildConnectionString } = require('@tediousjs/connection-string')
+const { build } = require('@tediousjs/connection-string')
 
 const DEFAULT_CONNECTION_DRIVER = ['darwin', 'linux'].includes(platform()) ? 'ODBC Driver 17 for SQL Server' : 'SQL Server Native Client 11.0'
 
@@ -22,7 +22,7 @@ class ConnectionPool extends BaseConnectionPool {
       }
 
       if (!this.config.connectionString) {
-        cfg.conn_str = buildConnectionString({
+        cfg.conn_str = build({
           Driver: this.config.driver && this.config.driver !== 'msnodesqlv8' ? this.config.driver : DEFAULT_CONNECTION_DRIVER,
           Server: this.config.options.instanceName ? `${this.config.server}\\${this.config.options.instanceName}` : `${this.config.server},${this.config.port}`,
           Database: this.config.database,
@@ -43,10 +43,18 @@ class ConnectionPool extends BaseConnectionPool {
 
       msnodesql.open(cfg, (err, tds) => {
         if (err) {
+          let customErr = err?.details
+          if (customErr instanceof Array && (customErr = customErr.at(-1))) {
+            err.message = customErr.message
+            err.code = customErr.code
+          }
+
           err = new ConnectionError(err.message, err.code)
           return reject(err)
         }
 
+        tds.setUseNumericString(true)
+
         IDS.add(tds, 'Connection', connedtionId)
         tds.setUseUTC(this.config.options.useUTC)
         debug('connection(%d): established', IDS.get(tds))

package/lib/msnodesqlv8/request.js

@@ -31,6 +31,7 @@ const castParameter = function (value, type) {
     case TYPES.NChar:
     case TYPES.Xml:
     case TYPES.Text:
+    case TYPES.BigInt:
     case TYPES.NText:
       if ((typeof value !== 'string') && !(value instanceof String)) {
         value = value.toString()
@@ -39,7 +40,6 @@ const castParameter = function (value, type) {
 
     case TYPES.Int:
     case TYPES.TinyInt:
-    case TYPES.BigInt:
     case TYPES.SmallInt:
       if ((typeof value !== 'number') && !(value instanceof Number)) {
         value = parseInt(value)
@@ -122,6 +122,8 @@ const createColumns = function (metadata, arrayRowMode) {
   return out
 }
 
+const numericStringSqlTypes = new Set(['int', 'smallint', 'tinyint', 'float', 'real', 'numeric', 'decimal', 'money', 'smallmoney'])
+
 const valueCorrection = function (value, metadata) {
   const type = metadata && objectHasProperty(metadata, 'sqlType') && objectHasProperty(DECLARATIONS, metadata.sqlType)
     ? DECLARATIONS[metadata.sqlType]
@@ -137,6 +139,10 @@ const valueCorrection = function (value, metadata) {
     } else {
       return value
     }
+  } else if (typeof value === 'string' && numericStringSqlTypes.has(metadata.sqlType)) {
+    return Number(value)
+  } else if (typeof value === 'string' && metadata.sqlType === 'sql_variant' && value !== '' && !isNaN(Number(value))) {
+    return Number(value)
   } else {
     return value
   }
@@ -177,6 +183,10 @@ class Request extends BaseRequest {
             return callback(new RequestError('Canceled.', 'ECANCEL'))
           }
 
+          // Disable useNumericString during bulk operations to avoid
+          // msnodesqlv8 SQL generation bugs with its table manager
+          connection.setUseNumericString(false)
+
           const done = (err, rowCount) => {
             if (hasReturned) {
               return
@@ -184,6 +194,8 @@ class Request extends BaseRequest {
 
             hasReturned = true
 
+            connection.setUseNumericString(true)
+
             if (err) {
               if ((typeof err.sqlstate === 'string') && (err.sqlstate.toLowerCase() === '08s01')) {
                 connection.hasError = true

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/package.json

@@ -21,7 +21,7 @@
     "azure",
     "node-mssql"
   ],
-  "version": "12.2.2",
+  "version": "12.3.0",
   "main": "index.js",
   "type": "commonjs",
   "repository": {
@@ -34,7 +34,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@tediousjs/connection-string": "^0.6.0",
+    "@tediousjs/connection-string": "^1.0.0",
     "commander": "^11.0.0",
     "debug": "^4.3.3",
     "tarn": "^3.0.2",