feat: add socket-level pool validation mode

Add a lightweight 'socket' validation mode for validateConnection config.
Instead of running SELECT 1 for every connection checkout (expensive at
scale), users can set validateConnection: 'socket' to check the tedious
connection state and socket health using synchronous property lookups.

Supported values for validateConnection:
- true (default): SQL validation via SELECT 1
- 'socket': lightweight state + socket check
- false: skip validation entirely

This addresses the concern raised in #1834 about SELECT 1 generating
millions of unnecessary queries in high-throughput environments.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dhensby

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).
 

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

test/common/unit.js

@@ -1,6 +1,6 @@
 'use strict'
 
-/* globals describe, it, afterEach */
+/* globals describe, it, before, afterEach */
 
 const sql = require('../../')
 const assert = require('node:assert')
@@ -862,4 +862,107 @@ describe('connection string auth - tedious', () => {
       assert.strictEqual(result, 'UDT_StringArray readonly')
     })
   })
+
+  describe('_poolValidate', () => {
+    // Reset Promise in case earlier tests replaced it (e.g. FakePromise)
+    before(() => { sql.Promise = Promise })
+
+    function createMockConnection (overrides = {}) {
+      return {
+        closed: false,
+        hasError: false,
+        STATE: { LOGGED_IN: 'LoggedIn' },
+        state: { name: 'LoggedIn' },
+        socket: { destroyed: false, writable: true },
+        ...overrides
+      }
+    }
+
+    function createPool (validateConnection) {
+      return new ConnectionPool({ validateConnection })
+    }
+
+    it('returns false for null connection', () => {
+      const pool = createPool(true)
+      assert.strictEqual(pool._poolValidate(null), false)
+    })
+
+    it('returns false for closed connection', () => {
+      const pool = createPool(true)
+      assert.strictEqual(pool._poolValidate(createMockConnection({ closed: true })), false)
+    })
+
+    it('returns false for errored connection', () => {
+      const pool = createPool(true)
+      assert.strictEqual(pool._poolValidate(createMockConnection({ hasError: true })), false)
+    })
+
+    it('returns true without validation when validateConnection is false', () => {
+      const pool = createPool(false)
+      assert.strictEqual(pool._poolValidate(createMockConnection()), true)
+    })
+
+    it('socket mode: returns true for healthy connection', () => {
+      const pool = createPool('socket')
+      const conn = createMockConnection()
+      conn.STATE.LOGGED_IN = conn.state
+      assert.strictEqual(pool._poolValidate(conn), true)
+    })
+
+    it('socket mode: returns false when state is not LOGGED_IN', () => {
+      const pool = createPool('socket')
+      const conn = createMockConnection()
+      conn.state = { name: 'SentLogin7WithStandardLogin' }
+      assert.strictEqual(pool._poolValidate(conn), false)
+    })
+
+    it('socket mode: returns false when socket is destroyed', () => {
+      const pool = createPool('socket')
+      const conn = createMockConnection()
+      conn.STATE.LOGGED_IN = conn.state
+      conn.socket = { destroyed: true, writable: false }
+      assert.strictEqual(pool._poolValidate(conn), false)
+    })
+
+    it('socket mode: returns false when socket is not writable', () => {
+      const pool = createPool('socket')
+      const conn = createMockConnection()
+      conn.STATE.LOGGED_IN = conn.state
+      conn.socket = { destroyed: false, writable: false }
+      assert.strictEqual(pool._poolValidate(conn), false)
+    })
+
+    it('socket mode: returns false when socket is null', () => {
+      const pool = createPool('socket')
+      const conn = createMockConnection()
+      conn.STATE.LOGGED_IN = conn.state
+      conn.socket = null
+      assert.strictEqual(pool._poolValidate(conn), false)
+    })
+
+    it('query mode: returns a promise (SELECT 1)', () => {
+      const pool = createPool(true)
+      const conn = createMockConnection()
+      conn.execSql = (req) => {
+        req.callback(null)
+      }
+      const result = pool._poolValidate(conn)
+      assert.ok(result instanceof Promise || (result && typeof result.then === 'function'))
+      return Promise.resolve(result).then(valid => {
+        assert.strictEqual(valid, true)
+      })
+    })
+
+    it('query mode: resolves false on error', () => {
+      const pool = createPool(true)
+      const conn = createMockConnection()
+      conn.execSql = (req) => {
+        req.callback(new Error('connection lost'))
+      }
+      const result = pool._poolValidate(conn)
+      return Promise.resolve(result).then(valid => {
+        assert.strictEqual(valid, false)
+      })
+    })
+  })
 })