mssql 12.7.6 → 12.7.8

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
@@ -430,6 +430,12 @@ function processRows() {
430
430
  }
431
431
  ```
432
432
 
433
+ Nothing is emitted while the request is paused: `row`, `recordset`, `info`, `error`, `rowsaffected` and `done`
434
+ events wait until it is resumed. The msnodesqlv8 driver reads rows 50 at a time and only stops reading at the end
435
+ of a full batch, so the rows it reads before then are held until the request is resumed. A paused request that is
436
+ cancelled does not wait to be resumed: it drops the rows it holds, emits the other events it holds, and completes
437
+ with an `error` (`ECANCEL`) and `done` (see [cancel](#cancel)).
438
+
433
439
  ## Connection Pools
434
440
 
435
441
  An important concept to understand when using this library is [Connection Pooling](https://en.wikipedia.org/wiki/Connection_pool) as this library uses connection pooling extensively. As one Node JS process is able to handle multiple requests at once, we can take advantage of this long running process to create a pool of database connections for reuse; this saves overhead of connecting to the database for each request
@@ -928,6 +934,7 @@ __Errors__
928
934
  - ENOTOPEN (`ConnectionError`) - Connection not yet open.
929
935
  - ECONNCLOSED (`ConnectionError`) - Connection is closed.
930
936
  - ENOTBEGUN (`TransactionError`) - Transaction has not begun.
937
+ - EREQINPROG (`TransactionError`) - Can't acquire connection for the request. There is another request in progress.
931
938
  - EABORT (`TransactionError`) - Transaction was aborted (by user or because of an error).
932
939
 
933
940
  ---------------------------------------
@@ -1074,6 +1081,12 @@ pipeline(readableStream, transformStream, writableStream)
1074
1081
  request.query('select * from mytable')
1075
1082
  ```
1076
1083
 
1084
+ The readable stream is destroyed with the request's first error. Later errors are still emitted on the request, but not on the stream.
1085
+
1086
+ If the readable stream is destroyed before the request finishes (for example because a later stream in the pipeline failed), the request still runs to the end and the rows it has left are discarded. Call `request.cancel()` to stop it early.
1087
+
1088
+ With msnodesqlv8 before 5.6 that cancel does not stop it. The request is resumed as soon as its stream is destroyed, so that it does not keep its connection, and those versions can only cancel a paused request.
1089
+
1077
1090
 
1078
1091
  ### pipe (stream)
1079
1092
 
@@ -1097,6 +1110,21 @@ stream.on('finish', () => {
1097
1110
  })
