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.
- package/README.md +264 -7
- package/THIRD_PARTY_NOTICES.md +25 -0
- package/dist/bulk.d.ts +164 -0
- package/dist/bulk.d.ts.map +1 -0
- package/dist/bulk.js +1135 -0
- package/dist/bulk.js.map +1 -0
- package/dist/checks.d.ts +15 -0
- package/dist/checks.d.ts.map +1 -0
- package/dist/checks.js +19 -0
- package/dist/checks.js.map +1 -0
- package/dist/codecs.d.ts +1 -1
- package/dist/codecs.d.ts.map +1 -1
- package/dist/codecs.js +10 -2
- package/dist/codecs.js.map +1 -1
- package/dist/columns/index.d.ts +9 -1
- package/dist/columns/index.d.ts.map +1 -1
- package/dist/columns/index.js +5 -5
- package/dist/columns/index.js.map +1 -1
- package/dist/connection.d.ts +75 -12
- package/dist/connection.d.ts.map +1 -1
- package/dist/connection.js +216 -43
- package/dist/connection.js.map +1 -1
- package/dist/db.d.ts +51 -26
- package/dist/db.d.ts.map +1 -1
- package/dist/db.js +56 -2
- package/dist/db.js.map +1 -1
- package/dist/dialect.d.ts +4 -2
- package/dist/dialect.d.ts.map +1 -1
- package/dist/dialect.js +41 -15
- package/dist/dialect.js.map +1 -1
- package/dist/errors.d.ts +82 -1
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +90 -4
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +5 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/introspect/codegen.d.ts.map +1 -1
- package/dist/introspect/codegen.js +22 -12
- package/dist/introspect/codegen.js.map +1 -1
- package/dist/introspect/fetch.d.ts.map +1 -1
- package/dist/introspect/fetch.js +24 -8
- package/dist/introspect/fetch.js.map +1 -1
- package/dist/introspect/types.d.ts +5 -0
- package/dist/introspect/types.d.ts.map +1 -1
- package/dist/native/index.d.ts +97 -9
- package/dist/native/index.d.ts.map +1 -1
- package/dist/native/index.js +17 -0
- package/dist/native/index.js.map +1 -1
- package/dist/native/sybase_native.darwin-arm64.node +0 -0
- package/dist/native/sybase_native.darwin-x64.node +0 -0
- package/dist/native/sybase_native.linux-arm64.node +0 -0
- package/dist/native/sybase_native.linux-x64.node +0 -0
- package/dist/native/sybase_native.win32-x64.node +0 -0
- package/dist/pool.d.ts +24 -2
- package/dist/pool.d.ts.map +1 -1
- package/dist/pool.js +117 -37
- package/dist/pool.js.map +1 -1
- package/dist/query-builders/insert.d.ts.map +1 -1
- package/dist/query-builders/insert.js +5 -0
- package/dist/query-builders/insert.js.map +1 -1
- package/dist/query-builders/select.d.ts +5 -0
- package/dist/query-builders/select.d.ts.map +1 -1
- package/dist/query-builders/select.js +16 -0
- package/dist/query-builders/select.js.map +1 -1
- package/dist/result.d.ts +20 -7
- package/dist/result.d.ts.map +1 -1
- package/dist/result.js +35 -17
- package/dist/result.js.map +1 -1
- package/dist/session.d.ts +25 -2
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +134 -11
- package/dist/session.js.map +1 -1
- package/dist/table.d.ts.map +1 -1
- package/dist/table.js +5 -2
- package/dist/table.js.map +1 -1
- package/licenses/FreeTDS-COPYING_LIB.txt +481 -0
- package/package.json +8 -4
- package/patches/freetds-1.5.17-sybase-bulk.patch +592 -0
- package/scripts/build-native.ts +34 -0
- package/scripts/build-win.ps1 +49 -8
- package/scripts/build.sh +101 -30
- package/scripts/smoke-native.ts +67 -0
- package/scripts/smoke-package.sh +79 -0
- package/scripts/verify-published.ts +29 -5
- package/src/native/binding.c +3325 -322
- 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
|
|
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
|
-
|
|
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":"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"}
|