drizzle-sybase 4.0.0 → 5.0.0

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.
Files changed (88) hide show
  1. package/README.md +264 -7
  2. package/THIRD_PARTY_NOTICES.md +25 -0
  3. package/dist/bulk.d.ts +164 -0
  4. package/dist/bulk.d.ts.map +1 -0
  5. package/dist/bulk.js +1135 -0
  6. package/dist/bulk.js.map +1 -0
  7. package/dist/checks.d.ts +15 -0
  8. package/dist/checks.d.ts.map +1 -0
  9. package/dist/checks.js +19 -0
  10. package/dist/checks.js.map +1 -0
  11. package/dist/codecs.d.ts +1 -1
  12. package/dist/codecs.d.ts.map +1 -1
  13. package/dist/codecs.js +10 -2
  14. package/dist/codecs.js.map +1 -1
  15. package/dist/columns/index.d.ts +9 -1
  16. package/dist/columns/index.d.ts.map +1 -1
  17. package/dist/columns/index.js +5 -5
  18. package/dist/columns/index.js.map +1 -1
  19. package/dist/connection.d.ts +75 -12
  20. package/dist/connection.d.ts.map +1 -1
  21. package/dist/connection.js +216 -43
  22. package/dist/connection.js.map +1 -1
  23. package/dist/db.d.ts +51 -26
  24. package/dist/db.d.ts.map +1 -1
  25. package/dist/db.js +56 -2
  26. package/dist/db.js.map +1 -1
  27. package/dist/dialect.d.ts +4 -2
  28. package/dist/dialect.d.ts.map +1 -1
  29. package/dist/dialect.js +41 -15
  30. package/dist/dialect.js.map +1 -1
  31. package/dist/errors.d.ts +82 -1
  32. package/dist/errors.d.ts.map +1 -1
  33. package/dist/errors.js +90 -4
  34. package/dist/errors.js.map +1 -1
  35. package/dist/index.d.ts +5 -3
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +1 -1
  38. package/dist/index.js.map +1 -1
  39. package/dist/introspect/codegen.d.ts.map +1 -1
  40. package/dist/introspect/codegen.js +22 -12
  41. package/dist/introspect/codegen.js.map +1 -1
  42. package/dist/introspect/fetch.d.ts.map +1 -1
  43. package/dist/introspect/fetch.js +24 -8
  44. package/dist/introspect/fetch.js.map +1 -1
  45. package/dist/introspect/types.d.ts +5 -0
  46. package/dist/introspect/types.d.ts.map +1 -1
  47. package/dist/native/index.d.ts +97 -9
  48. package/dist/native/index.d.ts.map +1 -1
  49. package/dist/native/index.js +17 -0
  50. package/dist/native/index.js.map +1 -1
  51. package/dist/native/sybase_native.darwin-arm64.node +0 -0
  52. package/dist/native/sybase_native.darwin-x64.node +0 -0
  53. package/dist/native/sybase_native.linux-arm64.node +0 -0
  54. package/dist/native/sybase_native.linux-x64.node +0 -0
  55. package/dist/native/sybase_native.win32-x64.node +0 -0
  56. package/dist/pool.d.ts +24 -2
  57. package/dist/pool.d.ts.map +1 -1
  58. package/dist/pool.js +117 -37
  59. package/dist/pool.js.map +1 -1
  60. package/dist/query-builders/insert.d.ts.map +1 -1
  61. package/dist/query-builders/insert.js +5 -0
  62. package/dist/query-builders/insert.js.map +1 -1
  63. package/dist/query-builders/select.d.ts +5 -0
  64. package/dist/query-builders/select.d.ts.map +1 -1
  65. package/dist/query-builders/select.js +16 -0
  66. package/dist/query-builders/select.js.map +1 -1
  67. package/dist/result.d.ts +20 -7
  68. package/dist/result.d.ts.map +1 -1
  69. package/dist/result.js +35 -17
  70. package/dist/result.js.map +1 -1
  71. package/dist/session.d.ts +25 -2
  72. package/dist/session.d.ts.map +1 -1
  73. package/dist/session.js +134 -11
  74. package/dist/session.js.map +1 -1
  75. package/dist/table.d.ts.map +1 -1
  76. package/dist/table.js +5 -2
  77. package/dist/table.js.map +1 -1
  78. package/licenses/FreeTDS-COPYING_LIB.txt +481 -0
  79. package/package.json +8 -4
  80. package/patches/freetds-1.5.17-sybase-bulk.patch +592 -0
  81. package/scripts/build-native.ts +34 -0
  82. package/scripts/build-win.ps1 +49 -8
  83. package/scripts/build.sh +101 -30
  84. package/scripts/smoke-native.ts +67 -0
  85. package/scripts/smoke-package.sh +79 -0
  86. package/scripts/verify-published.ts +29 -5
  87. package/src/native/binding.c +3325 -322
  88. package/vendor/freetds-1.5.17.tar.gz +0 -0
