mssql 12.7.15 → 12.7.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -801,6 +801,8 @@ const pool = new sql.ConnectionPool({ /* config */ })
801
801
 
802
802
  Create a new connection pool. The initial probe connection is created to find out whether the configuration is valid.
803
803
 
804
+ While a `close()` is in progress, `connect()` rejects with `ECLOSING`. Wait for `close()` to finish before you connect the pool again, or create a new `ConnectionPool`.
805
+
804
806
  __Arguments__
805
807
 
806
808
  - **callback(err)** - A callback which is called after initial probe connection has established, or an error has occurred. Optional. If omitted, returns [Promise](#promises).
@@ -827,6 +829,7 @@ __Errors__
827
829
  - EALREADYCONNECTING (`ConnectionError`) - Already connecting to database!
828
830
  - EINSTLOOKUP (`ConnectionError`) - Instance lookup failed.
829
831
  - ESOCKET (`ConnectionError`) - Socket error.
832
+ - ECLOSING (`ConnectionError`) - Cannot connect a pool while it is closing.
830
833
 
831
834
  ---------------------------------------
832
835
 
@@ -834,12 +837,21 @@ __Errors__
834
837
 
835
838
  Close all active connections in the pool.
836
839
 
840
+ `close()` waits for running requests, open transactions and prepared statements to release their connections back to the pool. This wait has no timeout.
841
+
842
+ After you call `close()`, `pool.connected` is `false`. New work then fails with `ECONNCLOSED` (`ConnectionError`): new requests (on the pool or on an open transaction), `begin()`, `prepare()` and a prepared statement's `execute()`.
843
+
844
+ A prepared statement or a transaction can still release its connection while the pool closes: `unprepare()`, `commit()` and `rollback()` work as usual. `close()` does not complete until every prepared statement is unprepared and every transaction has ended.
845
+
837
846
  __Example__
838
847
 
839
848
  ```javascript
840
849
  pool.close()
841
850
  ```
842
851
 
852
+ __Errors__
853
+ - ECONNECTING (`ConnectionError`) - Cannot close a pool while it is connecting.
854
+
843
855
  ---------------------------------------
844
856
 
845
857
  ### Pool properties
@@ -1485,6 +1497,8 @@ You can execute multiple queries against the same prepared statement but you *mu
1485
1497
 
1486
1498
  **TIP**: You can also create prepared statements in transactions (`new sql.PreparedStatement(transaction)`), but keep in mind you can't execute other requests in the transaction until you call `unprepare`.
1487
1499
 
1500
+ If the server rolls back a transaction that has a prepared statement (for example, when `abortTransactionOnError` is on and a statement fails), the transaction gives its connection back to the pool, and the pool can lend it to another caller, or to the same transaction when it begins again. From then on, `execute` rejects with `EABORT` and doesn't use the connection. Still call `unprepare`: it releases the statement without sending anything to the server. The server keeps the statement's handle on that connection until the connection closes. The msnodesqlv8 driver can't tell when the server rolls a transaction back (see [Aborted transactions](#transaction)), so with msnodesqlv8 the statement keeps its connection.
1501
+
1488
1502
  ---------------------------------------
1489
1503
 
1490
1504
  ### input (name, type)
@@ -1626,18 +1640,25 @@ ps.prepare('select @param as value', err => {
1626
1640
  **TIP**: To learn more about how number of affected rows works, see section [Affected Rows](#affected-rows).
1627
1641
 
1628
1642
  __Errors__
1643
+ - ENOCONN (`PreparedStatementError`) - No connection is specified for that prepared statement.
1644
+ - ECONNCLOSED (`ConnectionError`) - Connection is closed.
1629
1645
  - ENOTPREPARED (`PreparedStatementError`) - Statement is not prepared.
1630
1646
  - ETIMEOUT (`RequestError`) - Request timeout.
1631
1647
  - EREQUEST (`RequestError`) - *Message from SQL Server*
1632
1648
  - EPARAM (`RequestError`) - A parameter value is not valid for its type.
1633
1649
  - ECANCEL (`RequestError`) - Cancelled.
1634
1650
  - EREQINPROG (`TransactionError`) - Can't acquire connection for the request. There is another request in progress.
1651
+ - EABORT (`TransactionError`) - The transaction that the statement was prepared in has been aborted.
1635
1652
 
1636
1653
  ---------------------------------------
1637
1654
 
1638
1655
  ### unprepare ([callback])
1639
1656
 
1640
- Unprepare a prepared statement.
1657
+ Unprepare a prepared statement. If the server has rolled back the transaction that the statement was prepared in, `unprepare` releases the statement without sending anything to the server.
1658
+
1659
+ If the request to unprepare the statement fails (for example, because the connection has died), the statement still gives its connection back and is no longer prepared, and the error is passed on. The pool then closes that connection instead of lending it out again. In a transaction, the connection stays with the transaction until you commit or roll it back, or until the transaction is aborted because the server has rolled it back.
1660
+
1661
+ If `unprepare` rejects with `EREQINPROG` because another request on the statement is in progress, nothing changes: the statement stays prepared and keeps its connection, so call `unprepare` again when that request has finished.
1641
1662
 
1642
1663
  __Arguments__
1643
1664
 
@@ -2227,6 +2248,8 @@ Name | Code | Message
2227
2248
  `ConnectionError` | EINSTLOOKUP | Instance lookup failed.
2228
2249
  `ConnectionError` | ESOCKET | Socket error.
2229
2250
  `ConnectionError` | ECONNCLOSED | Connection is closed.
2251
+ `ConnectionError` | ECLOSING | Cannot connect a pool while it is closing.
2252
+ `ConnectionError` | ECONNECTING | Cannot close a pool while it is connecting.
2230
2253
  `TransactionError` | ENOTBEGUN | Transaction has not begun.
2231
2254
  `TransactionError` | EALREADYBEGUN | Transaction has already begun.
2232
2255
  `TransactionError` | EREQINPROG | Can't commit/rollback transaction, unprepare the statement or acquire connection for the request. There is a request in progress.
@@ -10,14 +10,16 @@ const shared = require('../shared')
10
10
  const { MSSQLError } = require('../error')
11
11
  const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
12
12
 
13
- const NODE_MSSQL_SCHEMA = {
13
+ // toSchema() gives the schema default for an empty boolean or number value.
14
+ // This schema drops the defaults, so an empty value gives undefined, and the
15
+ // parser handles it the same as a left-out key.
16
+ const NODE_MSSQL_SCHEMA = Object.fromEntries(Object.entries({
14
17
  ...MSSQL_SCHEMA,
15
- encrypt: { type: 'boolean' },
16
18
  useutc: { type: 'boolean' },
17
19
  stream: { type: 'boolean' },
18
20
  parsejson: { type: 'boolean' },
19
21
  'request timeout': { type: 'number' }
20
- }
22
+ }).map(([key, { default: _default, ...item }]) => [key, item]))
21
23
 
22
24
  /**
23
25
  * Class ConnectionPool.
@@ -142,6 +144,10 @@ class ConnectionPool extends EventEmitter {
142
144
  }
143
145
  }
144
146
  return Object.entries(parsed).reduce((config, [key, value]) => {
147
+ // an empty boolean or number value is not set
148
+ if (value === undefined) {
149
+ return config
150
+ }
145
151
  switch (key) {
146
152
  case 'application name':
147
153
  break
@@ -234,11 +240,9 @@ class ConnectionPool extends EventEmitter {
234
240
  break
235
241
  }
236
242
  case 'encrypt':
237
- if (typeof value === 'boolean') {
238
- Object.assign(config.options, {
239
- encrypt: value
240
- })
241
- }
243
+ Object.assign(config.options, {
244
+ encrypt: !!value
245
+ })
242
246
  break
243
247
  case 'enlist':
244
248
  break
@@ -505,6 +509,13 @@ class ConnectionPool extends EventEmitter {
505
509
  return setImmediate(callback, null, this)
506
510
  }
507
511
 
512
+ // we don't allow a pool that is still closing to connect: the close waits for borrowed connections to be
513
+ // released, and they would be released into the new pool instead, so the close would never finish
514
+ if (this.pool && this.pool.destroyed) {
515
+ debug('pool(%d): connect called while closing', IDS.get(this))
516
+ return setImmediate(callback, new ConnectionError('Cannot connect a pool while it is closing', 'ECLOSING'))
517
+ }
518
+
508
519
  this._connectStack.push(callback)
509
520
 
510
521
  if (this._connecting) {
@@ -607,7 +618,7 @@ class ConnectionPool extends EventEmitter {
607
618
  // edge cases to deal with
608
619
  if (this._connecting) {
609
620
  debug('pool(%d): close called while connecting', IDS.get(this))
610
- return setImmediate(callback, new ConnectionError('Cannot close a pool while it is connecting'))
621
+ return setImmediate(callback, new ConnectionError('Cannot close a pool while it is connecting', 'ECONNECTING'))
611
622
  }
612
623
 
613
624
  if (!this.pool) {
@@ -621,13 +632,15 @@ class ConnectionPool extends EventEmitter {
621
632
 
622
633
  this._connecting = this._connected = this._healthy = false
623
634
 
624
- this.pool.destroy().then(() => {
635
+ // clear only the pool this close destroyed, not one that has replaced it since
636
+ const pool = this.pool
637
+ pool.destroy().then(() => {
625
638
  debug('pool(%d): pool closed, removing pool reference and executing close callbacks', IDS.get(this))
626
639
  publish(CHANNELS.POOL_CLOSE, () => ({
627
640
  poolId: IDS.get(this),
628
641
  reason: 'closed'
629
642
  }))
630
- this.pool = null
643
+ if (this.pool === pool) this.pool = null
631
644
  this._closeStack.forEach(cb => {
632
645
  setImmediate(cb, null)
633
646
  })
@@ -637,7 +650,7 @@ class ConnectionPool extends EventEmitter {
637
650
  reason: 'error',
638
651
  error: err
639
652
  }))
640
- this.pool = null
653
+ if (this.pool === pool) this.pool = null
641
654
  this._closeStack.forEach(cb => {
642
655
  setImmediate(cb, err)
643
656
  })
@@ -6,6 +6,7 @@ const { IDS, objectHasProperty, getPoolId, isValidParameterName } = require('../
6
6
  const globalConnection = require('../global-connection')
7
7
  const { ConnectionError, TransactionError, PreparedStatementError } = require('../error')
8
8
  const shared = require('../shared')
9
+ const Transaction = require('./transaction')
9
10
  const { TYPES, declare } = require('../datatypes')
10
11
  const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
11
12
 
@@ -42,11 +43,26 @@ class PreparedStatement extends EventEmitter {
42
43
  }
43
44
 
44
45
  get config () {
45
- return this.parent.config
46
+ return this.parent ? this.parent.config : {}
46
47
  }
47
48
 
48
49
  get connected () {
49
- return this.parent.connected
50
+ return this.parent ? this.parent.connected : false
51
+ }
52
+
53
+ /**
54
+ * Whether the statement was prepared in a transaction that no longer lends its connection
55
+ * to the statement. This happens when the server rolls the transaction back (XACT_ABORT):
56
+ * the transaction then gives its connection back to the pool, and the pool can lend it to
57
+ * another caller, or to the same transaction when it begins again. While the statement is
58
+ * prepared, the transaction lends its connection to the statement and to nothing else.
59
+ *
60
+ * @private
61
+ * @return {boolean}
62
+ */
63
+
64
+ _transactionLostConnection () {
65
+ return this.parent instanceof Transaction && (this.parent._acquiredConnection !== this._acquiredConnection || this.parent._activeRequest !== this)
50
66
  }
51
67
 
52
68
  /**
@@ -63,6 +79,12 @@ class PreparedStatement extends EventEmitter {
63
79
  return this
64
80
  }
65
81
 
82
+ // the connection may now belong to another caller, so nothing more is run on it
83
+ if (this._transactionLostConnection()) {
84
+ setImmediate(callback, this.parent._createAbortError())
85
+ return this
86
+ }
87
+
66
88
  if (this._activeRequest) {
67
89
  setImmediate(callback, new TransactionError("Can't acquire connection for the request. There is another request in progress.", 'EREQINPROG'))
68
90
  return this
@@ -372,6 +394,13 @@ class PreparedStatement extends EventEmitter {
372
394
  }
373
395
  }
374
396
 
397
+ if (!this.parent) {
398
+ // with no pool, the request's own guard would report the statement as closed (ECONNCLOSED);
399
+ // fail it as prepare() does, but through the request, so that the error reaches the caller
400
+ // in every mode (promise, callback, stream) the way any other execute() error does
401
+ req._execute = (procedure, callback) => setImmediate(callback, new PreparedStatementError('No connection is specified for that prepared statement.', 'ENOCONN'))
402
+ }
403
+
375
404
  req.execute('sp_execute', typeof callback === 'function'
376
405
  ? callback
377
406
  : () => {}
@@ -429,19 +458,50 @@ class PreparedStatement extends EventEmitter {
429
458
  return setImmediate(callback, new TransactionError("Can't unprepare the statement. There is a request in progress.", 'EREQINPROG'))
430
459
  }
431
460
 
461
+ // the transaction has already given the connection back to the pool, and another caller
462
+ // may now use it, so sp_unprepare is not sent. The handle stays allocated on that session
463
+ // until the connection closes, and the server gives its number to no other statement
464
+ // until then
465
+ if (this._transactionLostConnection()) {
466
+ this._acquiredConnection = null
467
+ this._acquiredConfig = null
468
+ this._handle = 0
469
+ this.prepared = false
470
+
471
+ debug('ps(%d): unprepared without the connection, as the transaction has lost it', IDS.get(this))
472
+
473
+ return setImmediate(callback, null)
474
+ }
475
+
432
476
  const req = new shared.driver.Request(this, this.overrides)
433
477
  req._internal = true
434
478
  req.stream = false
435
479
  req.input('handle', TYPES.Int, this._handle)
480
+ req._allowDuringClose = true
436
481
  req.execute('sp_unprepare', err => {
437
- if (err) return callback(err)
482
+ const connection = this._acquiredConnection
483
+
484
+ // this request never reached the connection: another request on the statement held it, or
485
+ // another call has already given it back. Nothing is changed
486
+ if (err && (err.code === 'EREQINPROG' || !connection)) return callback(err)
438
487
 
439
- this.parent.release(this._acquiredConnection)
488
+ if (err) {
489
+ debug('ps(%d): failed to unprepare', IDS.get(this), err)
490
+
491
+ // the connection may have died, or the statement may still be prepared on it, so the
492
+ // pool is left to close it rather than lend it out again. It is given back all the
493
+ // same, as nothing else can give it back, and closing the pool waits until it is
494
+ connection.hasError = true
495
+ }
496
+
497
+ this.parent.release(connection)
440
498
  this._acquiredConnection = null
441
499
  this._acquiredConfig = null
442
500
  this._handle = 0
443
501
  this.prepared = false
444
502
 
503
+ if (err) return callback(err)
504
+
445
505
  debug('ps(%d): unprepared', IDS.get(this))
446
506
 
447
507
  return callback(null)
@@ -51,6 +51,8 @@ class Request extends EventEmitter {
51
51
  this.canceled = false
52
52
  this._paused = false
53
53
  this._internal = false
54
+ // Cleanup must still return borrowed connections while pool.close() waits for them.
55
+ this._allowDuringClose = false
54
56
  this.parent = parent || globalConnection.pool
55
57
  this.parameters = {}
56
58
  this.stream = null
@@ -597,7 +599,7 @@ class Request extends EventEmitter {
597
599
  return setImmediate(callback, new RequestError('No connection is specified for that request.', 'ENOCONN'))
598
600
  }
599
601
 
600
- if (!this.parent.connected) {
602
+ if (!this.parent.connected && !this._allowDuringClose) {
601
603
  return setImmediate(callback, new ConnectionError('Connection is closed.', 'ECONNCLOSED'))
602
604
  }
603
605
 
@@ -695,7 +697,7 @@ class Request extends EventEmitter {
695
697
  return setImmediate(callback, new RequestError('No connection is specified for that request.', 'ENOCONN'))
696
698
  }
697
699
 
698
- if (!this.parent.connected) {
700
+ if (!this.parent.connected && !this._allowDuringClose) {
699
701
  return setImmediate(callback, new ConnectionError('Connection is closed.', 'ECONNCLOSED'))
700
702
  }
701
703
 
@@ -48,7 +48,7 @@ class Transaction extends EventEmitter {
48
48
  }
49
49
 
50
50
  get config () {
51
- return this.parent.config
51
+ return this.parent ? this.parent.config : {}
52
52
  }
53
53
 
54
54
  get connected () {
@@ -26,6 +26,11 @@ function connect (config, callback) {
26
26
  const ogClose = globalConnection.close
27
27
 
28
28
  const globalClose = function (callback) {
29
+ // a pool refuses to close while it is connecting, so it stays the global pool with its handlers
30
+ if (this.connecting) {
31
+ return ogClose.call(this, callback)
32
+ }
33
+
29
34
  // remove event handlers from the global connection
30
35
  for (const event in globalConnectionHandlers) {
31
36
  for (let i = 0, l = globalConnectionHandlers[event].length; i < l; i++) {
@@ -42,22 +47,27 @@ function connect (config, callback) {
42
47
  }
43
48
  })
44
49
 
45
- globalConnection = null
50
+ // this close stays on the pool after another pool has become global, so leave that one alone
51
+ if (globalConnection === this) globalConnection = null
46
52
  return ogClose.call(this, callback)
47
53
  }
48
54
 
49
55
  globalConnection.close = globalClose.bind(globalConnection)
50
56
  }
57
+ // a failed connect is reported in a later setImmediate. By then sql.close() may have cleared the pool and
58
+ // sql.connect() made another one global, or sql.connect() may be connecting this pool again.
59
+ const pool = globalConnection
60
+ const forgetFailedPool = () => {
61
+ if (globalConnection === pool && !pool.connecting && !pool.connected) globalConnection = null
62
+ }
51
63
  if (typeof callback === 'function') {
52
- return globalConnection.connect((err, connection) => {
53
- if (err) {
54
- globalConnection = null
55
- }
64
+ return pool.connect((err, connection) => {
65
+ if (err) forgetFailedPool()
56
66
  callback(err, connection)
57
67
  })
58
68
  }
59
- return globalConnection.connect().catch((err) => {
60
- globalConnection = null
69
+ return pool.connect().catch((err) => {
70
+ forgetFailedPool()
61
71
  return shared.Promise.reject(err)
62
72
  })
63
73
  }
@@ -72,7 +82,8 @@ function connect (config, callback) {
72
82
  function close (callback) {
73
83
  if (globalConnection) {
74
84
  const gc = globalConnection
75
- globalConnection = null
85
+ // a pool refuses to close while it is connecting, so it stays the global pool
86
+ if (!gc.connecting) globalConnection = null
76
87
  return gc.close(callback)
77
88
  }
78
89
 
@@ -115,7 +126,8 @@ function removeListener (event, handler) {
115
126
  const index = globalConnectionHandlers[event].indexOf(handler)
116
127
  if (index === -1) return globalConnection
117
128
  globalConnectionHandlers[event].splice(index, 1)
118
- if (globalConnectionHandlers[event].length === 0) globalConnectionHandlers[event] = undefined
129
+ // sql.connect() and sql.close() go through every event in here, so an event with no handlers left must go
130
+ if (globalConnectionHandlers[event].length === 0) delete globalConnectionHandlers[event]
119
131
 
120
132
  if (globalConnection) globalConnection.removeListener(event, handler)
121
133
  return globalConnection
@@ -76,6 +76,7 @@ class Transaction extends BaseTransaction {
76
76
 
77
77
  const req = new Request(this)
78
78
  req.stream = false
79
+ req._allowDuringClose = true
79
80
  req.query('commit tran', err => {
80
81
  if (err) err = new TransactionError(err)
81
82
 
@@ -98,6 +99,7 @@ class Transaction extends BaseTransaction {
98
99
 
99
100
  const req = new Request(this)
100
101
  req.stream = false
102
+ req._allowDuringClose = true
101
103
  req.query('rollback tran', err => {
102
104
  if (err) err = new TransactionError(err)
103
105
 
@@ -3,6 +3,7 @@
3
3
  const tds = require('tedious')
4
4
  const debug = require('debug')('mssql:tedi')
5
5
  const BaseRequest = require('../base/request')
6
+ const BaseTransaction = require('../base/transaction')
6
7
  const RequestError = require('../error/request-error')
7
8
  const { IDS, objectHasProperty, assertSafeColumnName, assertSafeTypeName, assertSafeTypeSize, assertSafeProcedureName } = require('../utils')
8
9
  const { TYPES, DECLARATIONS, declare, cast } = require('../datatypes')
@@ -217,6 +218,23 @@ const parameterCorrection = function (value) {
217
218
  }
218
219
 
219
220
  class Request extends BaseRequest {
221
+ /*
222
+ Record the error that made the server roll back the transaction that the request ran in.
223
+ The request of a prepared statement has the statement as its parent, so the transaction
224
+ is the parent of the statement.
225
+ */
226
+
227
+ _recordAbortReason (reason) {
228
+ let transaction = this.parent
229
+ while (transaction && !(transaction instanceof BaseTransaction)) {
230
+ transaction = transaction.parent
231
+ }
232
+
233
+ if (reason && transaction && transaction._aborted) {
234
+ transaction._abortReason = reason
235
+ }
236
+ }
237
+
220
238
  /*
221
239
  Execute specified sql batch.
222
240
  */
@@ -306,10 +324,7 @@ class Request extends BaseRequest {
306
324
  } catch (e) {
307
325
  // noop
308
326
  }
309
- if (this.parent._aborted) {
310
- const reason = err || errors[errors.length - 1]
311
- if (reason) this.parent._abortReason = reason
312
- }
327
+ this._recordAbortReason(err || errors[errors.length - 1])
313
328
  callback(err, ...args)
314
329
  }
315
330
  if (err) return callbackWithRelease(err)
@@ -561,10 +576,7 @@ class Request extends BaseRequest {
561
576
  }
562
577
 
563
578
  this.parent.release(connection)
564
- if (this.parent._aborted) {
565
- const reason = error || errors[errors.length - 1]
566
- if (reason) this.parent._abortReason = reason
567
- }
579
+ this._recordAbortReason(error || errors[errors.length - 1])
568
580
  hasReturned = true
569
581
 
570
582
  if (error) {
@@ -958,10 +970,7 @@ class Request extends BaseRequest {
958
970
  }
959
971
 
960
972
  this.parent.release(connection)
961
- if (this.parent._aborted) {
962
- const reason = error || errors[errors.length - 1]
963
- if (reason) this.parent._abortReason = reason
964
- }
973
+ this._recordAbortReason(error || errors[errors.length - 1])
965
974
  hasReturned = true
966
975
 
967
976
  if (error) {
@@ -22,6 +22,9 @@ class Transaction extends BaseTransaction {
22
22
  this._acquiredConnection.removeListener('rollbackTransaction', this._abort)
23
23
  this._acquiredConnection = null
24
24
  this._acquiredConfig = null
25
+ // the request or prepared statement that holds the connection can no longer give it
26
+ // back to the transaction, so the transaction stops waiting for it
27
+ this._activeRequest = null
25
28
  this._aborted = true
26
29
  this._abortReason = this._abortReason || new Error('Transaction was rolled back by the server')
27
30
 
package/package.json CHANGED
@@ -21,7 +21,7 @@
21
21
  "azure",
22
22
  "node-mssql"
23
23
  ],
24
- "version": "12.7.15",
24
+ "version": "12.7.16",
25
25
  "main": "index.js",
26
26
  "type": "commonjs",
27
27
  "repository": {