1098
1111
  ```
1099
1112
 
1113
+ The stream is destroyed with the request's first error, so listen for `error` on it as above. It does not emit `finish` after an error. The request still runs to the end, and its remaining rows are discarded.
1114
+
1115
+ If the stream fails or closes before the request finishes, or was already destroyed, the request also runs to the end and its remaining rows are discarded, rather than waiting for a stream that will not read any more. Call `request.cancel()` to stop it early, bearing in mind the msnodesqlv8 caveat under [toReadableStream](#toreadablestream).
1116
+
1117
+ `pipe()` passes errors only to the stream it is given. If you pipe through more streams after that one, use `stream.pipeline()` with [`toReadableStream`](#toreadablestream) instead, so that every error reaches you:
1118
+
1119
+ ```javascript
1120
+ const { pipeline } = require('stream')
1121
+ const request = new sql.Request()
1122
+ pipeline(request.toReadableStream(), transformStream, writableStream, err => {
1123
+ // ...
1124
+ })
1125
+ request.query('select * from mytable')
1126
+ ```
1127
+
1100
1128
  ---------------------------------------
1101
1129
 
1102
1130
  ### query (command, [callback])
@@ -1130,6 +1158,7 @@ __Errors__
1130
1158
  - ENOTOPEN (`ConnectionError`) - Connection not yet open.
1131
1159
  - ECONNCLOSED (`ConnectionError`) - Connection is closed.
1132
1160
  - ENOTBEGUN (`TransactionError`) - Transaction has not begun.
1161
+ - EREQINPROG (`TransactionError`) - Can't acquire connection for the request. There is another request in progress.
1133
1162
  - EABORT (`TransactionError`) - Transaction was aborted (by user or because of an error).
1134
1163
  - EINJECT (`RequestError`) - Parameter type is not a valid identifier. See [Identifiers](#identifiers).
1135
1164
 
@@ -1177,6 +1206,7 @@ __Errors__
1177
1206
  - ENOTOPEN (`ConnectionError`) - Connection not yet open.
1178
1207
  - ECONNCLOSED (`ConnectionError`) - Connection is closed.
1179
1208
  - ENOTBEGUN (`TransactionError`) - Transaction has not begun.
1209
+ - EREQINPROG (`TransactionError`) - Can't acquire connection for the request. There is another request in progress.
1180
1210
  - EABORT (`TransactionError`) - Transaction was aborted (by user or because of an error).
1181
1211
  - EINJECT (`RequestError`) - Parameter type is not a valid identifier. See [Identifiers](#identifiers).
1182
1212
 
@@ -1224,6 +1254,7 @@ __Errors__
1224
1254
  - ENOTOPEN (`ConnectionError`) - Connection not yet open.
1225
1255
  - ECONNCLOSED (`ConnectionError`) - Connection is closed.
1226
1256
  - ENOTBEGUN (`TransactionError`) - Transaction has not begun.
1257
+ - EREQINPROG (`TransactionError`) - Can't acquire connection for the request. There is another request in progress.
1227
1258
  - EABORT (`TransactionError`) - Transaction was aborted (by user or because of an error).
1228
1259
  - EINJECT (`RequestError`) - Column name or parameter type is not a valid identifier. See [Identifiers](#identifiers).
1229
1260
 
@@ -1250,7 +1281,7 @@ request.cancel()
1250
1281
 
1251
1282
  A cancelled stream emits an `error` event with code `ECANCEL`, followed by `done`.
1252
1283
 
1253
- With the `msnodesqlv8` driver, a request that is already running can only be cancelled from msnodesqlv8 5.6. Earlier versions can cancel a paused stream, but let any other running request run to the end and complete as if `cancel()` had not been called.
1284
+ With the `msnodesqlv8` driver, a request that is already running can only be cancelled from msnodesqlv8 5.6. Earlier versions can cancel a paused stream, but let any other running request run to the end and complete as if `cancel()` had not been called. A paused stream is cancelled once the driver stops reading, at the end of a batch of 50 rows or the start of the next result set; a query that ends first, or times out, completes as cancelled.
1254
1285
 
1255
1286
  ## Transaction
1256
1287
 
@@ -1354,6 +1385,8 @@ __Errors__
1354
1385
  - ENOTOPEN (`ConnectionError`) - Connection not yet open.
1355
1386
  - EALREADYBEGUN (`TransactionError`) - Transaction has already begun.
1356
1387
 
1388
+ If the transaction fails to begin once it has a connection, the error is a `TransactionError`, with the error it comes from as its `originalError`. The connection goes back to the pool, and the transaction can be begun again. A connection that may have sent the request to begin the transaction is closed rather than lent out again, as the server may have begun the transaction even though the request failed (for example, when it timed out).
1389
+
1357
1390
  ---------------------------------------
1358
1391
 
1359
1392
  ### commit ([callback])
@@ -2186,7 +2219,7 @@ Name | Code | Message
2186
2219
  `ConnectionError` | ECONNCLOSED | Connection is closed.
2187
2220
  `TransactionError` | ENOTBEGUN | Transaction has not begun.
2188
2221
  `TransactionError` | EALREADYBEGUN | Transaction has already begun.
2189
- `TransactionError` | EREQINPROG | Can't commit/rollback transaction. There is a request in progress.
2222
+ `TransactionError` | EREQINPROG | Can't commit/rollback transaction or acquire connection for the request. There is a request in progress.
2190
2223
  `TransactionError` | EABORT | Transaction has been aborted.
2191
2224
  `RequestError` | EREQUEST | Message from SQL Server. Error object contains additional details.
2192
2225
  `RequestError` | ECANCEL | Cancelled.
@@ -401,7 +401,13 @@ class ConnectionPool extends EventEmitter {
401
401
  }))
402
402
 
403
403
  if (typeof callback === 'function') {
404
- acquirePromise.then(connection => callback(null, connection, this.config)).catch(callback)
404
+ // called back outside the promise chain, so that what the callback throws is not taken
405
+ // for a failure to acquire and passed back to it, but reaches the process as it would
406
+ // from any other callback
407
+ acquirePromise.then(
408
+ connection => process.nextTick(callback, null, connection, this.config),
409
+ err => process.nextTick(callback, err)
410
+ )
405
411
  return this
406
412
  }
407
413
 
@@ -10,6 +10,17 @@ const { TYPES } = require('../datatypes')
10
10
  const shared = require('../shared')
11
11
  const { CHANNELS, tracePromise, traceCallback, publish } = require('../diagnostics')
12
12
 
13
+ // a Readable runs a single destroy hook, so one the caller passed in its stream options runs after
14
+ // `destroy`, with the stream as `this` as the Readable would have run it. The options are spread to
15
+ // read it, as they are for the Readable, so only an own `destroy` counts and null options are fine
16
+ function withDestroyHook (streamOptions, destroy) {
17
+ const { destroy: hook } = { ...streamOptions }
18
+ if (typeof hook !== 'function') return destroy
19
+ return function (error, callback) {
20
+ destroy(error, () => hook.call(this, error, callback))
21
+ }
22
+ }
23
+
13
24
  /**
14
25
  * Class Request.
15
26
  *
@@ -429,22 +440,36 @@ class Request extends EventEmitter {
429
440
  toReadableStream (streamOptions = {}) {
430
441
  this.stream = true
431
442
  this.pause()
443
+ let requestDone = false
444
+ let requestCanceled = false
432
445
  const readableStream = new Readable({
433
446
  ...streamOptions,
434
447
  objectMode: true,
435
448
  read: (/* size */) => {
436
449
  this.resume()
437
- }
450
+ },
451
+ destroy: withDestroyHook(streamOptions, (error, callback) => {
452
+ // nothing will read from the stream again, so the request must not be left paused: it
453
+ // runs to the end, its remaining rows are dropped and its connection is released. A
454
+ // cancelled request is left to its driver, which is already stopping it: msnodesqlv8
455
+ // reports the cancel once the query is gone, and resuming it then reads a freed statement
456
+ if (!requestDone && !requestCanceled && this.paused) this.resume()
457
+ callback(error)
458
+ })
438
459
  })
439
460
  this.on('row', (row) => {
440
- if (!readableStream.push(row)) {
461
+ if (!readableStream.push(row) && !readableStream.destroyed) {
441
462
  this.pause()
442
463
  }
443
464
  })
444
465
  this.on('error', (error) => {
445
- readableStream.emit('error', error)
466
+ if (error.code === 'ECANCEL') requestCanceled = true
467
+ // the stream ends with the request's first error; destroying an already destroyed stream
468
+ // does nothing, so later errors stay with the request
469
+ readableStream.destroy(error)
446
470
  })
447
471
  this.on('done', () => {
472
+ requestDone = true
448
473
  readableStream.push(null)
449
474
  })
450
475
  return readableStream
@@ -453,6 +478,8 @@ class Request extends EventEmitter {
453
478
  /**
454
479
  * Wrap original request in a Readable stream that supports back pressure and pipe to the Writable stream.
455
480
  * It also sets request to `stream` mode and pulls all rows from all recordsets to a given stream.
481
+ * The Writable stream is destroyed with the request's first error. If the Writable stream fails or
482
+ * closes first, the request runs to the end and its remaining rows are discarded.
456
483
  *
457
484
  * @param {Stream} stream Stream to pipe data into.
458
485
  * @return {Stream}
@@ -460,6 +487,20 @@ class Request extends EventEmitter {
460
487
 
461
488
  pipe (writableStream) {
462
489
  const readableStream = this.toReadableStream()
490
+ // readable.pipe() leaves the source's errors to the source, but only the destination is
491
+ // handed back, so pass them on to it as pipeline() does
492
+ readableStream.on('error', (error) => {
493
+ writableStream.destroy(error)
494
+ })
495
+ // and when the destination fails or closes first, readable.pipe() only unpipes from it, which
496
+ // leaves the request paused with its connection: destroy the stream so the request runs to
497
+ // the end. 'unpipe' comes even from a destination that never emits 'close', and unlike
498
+ // finished() it adds no 'error' listener, which would stop an unhandled failure being thrown
499
+ writableStream.on('unpipe', (source) => {
500
+ if (source === readableStream && !readableStream.readableEnded) readableStream.destroy()
501
+ })
502
+ // a destination that is already destroyed will not fail or close again
503
+ if (writableStream.destroyed) readableStream.destroy()
463
504
  return readableStream.pipe(writableStream)
464
505
  }
465
506
 
@@ -14,6 +14,12 @@ const JSON_COLUMN_ID = 'JSON_F52E2B61-18A1-11d1-B105-00805F49916B'
14
14
  const XML_COLUMN_ID = 'XML_F52E2B61-18A1-11d1-B105-00805F49916B'
15
15
  const EMPTY_BUFFER = Buffer.alloc(0)
16
16
 
17
+ // msnodesqlv8 fetches a result set's rows this many at a time. It is only safe to pause once
18
+ // it has handed over every row of the batch it fetched: paused part way through a result set's
19
+ // last, short batch, it moves on to the next result set, or ends the query, with the rest of
20
+ // that batch still to come.
21
+ const DRIVER_ROW_BATCH_SIZE = 50
22
+
17
23
  // String() converts a Symbol, which only fails to convert implicitly; an object without a
18
24
  // working toString falls back to its tag
19
25
  const thrownMessage = function (value) {
@@ -24,6 +30,12 @@ const thrownMessage = function (value) {
24
30
  }
25
31
  }
26
32
 
33
+ // msnodesqlv8 >= 3 keeps the reader of a query on it, and the reader stops running as soon as
34
+ // the query ends, a few ticks before msnodesqlv8 reports the end with 'done' or 'free'
35
+ const stopped = function (query) {
36
+ return query.queryWorker?.running === false
37
+ }
38
+
27
39
  const castParameter = function (value, type) {
28
40
  if (value == null) {
29
41
  if ((type === TYPES.Binary) || (type === TYPES.VarBinary) || (type === TYPES.Image)) {
@@ -243,6 +255,16 @@ class Request extends BaseRequest {
243
255
  }
244
256
  }
245
257
 
258
+ // msnodesqlv8 throws, rather than calls back, for a query on a connection it has
259
+ // closed, so what it throws is handed to `done` as well, which releases the connection
260
+ const attempt = run => {
261
+ try {
262
+ run()
263
+ } catch (e) {
264
+ done(e)
265
+ }
266
+ }
267
+
246
268
  const go = () => {
247
269
  const tm = connection.tableMgr()
248
270
  // the table manager reports a failed lookup as (null, err), not error first
@@ -305,13 +327,15 @@ class Request extends BaseRequest {
305
327
  return done(e)
306
328
  }
307
329
 
308
- return connection.queryRaw(statement, function (err) {
330
+ return attempt(() => connection.queryRaw(statement, function (err) {
309
331
  if (err) { return done(err) }
310
- go()
311
- })
332
+ attempt(go)
333
+ }))
312
334
  } else {
313
- go()
335
+ attempt(go)
314
336
  }
337
+ } else {
338
+ callback(err)
315
339
  }
316
340
  })
317
341
  })
@@ -343,10 +367,44 @@ class Request extends BaseRequest {
343
367
  // set while the error just collected is being dispatched, along with whatever came with it
344
368
  let failing = false
345
369
  let cancelRequested = false
346
- // 'done' ends the request. msnodesqlv8 >= 5.6 emits it as soon as a cancel is through, and
347
- // the query can go on emitting after it, so the listeners ignore anything that follows
370
+ // 'done' or 'free' ends the request. msnodesqlv8 >= 5.6 emits 'done' as soon as a cancel is
371
+ // through, and the query can go on emitting after it, so the listeners ignore anything that
372
+ // follows
348
373
  let finished = false
349
374
 
375
+ // A stream goes on receiving rows after it is paused, until the driver reaches the end of a
376
+ // full batch (see DRIVER_ROW_BATCH_SIZE). What the stream emits waits here while it is
377
+ // paused, and is emitted in the order it arrived once it is resumed.
378
+ const pending = []
379
+ let rowsInRecordset = 0
380
+ let driverPaused = false
381
+ // a cancel of a paused stream waits for the driver to reach a point where it can be paused
382
+ let cancelDeferred = false
383
+ // msnodesqlv8 has freed the statement, which it does without 'done' after an error ends the query
384
+ let freed = false
385
+ let resuming = false
386
+ // a refused cancel undoes only the latest one
387
+ let cancelAttempts = 0
388
+
389
+ const emitInOrder = (isRow, emit) => {
390
+ if (this.stream && (this.paused || pending.length)) {
391
+ pending.push({ isRow, emit })
392
+ } else {
393
+ emit()
394
+ }
395
+ }
396
+
397
+ // once a cancel is through, what is waiting is emitted at once, but for the rows of a
398
+ // paused stream, which are dropped
399
+ const emitPendingOnCancel = () => {
400
+ // decided once, so that a listener that resumes the stream part way through cannot let
401
+ // the rows of the cancelled stream through
402
+ const dropRows = this.paused
403
+ for (const { isRow, emit } of pending.splice(0)) {
404
+ if (!isRow || !dropRows) emit()
405
+ }
406
+ }
407
+
350
408
  const handleError = (req, connection, info, moreErrors) => {
351
409
  // a cancel is reported from 'done'. msnodesqlv8 >= 5.6 also sends an 'Operation canceled'
352
410
  // error after a cancel, and one that arrives before 'done' is dropped here
@@ -359,7 +417,7 @@ class Request extends BaseRequest {
359
417
  err.code = 'EREQUEST'
360
418
 
361
419
  if (this.stream) {
362
- this.emit('error', err)
420
+ emitInOrder(false, () => this.emit('error', err))
363
421
  } else {
364
422
  if (doReturn && !hasReturned) {
365
423
  if (req) {
@@ -486,39 +544,160 @@ class Request extends BaseRequest {
486
544
 
487
545
  debug('request(%d): query', IDS.get(this), command)
488
546
 
489
- const req = connection.queryRaw({
490
- query_str: command,
491
- query_timeout: (this.overrides.requestTimeout ?? config.requestTimeout) / 1000 // msnodesqlv8 timeouts are in seconds (<1 second not supported)
492
- }, params)
547
+ // msnodesqlv8 throws, rather than calls back, for a query on a connection it has closed
548
+ let req
549
+ try {
550
+ req = connection.queryRaw({
551
+ query_str: command,
552
+ query_timeout: (this.overrides.requestTimeout ?? config.requestTimeout) / 1000 // msnodesqlv8 timeouts are in seconds (<1 second not supported)
553
+ }, params)
554
+ } catch (e) {
555
+ this.parent.release(connection)
556
+ const err = new RequestError(e, 'EREQUEST')
557
+ err.code = 'EREQUEST'
558
+ return callback(err)
559
+ }
493
560
 
494
561
  this._setCurrentRequest(req)
495
562
 
496
- this._cancel = () => {
497
- debug('request(%d): cancel', IDS.get(this))
498
- // newer msnodesqlv8 versions drop a repeat cancel without calling back, so the
499
- // outcome of the first one stands
500
- if (typeof req.getCancelSent === 'function' && req.getCancelSent()) {
501
- return
502
- }
503
- cancelRequested = true
563
+ // msnodesqlv8 does not check that a query is still running when it is paused or resumed.
564
+ // Pausing and resuming one that has ended puts it back on its connection's work queue,
565
+ // where it holds up whatever that connection is sent next, and resuming it can set it
566
+ // reading again from a statement that is gone, or crash the process. So once msnodesqlv8
567
+ // reports that the query has ended, the request no longer pauses, resumes or cancels it,
568
+ // before anything the request emits from then on is handled. Before then it leaves the
569
+ // query alone while an error that may end the batch is being handled and, from msnodesqlv8
570
+ // 3, once the query's reader has stopped
571
+ let detached = false
572
+ let settingAside = false
573
+ let cancelHeld = false
574
+ const detach = () => {
575
+ detached = true
576
+ }
577
+ const reachable = () => !detached && !settingAside && !stopped(req)
578
+
579
+ const cancelDriver = (attempt = cancelAttempts) => {
504
580
  req.cancelQuery(err => {
505
581
  if (err) {
506
582
  debug('request(%d): failed to cancel', IDS.get(this), err)
507
583
  // msnodesqlv8 < 5.6 refuses to cancel a query that is neither paused nor polling,
508
- // and the query runs to the end
509
- if (!hasReturned) cancelRequested = false
584
+ // and the query runs to the end; if it reached the end of a batch meanwhile, a
585
+ // stream that is no longer paused resumes it
586
+ if (!hasReturned && attempt === cancelAttempts) {
587
+ cancelRequested = false
588
+ this._resumeStream()
589
+ }
510
590
  }
511
- // this fixes an issue where paused connections don't emit a done event
591
+ // this fixes an issue where paused connections don't emit a done event; a query whose
592
+ // cancel was refused goes on, though it may have paused at the end of a batch since
512
593
  try {
513
- if (req.isPaused()) req.emit('done')
594
+ if (!err && req.isPaused()) req.emit('done')
514
595
  } catch (err) {
515
596
  // do nothing
516
597
  }
517
598
  })
518
599
  }
519
600
 
601
+ // every version of msnodesqlv8 cancels a paused query; it is paused here only where it stops
602
+ // for a pause, with nothing of its own under way
603
+ const pauseAndCancelDriver = () => {
604
+ cancelDeferred = false
605
+ // msnodesqlv8 5.0 to 5.5 send a query one cancel, which a cancel made before the query
606
+ // started has used up and they refused, so the query runs on
607
+ if (typeof req.getCancelSent === 'function' && req.getCancelSent()) {
608
+ cancelRequested = false
609
+ return false
610
+ }
611
+ driverPaused = true
612
+ req.pauseQuery()
613
+ cancelDriver()
614
+ return true
615
+ }
616
+
617
+ // called with each row once it is complete
618
+ const pauseDriverAtEndOfBatch = () => {
619
+ if (driverPaused || rowsInRecordset % DRIVER_ROW_BATCH_SIZE !== 0) return
620
+ if (cancelDeferred && pauseAndCancelDriver()) return
621
+ if (this.stream && this.paused) {
622
+ driverPaused = true
623
+ req.pauseQuery()
624
+ }
625
+ }
626
+
627
+ // until the first result set the driver has read nothing, so a stream paused before then,
628
+ // or before its query starts, holds it back at once
629
+ this._pauseStream = () => {
630
+ if (!columns && !driverPaused && !finished && reachable()) {
631
+ driverPaused = true
632
+ req.pauseQuery()
633
+ }
634
+ }
635
+ if (this.stream && this.paused) this._pauseStream()
636
+
637
+ this._resumeStream = () => {
638
+ // a listener that resumes the stream while it is emitting what was waiting leaves the
639
+ // rest to this loop, so that every listener gets the events in order
640
+ if (resuming) return
641
+ resuming = true
642
+ try {
643
+ while (pending.length && !this.paused) {
644
+ pending.shift().emit()
645
+ }
646
+ } finally {
647
+ resuming = false
648
+ }
649
+ // cancelled while it emitted what was waiting after the query ended, and then paused, a
650
+ // stream completes as cancelled straight away, as it does when it is paused first
651
+ if (finished && cancelRequested && this.paused && pending.length) emitPendingOnCancel()
652
+ // a query that is being cancelled stays paused, so that the cancel can go through
653
+ if (!pending.length && !this.paused && driverPaused && !finished && !cancelRequested && reachable()) {
654
+ driverPaused = false
655
+ req.resumeQuery()
656
+ }
657
+ }
658
+
659
+ const cancel = () => {
660
+ debug('request(%d): cancel', IDS.get(this))
661
+ // a query that has ended has nothing to cancel, nor one whose reader has stopped. The
662
+ // cancel is held: it is made if msnodesqlv8 goes on to a result set after all, and once
663
+ // the query is through a paused stream completes as cancelled, without waiting to be
664
+ // resumed
665
+ if (detached || stopped(req) || settingAside) {
666
+ cancelHeld = true
667
+ return
668
+ }
669
+ // newer msnodesqlv8 versions drop a repeat cancel without calling back, so the
670
+ // outcome of the first one stands
671
+ if (cancelDeferred || (typeof req.getCancelSent === 'function' && req.getCancelSent())) {
672
+ return
673
+ }
674
+ cancelRequested = true
675
+ cancelAttempts++
676
+ if (!this.stream || !this.paused || driverPaused) {
677
+ return cancelDriver()
678
+ }
679
+ // A paused stream holds the driver back only once it reaches the end of a batch. Until
680
+ // then the driver goes on reading, and pausing or cancelling it part way through a fetch,
681
+ // or as it moves to the next result set or ends the query, can leave its queue broken.
682
+ // So it is paused and cancelled when it next stops, at the end of a batch or the start
683
+ // of a result set, and a query that ends first, at the latest on the request timeout,
684
+ // is reported as cancelled.
685
+ if (freed) return req.emit('done')
686
+ cancelDeferred = true
687
+ }
688
+ this._cancel = cancel
689
+
520
690
  req.on('meta', metadata => {
521
691
  if (finished) return
692
+ // a query that goes on to a result set has not ended: msnodesqlv8 can give the last error
693
+ // of a statement that fails first more=false, and carry on to the statements after it
694
+ if (detached) {
695
+ detached = false
696
+ if (cancelHeld) {
697
+ cancelHeld = false
698
+ cancel()
699
+ }
700
+ }
522
701
 
523
702
  if (row) {
524
703
  if (isChunkedRecordset) {
@@ -536,7 +715,7 @@ class Request extends BaseRequest {
536
715
  const ex2 = new RequestError(`Failed to parse incoming JSON. ${ex.message}`, 'EJSON')
537
716
 
538
717
  if (this.stream) {
539
- this.emit('error', ex2)
718
+ emitInOrder(false, () => this.emit('error', ex2))
540
719
  } else {
541
720
  console.error(ex2)
542
721
  }
@@ -548,12 +727,14 @@ class Request extends BaseRequest {
548
727
  chunksBuffer = null
549
728
  if (row && row.___return___ == null) {
550
729
  // row with ___return___ col is the last row
551
- if (this.stream && !this.paused) this.emit('row', row)
730
+ const last = row
731
+ if (this.stream) emitInOrder(true, () => this.emit('row', last))
552
732
  }
553
733
  }
554
734
  }
555
735
 
556
736
  row = null
737
+ rowsInRecordset = 0
557
738
  columns = metadata
558
739
  recordset = []
559
740
 
@@ -588,16 +769,23 @@ class Request extends BaseRequest {
588
769
  }
589
770
  if (this.stream) {
590
771
  if (!hasReturnColumn) {
591
- this.emit('recordset', recordset.columns)
772
+ const recordsetColumns = recordset.columns
773
+ emitInOrder(false, () => this.emit('recordset', recordsetColumns))
592
774
  }
593
775
  } else {
594
776
  recordsets.push(recordset)
595
777
  }
596
778
  if (this.arrayRowMode) recordsetcolumns.push(recordset.columns)
779
+
780
+ // the driver fetches nothing of a result set it is paused at the start of
781
+ if (cancelDeferred) pauseAndCancelDriver()
597
782
  })
598
783
 
599
784
  req.on('row', rownumber => {
600
- if (finished || (row && isChunkedRecordset)) return
785
+ if (finished) return
786
+
787
+ rowsInRecordset++
788
+ if (row && isChunkedRecordset) return
601
789
 
602
790
  if (this.arrayRowMode) {
603
791
  row = []
@@ -642,11 +830,14 @@ class Request extends BaseRequest {
642
830
  }
643
831
  }
644
832
  if (!hasReturnColumn) {
645
- if (this.stream && !this.paused && idx === columns.length - 1) {
646
- this.emit('row', row)
833
+ if (this.stream && idx === columns.length - 1) {
834
+ const complete = row
835
+ emitInOrder(true, () => this.emit('row', complete))
647
836
  }
648
837
  }
649
838
  }
839
+
840
+ if (idx === columns.length - 1) pauseDriverAtEndOfBatch()
650
841
  })
651
842
 
652
843
  req.on('rowcount', rowCount => {
@@ -654,7 +845,7 @@ class Request extends BaseRequest {
654
845
 
655
846
  rowsAffected.push(rowCount)
656
847
  if (this.stream) {
657
- this.emit('rowsaffected', rowCount)
848
+ emitInOrder(false, () => this.emit('rowsaffected', rowCount))
658
849
  }
659
850
  })
660
851
 
@@ -666,7 +857,7 @@ class Request extends BaseRequest {
666
857
  msg.message = parsedMessage[1]
667
858
  }
668
859
 
669
- this.emit('info', {
860
+ const info = {
670
861
  message: msg.message,
671
862
  number: msg.code,
672
863
  state: msg.sqlstate,
@@ -674,7 +865,8 @@ class Request extends BaseRequest {
674
865
  lineNumber: msg.lineNumber || 0,
675
866
  serverName: msg.serverName,
676
867
  procName: msg.procName
677
- })
868
+ }
869
+ emitInOrder(false, () => this.emit('info', info))
678
870
 
679
871
  // query terminated
680
872
  if (msg.code === 3621 && !hasReturned) {
@@ -682,6 +874,7 @@ class Request extends BaseRequest {
682
874
  // msnodesqlv8 2.0 ends a statement's error with more=true and this message, and then
683
875
  // nothing follows: the error just collected is the one that terminated the statement.
684
876
  // A stream has already emitted it
877
+ detach()
685
878
  if (!this.stream) {
686
879
  const error = errors.pop()
687
880
  handleError(req, connection, error.originalError || error, false)
@@ -701,13 +894,48 @@ class Request extends BaseRequest {
701
894
  connection.hasError = true
702
895
  }
703
896
 
897
+ if (!moreErrors) {
898
+ // an error with nothing more to follow ends the batch
899
+ detach()
900
+ } else if (!detached && !settingAside) {
901
+ // the errors that end a batch are emitted together, all but the last with more=true,
902
+ // and msnodesqlv8 >= 5.1 releases the statement as soon as they are, so the query is
903
+ // set aside while they are handled, and a cancel made meanwhile waits until they have
904
+ // been. If none of them ended the batch it is taken up again and, if the stream was
905
+ // paused meanwhile before its first result set, paused, unless it is being cancelled.
906
+ // A stream that is paused holds its events back, so none is resumed meanwhile
907
+ settingAside = true
908
+ queueMicrotask(() => {
909
+ settingAside = false
910
+ if (cancelHeld) {
911
+ cancelHeld = false
912
+ cancel()
913
+ }
914
+ if (!detached && !cancelRequested && this.paused && this._pauseStream) this._pauseStream()
915
+ })
916
+ }
917
+
704
918
  if (finished) return
705
919
 
706
920
  handleError(req, connection, info, moreErrors)
707
921
  })
708
922
 
709
- req.once('done', () => {
923
+ req.on('free', () => {
924
+ freed = true
925
+ if (cancelDeferred && !finished) {
926
+ cancelDeferred = false
927
+ req.emit('done')
928
+ }
929
+ })
930
+
931
+ // msnodesqlv8 emits 'done' when a batch completes, but not when an error ends it; either
932
+ // way it emits 'free' once it has released the statement. A stream reports its errors as
933
+ // they arrive rather than settling on them, so without 'free' it would never complete
934
+ // after such an error, nor give its connection back
935
+ const complete = () => {
710
936
  finished = true
937
+ detach()
938
+ if (cancelHeld && this.stream && this.paused) cancelRequested = true
711
939
 
712
940
  if (hasReturned) {
713
941
  return
@@ -729,6 +957,9 @@ class Request extends BaseRequest {
729
957
 
730
958
  const err = new RequestError('Canceled.', 'ECANCEL')
731
959
  if (this.stream) {
960
+ delete this._resumeStream
961
+ delete this._pauseStream
962
+ emitPendingOnCancel()
732
963
  // as with tedious, a cancelled stream reports the cancel as an error and still
733
964
  // completes with what was read up to it
734
965
  this.emit('error', err)
@@ -770,7 +1001,7 @@ class Request extends BaseRequest {
770
1001
  const ex2 = new RequestError(`Failed to parse incoming JSON. ${ex.message}`, 'EJSON')
771
1002
 
772
1003
  if (this.stream) {
773
- this.emit('error', ex2)
1004
+ emitInOrder(false, () => this.emit('error', ex2))
774
1005
  } else {
775
1006
  console.error(ex2)
776
1007
  }
@@ -782,7 +1013,8 @@ class Request extends BaseRequest {
782
1013
  chunksBuffer = null
783
1014
  if (row && row.___return___ == null) {
784
1015
  // row with ___return___ col is the last row
785
- if (this.stream && !this.paused) { this.emit('row', row) }
1016
+ const last = row
1017
+ if (this.stream) emitInOrder(true, () => this.emit('row', last))
786
1018
  }
787
1019
  }
788
1020
  }
@@ -803,17 +1035,38 @@ class Request extends BaseRequest {
803
1035
  }
804
1036
  }
805
1037
 
806
- delete this._cancel
807
1038
  this.parent.release(connection)
808
1039
 
809
1040
  debug('request(%d): completed', IDS.get(this))
810
1041
 
811
1042
  if (this.stream) {
812
- callback(null, this._nested ? row : null, output, rowsAffected, recordsetcolumns)
1043
+ // the driver is through, but a paused stream completes once it has emitted what is
1044
+ // still waiting. Cancelled before then, it completes as cancelled: at once if it is
1045
+ // paused, dropping its rows, or else once it has emitted the rest
1046
+ this._cancel = () => {
1047
+ cancelRequested = true
1048
+ if (this.paused) emitPendingOnCancel()
1049
+ }
1050
+ const last = this._nested ? row : null
1051
+ emitInOrder(false, () => {
1052
+ delete this._cancel
1053
+ delete this._resumeStream
1054
+ delete this._pauseStream
1055
+ if (cancelRequested) {
1056
+ debug('request(%d): canceled', IDS.get(this))
1057
+ this.emit('error', new RequestError('Canceled.', 'ECANCEL'))
1058
+ return callback(null, null, output, rowsAffected, recordsetcolumns)
1059
+ }
1060
+ callback(null, last, output, rowsAffected, recordsetcolumns)
1061
+ })
813
1062
  } else {
1063
+ delete this._cancel
814
1064
  callback(null, recordsets, output, rowsAffected, recordsetcolumns)
815
1065
  }
816
- })
1066
+ }
1067
+
1068
+ req.once('done', complete)
1069
+ req.once('free', complete)
817
1070
  })
818
1071
  })
819
1072
  }
@@ -964,17 +1217,18 @@ class Request extends BaseRequest {
964
1217
  })
965
1218
  }
966
1219
 
1220
+ // the query pauses the driver itself, mostly at the end of a batch (see DRIVER_ROW_BATCH_SIZE)
967
1221
  _pause () {
968
1222
  super._pause()
969
- if (this._currentRequest) {
970
- this._currentRequest.pauseQuery()
1223
+ if (this._pauseStream) {
1224
+ this._pauseStream()
971
1225
  }
972
1226
  }
973
1227
 
974
1228
  _resume () {
975
1229
  super._resume()
976
- if (this._currentRequest) {
977
- this._currentRequest.resumeQuery()
1230
+ if (this._resumeStream) {
1231
+ this._resumeStream()
978
1232
  }
979
1233
  }
980
1234
  }
@@ -23,6 +23,15 @@ class Transaction extends BaseTransaction {
23
23
  super._begin(isolationLevel, err => {
24
24
  if (err) return callback(err)
25
25
 
26
+ // built before a connection is borrowed, so that an invalid isolation level is reported
27
+ // with nothing to give back
28
+ let statement
29
+ try {
30
+ statement = `set transaction isolation level ${isolationLevelDeclaration(this.isolationLevel)};begin tran;`
31
+ } catch (err) {
32
+ return callback(err)
33
+ }
34
+
26
35
  debug('transaction(%d): begin', IDS.get(this))
27
36
 
28
37
  this.parent.acquire(this, (err, connection, config) => {
@@ -33,13 +42,22 @@ class Transaction extends BaseTransaction {
33
42
 
34
43
  const req = new Request(this)
35
44
  req.stream = false
36
- req.query(`set transaction isolation level ${isolationLevelDeclaration(this.isolationLevel)};begin tran;`, err => {
45
+ req.query(statement, err => {
37
46
  if (err) {
38
- this.parent.release(this._acquiredConnection)
47
+ debug('transaction(%d): failed to begin', IDS.get(this), err)
48
+
39
49
  this._acquiredConnection = null
40
50
  this._acquiredConfig = null
41
51
 
42
- return callback(err)
52
+ // the server may have begun the transaction even though the query failed (it can
53
+ // time out after the server has run it), so the pool is left to close the connection
54
+ // rather than lend it out again with a transaction nobody will end. It is not closed
55
+ // here, as msnodesqlv8 never calls back from closing a connection that is already
56
+ // closed, and the pool would wait for it to
57
+ connection.hasError = true
58
+ this.parent.release(connection)
59
+
60
+ return callback(new TransactionError(err))
43
61
  }
44
62
 
45
63
  debug('transaction(%d): begun', IDS.get(this))
@@ -167,7 +167,13 @@ class ConnectionPool extends BaseConnectionPool {
167
167
  const poolId = IDS.get(this)
168
168
 
169
169
  if (tedious.closed) {
170
+ // already closed (tedious closes a connection whose socket ends, for one), but it is
171
+ // leaving the pool all the same
170
172
  debug('connection(%d): already closed', IDS.get(tedious))
173
+ publish(CHANNELS.CONNECTION_DESTROY, () => ({
174
+ connectionId,
175
+ poolId
176
+ }))
171
177
  resolve()
172
178
  } else {
173
179
  tedious.once('end', () => {
@@ -47,13 +47,42 @@ class Transaction extends BaseTransaction {
47
47
  this._acquiredConnection.on('rollbackTransaction', this._abort)
48
48
  this._acquiredConfig = config
49
49
 
50
- connection.beginTransaction(err => {
51
- if (err) err = new TransactionError(err)
52
-
53
- debug('transaction(%d): begun', IDS.get(this))
54
-
55
- callback(err)
56
- }, this.name, this.isolationLevel)
50
+ // the caller hears of one outcome, whatever tedious does
51
+ let calledBack = false
52
+ const done = (err, discard) => {
53
+ if (calledBack) return
54
+ calledBack = true
55
+
56
+ if (!err) {
57
+ debug('transaction(%d): begun', IDS.get(this))
58
+ return callback(null)
59
+ }
60
+
61
+ debug('transaction(%d): failed to begin', IDS.get(this), err)
62
+
63
+ connection.removeListener('rollbackTransaction', this._abort)
64
+ this._acquiredConnection = null
65
+ this._acquiredConfig = null
66
+
67
+ // deferred so that tedious is done with the connection before it is closed, and so
68
+ // that what the callback throws when tedious calls back at once is not caught below
69
+ // as though tedious had thrown it
70
+ setImmediate(() => {
71
+ if (discard) connection.close()
72
+ this.parent.release(connection)
73
+ callback(new TransactionError(err))
74
+ })
75
+ }
76
+
77
+ try {
78
+ // the server may have begun the transaction even though the request failed (it can
79
+ // time out after the server has run it), so the connection is closed rather than
80
+ // lent out again with a transaction nobody will end
81
+ connection.beginTransaction(err => done(err, true), this.name, this.isolationLevel)
82
+ } catch (err) {
83
+ // tedious validates the arguments before it sends anything
84
+ done(err, false)
85
+ }
57
86
  })
58
87
  })
59
88
  }
package/package.json CHANGED
@@ -21,7 +21,7 @@
21
21
  "azure",
22
22
  "node-mssql"
23
23
  ],
24
- "version": "12.7.6",
24
+ "version": "12.7.8",
25
25
  "main": "index.js",
26
26
  "type": "commonjs",
27
27
  "repository": {