package/README.md CHANGED
@@ -150,7 +150,11 @@ the number of rows (only with the largest single value) and the event loop
150
150
  stays free. The file is written beside `path` and renamed into place when the
151
151
  query succeeds: a failed query leaves an existing file untouched and no partial
152
152
  one behind, and a query whose connection was closed before it finished (as on a
153
- hard timeout) publishes nothing. On Linux and macOS the file is created
153
+ hard timeout) publishes nothing — unless the close lands while the finished file
154
+ is being renamed into place: then it is still published, possibly just after the
155
+ call has rejected (only a slow file system makes that window noticeable). So a
156
+ retry after a timeout should write to a path of its own: one into the same path
157
+ could be overwritten by the late rename of the attempt that timed out. On Linux and macOS the file is created
154
158
  readable by its owner only (mode `0600`), since it holds query results; `chmod`
155
159
  it if another user must read it. The file is not fsynced: it is meant to be read
156
160
  right away (by DuckDB, or an upload), not to survive a crash of the machine.
@@ -201,6 +205,242 @@ file (main thread busy ~20 ms, peak RSS ~0.4 GB) against about 4.7 s via
201
205
  `executeColumns` and the DuckDB appender (main thread busy ~3 s, peak RSS
202
206
  1.1–1.6 GB).
203
207
 
208
+ ## Bulk Copy (bcp, in process)
209
+
210
+ `db.bulkInsert()` loads rows with ASE's bulk copy protocol — what the `bcp`
211
+ utility uses — from inside the process: no `bcp` binary, no separate Lambda,
212
+ no payload limits. Rows are arrays of values or TSV, read as the copy goes:
213
+
214
+ ```ts
215
+ const { rowsCopied, batches } = await db.bulkInsert({
216
+ table: "apradb..DDSD", // db..table, db.owner.table, owner.table, table or #temp
217
+ columns: ["RCSBkey", "cd_unit_type", "line_number", "price"], // default: every column
218
+ rows: [["A0000001", "C", 1, "12.3456"] /* , ... */], // arrays, an async generator, or TSV
219
+ batchSize: 20_000, // default "all": one batch for the whole call
220
+ expectedRows: 20_000 // optional: fail unless exactly this many are copied
221
+ });
222
+ // { rowsCopied: 20000, batches: [{ rows: 20000 }], rejected: [], rejectedCount: 0, elapsedMs }
223
+ ```
224
+
225
+ It is on `db` (a pooled connection) and on `withConnection`'s handle (to load a
226
+ `#temp` table created in the same callback). It is not on a `db.transaction()`
227
+ handle, and is refused when a transaction is open, or in chained mode (where
228
+ every statement opens one): each batch it commits must be committed for good.
229
+
230
+ **Rows.**
231
+
232
+ - **Values:** any `Iterable` or `AsyncIterable` of arrays — an array, a
233
+ generator, an object-mode stream.
234
+ - **TSV:** a `string` or `Buffer` of UTF-8 text, or an iterable of such pieces
235
+ (e.g. `fs.createReadStream(path)`) split anywhere. bcp's character format:
236
+ fields separated by tab, rows by `\n` or `\r\n`, an empty field is NULL, no
237
+ quoting, binary columns in hex. As in bcp, every line is a row — an empty one
238
+ too — and a byte-order mark is data.
239
+ - An array of strings is TSV pieces, not rows: `["a", "b"]` is the one row
240
+ `ab`; rows of values are arrays (`[["a"], ["b"]]`).
241
+ - **Memory:** the input is never held whole. Rows are read ahead of what is
242
+ being sent, so reading and sending overlap: about three chunks of up to 4 MiB,
243
+ plus a copy of the TSV piece being cut (a stream's are 64 KiB).
244
+
245
+ **Atomicity.** Each batch is a transaction on the server: it commits whole or
246
+ not at all. With `batchSize: "all"` (the default), a failure before the server
247
+ confirms the copy's end commits nothing. With a batch size, each batch commits
248
+ as soon as it is full — even when it turns out to be the only one, before the
249
+ source is known to have ended — so a failure after it (the source throwing on
250
+ its next row, say) leaves it committed, and the error says exactly which:
251
+
252
+ ```ts
253
+ try {
254
+ await db.bulkInsert({ table, rows, batchSize: 20_000 });
255
+ } catch (err) {
256
+ if (err instanceof SybaseBulkCopyError) {
257
+ err.rowsCommitted; // rows of the batches the server confirmed before the failure
258
+ err.batches; // [{ rows }, ...] — the batches committed, each with its count
259
+ err.rowsInDoubt; // see below; 0 in every other case
260
+ (err.row, err.column); // the input row (1-based) and column a refused value was in
261
+ err.cause; // SybaseQueryError (e.g. Msg 2601 duplicate key), SybaseTimeoutError, ...
262
+ }
263
+ }
264
+ ```
265
+
266
+ A failed copy is abandoned by closing its connection — that is what makes the
267
+ server roll back the batch it never saw the end of — so the pool never hands
268
+ out a connection left in the middle of a copy. A duplicate key in a unique
269
+ index fails the batch that holds it, as a whole. The one case the outcome cannot be
270
+ known is when the connection is lost (or the deadline passes) while the server
271
+ is committing a batch: the answer never arrives, and the error reports those
272
+ rows as `rowsInDoubt` instead of guessing — every row of that batch handed to
273
+ the server, so an upper bound (rows it would have refused under `maxErrors` are
274
+ in it too). Only then does the caller have to look.
275
+
276
+ **Bulk copy is not an `insert`: CHECK constraints, foreign keys, rules and
277
+ triggers are not applied.** This is ASE's bulk copy itself — the `bcp` utility
278
+ behaves the same — not this driver: the server checks a row's types, NOT NULL
279
+ and unique indexes, but a row that breaks a CHECK constraint or references a
280
+ missing parent row is stored, and no insert trigger fires (checked against ASE
281
+ 15.7). So a copy into a table that has any of these is **refused** before it
282
+ starts, naming what the table has. Load such a table through a staging table
283
+ and an `insert ... select`; or, when the rows are known to satisfy them (or the
284
+ trigger need not run), pass `allowConstraintBypass: true` to copy anyway. The
285
+ check is made once, as the copy starts: changing the table's constraints or
286
+ triggers while a copy into it runs is not supported.
287
+
288
+ **Counts are the server's.** `rowsCopied` and each batch's `rows` are what the
289
+ server reported when it committed (`bcp_batch` / `bcp_done`), never what was
290
+ sent; a batch whose count differs from what was sent fails the call.
291
+ `expectedRows` is checked before the last commit, so a mismatch commits
292
+ nothing more.
293
+
294
+ **Locking and size.** A batch is one transaction holding its locks until it
295
+ commits. Once a batch holds more rows than the table's lock promotion
296
+ threshold, ASE escalates to a **table lock** for the rest of that batch,
297
+ blocking every other reader and writer of the table until it commits: the
298
+ `row lock promotion HWM` for datarows tables (ASE's default is 200; many
299
+ servers raise it — the one this was tested on uses 25,000; see
300
+ `sp_configure "row lock promotion HWM"` and `sp_setrowlockpromote`), the `page
301
+ lock promotion HWM` for allpages tables. On a table others use, keep
302
+ `batchSize` below it. A batch is also logged as one transaction (a table with
303
+ indexes gets a fully logged "slow" bcp), so a very large single batch needs log
304
+ space for all of it. The driver does not cap or split batches behind your back.
305
+
306
+ **Values are copied exactly, or refused.** Each value is checked and converted
307
+ before it is sent, with the query builders' rules — except that money takes no
308
+ `bigint` here (below):
309
+
310
+ - `money`/`smallmoney` take a decimal string (`"12.3456"`) — **not a
311
+ `bigint`**: an amount held as an integer may count whole units or
312
+ ten-thousandths, and guessing wrong stores it 10,000 times off without an
313
+ error. Turn it into the decimal string for its unit first.
314
+ - `numeric`/`decimal` take a decimal string or a `bigint` (a whole number).
315
+ More fraction digits than the column keeps are
316
+ refused, never rounded (`"1.50000"` is fine, `"12.34567"` into money is not).
317
+ A `number` is refused where it cannot hold every value of the column.
318
+ - Integers must be in the column's range; `bigint` takes a `bigint` or digits.
319
+ - `datetime`/`smalldatetime` take a `Date` (written as its wall clock in the
320
+ configured `timeZone`, like everywhere else) or a wall-clock string
321
+ `YYYY-MM-DD[ HH:MM[:SS[.mmm]]]`, stored as written. The sub-millisecond
322
+ rounding to 1/300 s is the server's own: a copied value equals the same
323
+ literal inserted with SQL.
324
+ - A string longer than its column is refused, never cut — measured in bytes in
325
+ the server's character set, after the trailing blanks ASE drops anyway.
326
+ - Bulk copy runs only against iso_1 and utf8 servers, the character sets text
327
+ is converted to; any other is refused rather than sent unconverted.
328
+ - A TSV row longer than 4 MiB fails the copy (no table's row comes near it).
329
+ - On an iso_1 server text is sent as Latin-1; a character Latin-1 cannot hold
330
+ (e.g. `中`) refuses its row, naming the row, column and character — it is
331
+ never stored as `?`.
332
+ - Text holding a NUL character refuses its row, as SQL text with one is
333
+ refused (db-lib would store a lone NUL as a blank).
334
+ - A number, date or bit given as a string of more than 127 characters refuses
335
+ its row: no value of those types is written that long.
336
+ - An empty string is stored as ASE stores `''` from SQL: one blank. NULL stays
337
+ NULL — except that, as with the bcp utility, a NULL (an empty TSV field,
338
+ `null`, `undefined`) or a column left out of `columns` gets the column's
339
+ DEFAULT. `ignoreDefaults: true` keeps them NULL instead (bcp's
340
+ `--ignoredefaults`).
341
+ - Identity columns are assigned by the server and left out of the default
342
+ `columns`. `keepIdentity: true` copies them from the rows (bcp's `-E`;
343
+ `identity_insert` is switched back off afterwards).
344
+ - `maxErrors: n` leaves up to `n` rows with a refused value out (listed in
345
+ `rejected`) instead of failing; the default 0 fails on the first.
346
+
347
+ Column types that can be loaded: `tinyint`, `smallint`, `int`, `bigint`, `bit`,
348
+ `float`, `real`, `money`, `smallmoney`, `numeric`, `decimal`, `datetime`,
349
+ `smalldatetime`, `char`, `varchar`, `nchar`, `nvarchar`, `binary`, `varbinary`.
350
+ Columns of other types (`text`, `image`, `unichar`, `univarchar`, `date`,
351
+ `time`, `bigdatetime`, unsigned integers, `timestamp`, ...) can be left out of
352
+ `columns`.
353
+
354
+ **Timeouts.** `timeoutSeconds` is the cooperative timeout for each wait on the
355
+ server during the copy — including a batch's commit, which on a large indexed
356
+ table can take a while — and `hardTimeoutMs` (default: twice that, at least
357
+ 30 s) bounds the whole call, reading the rows included. When it passes the
358
+ connection is closed, rolling back the open batch.
359
+
360
+ **Throughput.** The server sets the pace, not the driver. What helps:
361
+
362
+ - **Fewer, larger calls.** Each call costs about five round trips before and
363
+ after its rows (reading the table, opening the copy, ending it). Load a large
364
+ input in one call with `batchSize`, not many small calls.
365
+ - **Load staging tables before indexing them.** Every index is maintained row by
366
+ row during the copy; build it afterwards.
367
+
368
+ Datarows and datapages tables are supported through FreeTDS changes not yet
369
+ released, carried in `patches/`.
370
+
371
+ ## Timeouts
372
+
373
+ `timeout` (seconds, default 30) is the cooperative timeout of each connection:
374
+ when a statement waits on the server longer than that, db-lib cancels it and the
375
+ call fails with a `SybaseTimeoutError`, leaving the connection usable. It is
376
+ set on each connection's own DBPROCESS, not process-wide.
377
+
378
+ `timeoutSeconds` overrides it for one call, on `execute`, `exec`, `executeRaw`,
379
+ `executeColumns`, `executeToFile` and `bulkInsert`:
380
+
381
+ ```ts
382
+ await db.execute(sql`exec long_report ${id}`, { timeoutSeconds: 600 });
383
+ await db.executeRaw("select ...", { timeoutSeconds: 5 });
384
+ ```
385
+
386
+ It applies to that call only — set on its connection before the call and
387
+ restored after it; other calls, on that connection or others, keep theirs.
388
+
389
+ **Budget a call on its hard timeout, not on `timeoutSeconds`.** The cooperative
390
+ timeout limits each wait for the server, not the call: a query whose rows keep
391
+ arriving runs past it for as long as it takes. `hardTimeoutMs` bounds the whole
392
+ statement: when it passes, the call fails with a `SybaseTimeoutError` and the
393
+ connection is closed (the pool replaces it). The call settles by then, plus at
394
+ most one second — given a JS thread that is not blocked.
395
+
396
+ - **Default:** `max(2 * timeoutSeconds * 1000, 30000)` ms. A configured
397
+ `hardTimeoutMs` applies to calls that do not set their own `timeoutSeconds`
398
+ (a longer wait asked for must not be cut short by it).
399
+ - **`bulkInsert`:** it bounds the whole copy, reading the rows included, with no
400
+ grace.
401
+ - **Abandoned calls:** the worker thread and the server session are released
402
+ within about a second, even from one long wait (a lock, a `waitfor`).
403
+
404
+ ```ts
405
+ // Each wait at most 30 s; the statement at most 45 s.
406
+ await db.execute(sql`exec check_batch ${id}`, { timeoutSeconds: 30, hardTimeoutMs: 45_000 });
407
+ ```
408
+
409
+ **What it does not cover.** It starts when the statement is handed to the
410
+ native layer (waiting there for a worker thread counts). Not counted:
411
+
412
+ - waiting behind other calls on the same connection (several at once in a
413
+ `withConnection` callback, say);
414
+ - up to `acquireTimeoutMs` (default 10 s) waiting for a pool connection;
415
+ - after a statement that may have left session state behind (an open
416
+ transaction, `#temp` tables, a `SET`), a query or two to restore it, under
417
+ the connection's `timeout`;
418
+ - for a read-only statement whose connection was lost, `retries` more attempts
419
+ (default 2), each with its own acquire and hard timeout, `retryDelayMs` apart.
420
+
421
+ A call that must finish by a deadline needs an `acquireTimeoutMs` and
422
+ `hardTimeoutMs` that fit it, and a pool sized so calls do not queue.
423
+
424
+ ## Multiple Result Sets
425
+
426
+ A batch or procedure that selects several times returns only its first result
427
+ set by default (`rows`), as before. `allResultSets: true` returns all of them —
428
+ every result set that has columns, in order — as `resultSets`, with `rows`
429
+ still the first:
430
+
431
+ ```ts
432
+ const { rows, resultSets } = await db.executeRaw("exec report_with_totals @run = 42", {
433
+ allResultSets: true
434
+ });
435
+ // resultSets: [[...detail rows], [{ total: "1234.5000" }]]
436
+ ```
437
+
438
+ It works on `execute`, `exec`, `executeRaw` and `executeColumns` (there,
439
+ `resultSets` holds one `{ columns, rowCount }` per set). `maxRows` caps each
440
+ set on its own; as for one set, a set cut short there is not marked as such.
441
+ A statement of the batch that fails fails the call: the sets read before it are
442
+ not returned. `executeToFile` writes one result set and refuses the option.
443
+
204
444
  ## Why not `child_process` + `tsql`?
205
445
 
206
446
  | | Old (tsql child_process) | New (native db-lib) |
@@ -224,21 +464,35 @@ file (main thread busy ~20 ms, peak RSS ~0.4 GB) against about 4.7 s via
224
464
 
225
465
  All platform binaries are bundled in the package. At runtime, only the binary matching your `process.platform` + `process.arch` is loaded via `dlopen`.
226
466
 
467
+ - **Linux** binaries need glibc 2.34 or later — AWS Lambda's Amazon Linux 2023,
468
+ Debian 12, Ubuntu 22.04 and later. musl (Alpine) is not supported.
469
+ - **Windows** needs the Microsoft Visual C++ runtime (it links `/MD`).
470
+ - **No TLS.** FreeTDS is built without a TLS library, so the connection to ASE
471
+ is not encrypted: run it over a network you trust (a VPC, a VPN or an SSH
472
+ tunnel).
473
+
227
474
  ## Building from Source
228
475
 
229
- If no prebuilt binary exists for your platform:
476
+ To rebuild the binary for one of the platforms above (the loader knows no
477
+ others):
230
478
 
231
479
  ```bash
232
- # Requires: C compiler, node-gyp, curl
480
+ # Requires: C compiler, node-gyp, curl. On Windows: scripts/build-win.ps1
233
481
  bash scripts/build.sh
234
482
  ```
235
483
 
236
484
  This will:
237
485
 
238
- 1. Download FreeTDS source
486
+ 1. Download FreeTDS source, check its SHA-256, and apply
487
+ `patches/freetds-<version>-*.patch` (fixes from FreeTDS's development branch
488
+ not yet in a release, and a few of our own; each patch says which, and why)
239
489
  2. Compile as static library (`libsybdb.a`)
240
490
  3. Build the N-API addon linked against it
241
- 4. Place the `.node` file in `src/native/` (e.g. `sybase_native.darwin-arm64.node`)
491
+ 4. Place the `.node` file in `src/native/` (e.g. `sybase_native.darwin-arm64.node`),
492
+ and in `dist/native/` when it exists (an installed package)
493
+
494
+ After a change to `binding.c` alone, `npm run build:native` rebuilds just the
495
+ addon and puts it in the same places.
242
496
 
243
497
  ## Architecture
244
498
 
@@ -260,6 +514,7 @@ This will:
260
514
  │ sybase_native.node (C addon) │
261
515
  │ - connect() → dbopen() │
262
516
  │ - query() → dbcmd() + dbsqlexec() + dbresults() │
517
+ │ - bulkSend()→ bcp_sendrow() + bcp_batch()/done() │
263
518
  │ - close() → dbclose() │
264
519
  │ - Async on libuv worker threads │
265
520
  │ - FreeTDS libsybdb.a statically linked │
@@ -278,7 +533,7 @@ This will:
278
533
  - **Server-aborted transactions**: ASE rolls a transaction back on its own after some errors (conversion, divide-by-zero, deadlock). Once that happens the `tx` handle refuses further statements and `db.transaction` rejects instead of committing
279
534
  - **Raw multi-statement batches are not atomic**: after a statement-level error (e.g. a duplicate key) ASE carries on with the rest of the batch, so earlier and later statements may already be applied when the error is reported. Run such batches inside `db.transaction()` if they must be all-or-nothing
280
535
  - **Session state does not leak between pool users**: a connection always returns to the pool with no open transaction, `ROWCOUNT 0`, chained mode off, its original isolation level and the configured database. A raw statement outside `db.transaction()` that leaves a transaction open is rolled back and reported as an error — use `db.transaction()` instead. A connection that ran `setuser` is discarded rather than reused, since its original identity cannot be restored reliably. Other `SET` options (`dateformat`, `textsize`, ...) are not reset
281
- - **Inside `db.transaction()`, the callback must not end the transaction itself**: a batch containing `COMMIT` or a `ROLLBACK` without a savepoint name is refused before it is sent — once it ran, the rest of its batch would run in autocommit. A procedure that commits or rolls back cannot be seen in the SQL: the driver detects it after the call and refuses every later statement (what the procedure committed stays committed). Savepoints (`save tran x` / `rollback tran x`) are fine
536
+ - **Inside `db.transaction()`, the callback must not end the transaction itself**: a batch containing `COMMIT` or a `ROLLBACK` without a savepoint name is refused before it is sent — once it ran, the rest of its batch would run in autocommit. A procedure that commits or rolls back cannot be seen in the SQL: the driver detects it after the call (from `@@trancount`) and refuses every later statement (what the procedure committed stays committed). It cannot detect a procedure that ends the transaction and then begins another — the depth is the same — so do not call one that does. Savepoints (`save tran x` / `rollback tran x`) are fine
282
537
  - **Results are capped at 1,000,000 rows**: a larger result fails rather than being silently cut short. Pass `maxRows` (`db.execute(query, { maxRows })`, also on `exec`, `executeRaw` and `executeColumns`) to raise the cap or accept a truncated result. `executeToFile` holds no rows and has no cap
283
538
  - **Packet size**: `packetSize` defaults to 2048, ASE's out-of-the-box `max network packet size`. A server whose limit was raised (e.g. to 4096) can take a larger value for fewer round-trips on big results; one whose limit was lowered (it can go down to 512) needs a smaller one. A request above the server's limit is refused with the same "Login failed" (Msg 4002) as a wrong password — the error message points this out
284
539
  - **Temporary tables do not outlive their query or transaction**: a `#temp` table created by a pool query is dropped when that query finishes (the next one may run on another connection), and one created inside `db.transaction()` is dropped when the transaction ends. To use one across several statements, run them in `db.withConnection(async conn => ...)`: one connection, no transaction, and its `#temp` tables are dropped when the callback returns. (Inside `db.transaction()` ASE only allows creating them when `ddl in tran` is enabled.)
@@ -509,4 +764,6 @@ Unmapped Sybase types fall back to `varchar` and are reported via `warnings`.
509
764
 
510
765
  ## License
511
766
 
512
- MIT
767
+ MIT. The native binaries statically link [FreeTDS](https://www.freetds.org/),
768
+ which is licensed under the GNU LGPL; see
769
+ [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
@@ -0,0 +1,25 @@
1
+ # Third-party notices
2
+
3
+ ## FreeTDS
4
+
5
+ The native binaries in this package (`dist/native/sybase_native.*.node`) contain
6
+ [FreeTDS](https://www.freetds.org/) 1.5.17, statically linked: its db-lib and
7
+ libTDS libraries, licensed under the GNU Library General Public License, version
8
+ 2 or later. The license text is in
9
+ [licenses/FreeTDS-COPYING_LIB.txt](licenses/FreeTDS-COPYING_LIB.txt).
10
+
11
+ FreeTDS is modified by the patches in [patches/](patches/) (each says what it
12
+ changes and why; each file changed carries a notice saying so, and when). The
13
+ source it is built from is in this package:
14
+
15
+ - the FreeTDS 1.5.17 release tarball, `vendor/freetds-1.5.17.tar.gz` — as
16
+ published at <https://www.freetds.org/files/stable/freetds-1.5.17.tar.gz>
17
+ (SHA-256 `8d154ce458d1825a8625b0ef1c3288afecfc32b3a09015a5ece4fbdf8aafd144`),
18
+ - the patches in `patches/`, applied to it,
19
+ - the addon's own source (`src/native/binding.c`, `binding.gyp`) and the build
20
+ scripts (`scripts/`).
21
+
22
+ To link the addon against a modified FreeTDS, change or add a patch and run
23
+ `scripts/build.sh` (or `scripts/build-win.ps1` on Windows) from the package's
24
+ directory: it rebuilds FreeTDS from that source — no download needed — and then
25
+ the addon, and puts it where the package loads it from.
package/dist/bulk.d.ts ADDED
@@ -0,0 +1,164 @@
1
+ import type { SybaseBulkBatch, SybaseBulkRejectedRow } from "./errors.js";
2
+ import type { NativeBulkBeginOptions, NativeBulkBeginResult, NativeBulkChunkHeader, NativeBulkPayload, NativeBulkSendResult } from "./native/index.js";
3
+ /**
4
+ * One value of a row given to {@link SybaseBulkInsertOptions.rows}. What each
5
+ * column type accepts:
6
+ *
7
+ * | Column | Accepts |
8
+ * | -------------------------------------- | -------------------------------------------------------------- |
9
+ * | `tinyint`, `smallint`, `int`, `bigint` | an integer `number` (safe integers only), a `bigint`, a digit string |
10
+ * | `money`, `smallmoney` | a decimal string (`"12.3456"`) — not a `bigint`, whose unit (whole amounts or ten-thousandths) could only be guessed |
11
+ * | `numeric(p,s)`, `decimal(p,s)` | a decimal string or a `bigint`; a `number` if `p` ≤ 15 |
12
+ * | `float`, `real` | a `number` or a numeric string |
13
+ * | `bit` | a `boolean`, `0`/`1`, `"0"`/`"1"` |
14
+ * | `datetime`, `smalldatetime` | a `Date` (written in the connection's `timeZone`), or a wall-clock string `YYYY-MM-DD[ HH:MM[:SS[.mmm]]]`, stored as written |
15
+ * | `char`, `varchar` | a `string` |
16
+ * | `binary`, `varbinary` | a `Uint8Array` / `Buffer` |
17
+ *
18
+ * `null` and `undefined` are NULL — which, as with the bcp utility, a column
19
+ * with a DEFAULT replaces by its default (unless `ignoreDefaults`).
20
+ */
21
+ export type SybaseBulkValue = string | number | bigint | boolean | Date | Uint8Array | null | undefined;
22
+ /** One row: a value per copied column, in the order of `columns`. */
23
+ export type SybaseBulkRow = readonly SybaseBulkValue[];
24
+ /**
25
+ * The rows of a bulk copy:
26
+ *
27
+ * - **Value rows** — an `Iterable` or `AsyncIterable` of arrays (a generator, an
28
+ * array of arrays, a stream in object mode). Pulled as the copy goes, so the
29
+ * input is never held whole (memory: about three chunks of up to 4 MiB, plus
30
+ * one entry per committed batch in the result).
31
+ * - **TSV** — a `string` or `Uint8Array`/`Buffer` of UTF-8 text, or an
32
+ * `Iterable`/`AsyncIterable` of such pieces (e.g. `fs.createReadStream`),
33
+ * split anywhere. bcp character format: fields separated by tab, rows by
34
+ * newline (`\r\n` too); an empty field is NULL; no quoting or escaping, so a
35
+ * value cannot contain a tab or newline. Binary columns are hex.
36
+ */
37
+ export type SybaseBulkRows = string | Uint8Array | Iterable<SybaseBulkRow> | AsyncIterable<SybaseBulkRow> | Iterable<string | Uint8Array> | AsyncIterable<string | Uint8Array>;
38
+ /** Options of `bulkInsert`. */
39
+ export interface SybaseBulkInsertOptions {
40
+ /**
41
+ * The target: `db..table`, `db.owner.table`, `owner.table`, `table`, or a
42
+ * `#temp` table of the same connection (`withConnection`). Plain identifiers
43
+ * only — no brackets or quotes; at most 92 characters.
44
+ */
45
+ table: string;
46
+ /**
47
+ * The columns the rows give values for, in that order. Default: every column
48
+ * in table order, except identity columns (unless `keepIdentity`) and
49
+ * `timestamp`. Columns left out get NULL, or their DEFAULT.
50
+ */
51
+ columns?: readonly string[];
52
+ /** The rows; see {@link SybaseBulkRows}. */
53
+ rows: SybaseBulkRows;
54
+ /**
55
+ * Input rows per batch; each batch is committed on its own. `"all"` (the
56
+ * default) makes the whole call one batch: it then commits everything or
57
+ * nothing.
58
+ *
59
+ * ASE escalates to a table lock once a batch holds more rows than the
60
+ * table's row lock promotion HWM (200 by default for datarows/datapages
61
+ * tables, raised to 25,000 on many servers): a larger batch locks the whole
62
+ * table until it commits. Keep batches below it on a table others use.
63
+ */
64
+ batchSize?: number | "all";
65
+ /**
66
+ * Fail unless exactly this many rows are copied. Checked before the last
67
+ * commit, so a mismatch commits nothing more (earlier batches stay).
68
+ */
69
+ expectedRows?: number;
70
+ /**
71
+ * Copy the identity column's values from the rows (`set identity_insert on`
72
+ * for the copy, as `bcp -E` does) instead of letting the server assign them.
73
+ * The identity column must then be among `columns` (it is by default).
74
+ */
75
+ keepIdentity?: boolean;
76
+ /**
77
+ * Store NULL where a row gives NULL — and in columns left out of `columns` —
78
+ * instead of the column's DEFAULT: ASE bcp's `--ignoredefaults`. A NULL for
79
+ * a NOT NULL column then rejects the row, as for a column without a default.
80
+ * Default `false`: as with the bcp utility, a NULL (an empty TSV field,
81
+ * `null`, `undefined`) in a column that has a DEFAULT stores the default.
82
+ */
83
+ ignoreDefaults?: boolean;
84
+ /**
85
+ * Copy into a table that has an insert trigger, CHECK or foreign key
86
+ * constraints, or rules. ASE's bulk copy applies none of them (nor does the
87
+ * bcp utility): a row that breaks one is stored, and no trigger fires. So a
88
+ * copy into such a table is refused unless this is `true` — set it only when
89
+ * the rows are known to satisfy them, or that does not matter. Otherwise load
90
+ * a staging table and `insert ... select` from it.
91
+ */
92
+ allowConstraintBypass?: boolean;
93
+ /**
94
+ * How many rows may be left out because a value cannot be converted before
95
+ * the copy fails. Default 0: the first such row fails the copy. Rejected rows
96
+ * are listed in the result. A duplicate key in a unique index, which the
97
+ * server finds when it commits a batch, always fails that batch as a whole.
98
+ * (CHECK constraints, foreign keys and triggers are not applied by a bulk
99
+ * copy at all — see the README.)
100
+ */
101
+ maxErrors?: number;
102
+ /**
103
+ * Cooperative timeout, in seconds, for each wait on the server during the
104
+ * copy — including the commit of a batch, which on a large indexed table
105
+ * can take a while. Default: the connection's `timeout`.
106
+ */
107
+ timeoutSeconds?: number;
108
+ /**
109
+ * Deadline for the whole call, in ms. When it passes the copy is abandoned:
110
+ * the connection is closed, which makes the server roll back the open batch.
111
+ * Default: `max(2 * timeoutSeconds * 1000, 30000)`.
112
+ */
113
+ hardTimeoutMs?: number;
114
+ }
115
+ /** What a successful bulk copy did. */
116
+ export interface SybaseBulkInsertResult {
117
+ /** Rows committed, as the server reported them — never a count of what was sent. */
118
+ rowsCopied: number;
119
+ /** Every batch committed, in order. */
120
+ batches: SybaseBulkBatch[];
121
+ /** Rows left out under `maxErrors` (at most 1000 listed, in the order they were found). */
122
+ rejected: SybaseBulkRejectedRow[];
123
+ /** How many rows were left out under `maxErrors`. */
124
+ rejectedCount: number;
125
+ /** Wall-clock duration of the call, in ms. */
126
+ elapsedMs: number;
127
+ }
128
+ /**
129
+ * Reject bad options before a connection is taken for them.
130
+ *
131
+ * @internal
132
+ */
133
+ export declare const validateBulkInsertOptions: (options: SybaseBulkInsertOptions) => void;
134
+ /** What a connection provides for a copy; see `SybaseConnection.bulkInsert`. */
135
+ export interface BulkIo {
136
+ begin(options: Omit<NativeBulkBeginOptions, "hardTimeoutMs">): Promise<NativeBulkBeginResult>;
137
+ send(chunk: Omit<NativeBulkChunkHeader, "hardTimeoutMs"> & NativeBulkPayload): Promise<NativeBulkSendResult>;
138
+ /** `promise`, but rejecting once the copy's deadline has passed. */
139
+ race<T>(promise: Promise<T>): Promise<T>;
140
+ /** Whether the deadline has passed (the connection is then closed). */
141
+ readonly expired: boolean;
142
+ /**
143
+ * Check the deadline now, acting on it — closing the connection — if it has
144
+ * passed, and return whether it has. For loops that may not yield to the
145
+ * event loop for long (a source whose rows are all ready at once), where the
146
+ * deadline's timer could not fire on time.
147
+ */
148
+ checkDeadline(): boolean;
149
+ /** The error a passed deadline stands for. */
150
+ deadlineError(): Error;
151
+ /** Close the connection: the server rolls back the open batch. */
152
+ abandon(): void;
153
+ /** The `SybaseError` a native failure stands for. */
154
+ toCause(err: unknown): Error;
155
+ /** IANA zone `Date` values are written in. */
156
+ timeZone: string;
157
+ }
158
+ /**
159
+ * Run a whole copy over `io`.
160
+ *
161
+ * @internal
162
+ */
163
+ export declare const copyRows: (io: BulkIo, options: SybaseBulkInsertOptions) => Promise<SybaseBulkInsertResult>;
164
+ //# sourceMappingURL=bulk.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"bulk.d.ts","sourceRoot":"","sources":["../src/bulk.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EAErB,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAM3B;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,UAAU,GACV,IAAI,GACJ,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,MAAM,aAAa,GAAG,SAAS,eAAe,EAAE,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,UAAU,GACV,QAAQ,CAAC,aAAa,CAAC,GACvB,aAAa,CAAC,aAAa,CAAC,GAC5B,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,GAC7B,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;AAEvC,+BAA+B;AAC/B,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,4CAA4C;IAC5C,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,2FAA2F;IAC3F,QAAQ,EAAE,qBAAqB,EAAE,CAAC;IAClC,qDAAqD;IACrD,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;CACnB;AA2BD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,YAAa,uBAAuB,KAAG,IAyC5E,CAAC;AAwzBF,gFAAgF;AAChF,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,eAAe,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC9F,IAAI,CACF,KAAK,EAAE,IAAI,CAAC,qBAAqB,EAAE,eAAe,CAAC,GAAG,iBAAiB,GACtE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACjC,oEAAoE;IACpE,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,aAAa,IAAI,OAAO,CAAC;IACzB,8CAA8C;IAC9C,aAAa,IAAI,KAAK,CAAC;IACvB,kEAAkE;IAClE,OAAO,IAAI,IAAI,CAAC;IAChB,qDAAqD;IACrD,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAkBD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,OACf,MAAM,WACD,uBAAuB,KAC/B,OAAO,CAAC,sBAAsB,CAqXhC,CAAC"}