node-firebird 2.12.0 → 2.14.0

package/lib/wire/connection.js

@@ -44,6 +44,7 @@ const srp = __importStar(require("../srp"));
 const crypt = __importStar(require("../unix-crypt"));
 const const_1 = __importDefault(require("./const"));
 const Xsql = __importStar(require("./xsqlvar"));
+const codepages_1 = require("./codepages");
 const service_1 = __importDefault(require("./service"));
 const database_1 = __importDefault(require("./database"));
 const statement_1 = __importDefault(require("./statement"));
@@ -109,6 +110,20 @@ function statementCacheLimit(options) {
 }
 // SQL type-code names live in xsqlvar.ts alongside the descriptors
 const SQL_TYPE_NAMES = Xsql.SQL_TYPE_NAMES;
+/**
+ * Build the wire parameter for a text value in the CONNECTION charset:
+ * plain SQLParamString for UTF-8 connections, pre-encoded bytes for
+ * everything else — SQLParamString hardwires utf8, which corrupted
+ * writes on latin1/codepage connections (issues #319/#301).
+ */
+function textParam(options, value) {
+    const codec = Xsql.resolveTextCodec(options);
+    const enc = Xsql.resolveTextEncoding(options);
+    if (!codec && enc === 'utf8') {
+        return new Xsql.SQLParamString(value);
+    }
+    return new Xsql.SQLParamBuffer(Xsql.encodeConnectionText(options, value));
+}
 /**
  * Run the user's typeCast hook (options.typeCast) for one column value.
  * The hook receives the column metadata and a next() returning the value
@@ -240,6 +255,24 @@ class Connection {
             (0, callback_1.doError)(err, queue[i]);
         }
     }
+    /**
+     * Deliver a connection-level error to 'error' listeners — and ONLY to
+     * listeners. Emitting an unlistened 'error' makes Node throw the error
+     * object as an uncaught exception; for errors that originate in
+     * background contexts (the reconnect timer, socket-level failures whose
+     * operations are separately rejected via _rejectPending) that crashes
+     * the process — or, under a test runner, fails whatever unrelated test
+     * happens to be running. The failing operations themselves always
+     * still receive their error through their own callbacks.
+     */
+    _emitError(err) {
+        if (this.db && typeof this.db.listenerCount === 'function' && this.db.listenerCount('error') > 0) {
+            this.db.emit('error', err);
+        }
+        else if (process.env.FIREBIRD_DEBUG) {
+            console.warn('[fb-debug] connection error (no error listener):', err && err.message);
+        }
+    }
     _bind_events(host, port, callback) {
         var self = this;
         self._socket.on('close', function () {
@@ -256,6 +289,14 @@ class Connection {
                 return;
             }
             self._rejectPending(lostError);
+            // Pooled connections do not self-reconnect: the pool is the
+            // recovery authority (dead-connection check on checkout + the
+            // reaper), and a background reconnect here would produce a
+            // zombie attachment the pool no longer tracks — whose own
+            // failures then surface as uncatchable async errors.
+            if (self.options && self.options.isPool) {
+                return;
+            }
             self._retry_connection_id = setTimeout(function () {
                 self._socket.removeAllListeners();
                 // transiently null while the replacement Connection is built
@@ -264,12 +305,12 @@ class Connection {
                 var ctx = new Connection(host, port, function (err) {
                     ctx.connect(self.options, function (err) {
                         if (err) {
-                            self.db.emit('error', err);
+                            self._emitError(err);
                             return;
                         }
                         ctx.attach(self.options, function (err) {
                             if (err) {
-                                self.db.emit('error', err);
+                                self._emitError(err);
                                 return;
                             }
                             self.db.emit('reconnect');
@@ -281,8 +322,10 @@ class Connection {
         });
         self._socket.on('error', function (e) {
             self.error = e;
-            if (self.db)
-                self.db.emit('error', e);
+            // listeners only (_emitError): the affected operations get their
+            // errors via the close handler's _rejectPending — an unlistened
+            // socket error must not become an uncaught exception
+            self._emitError(e);
             if (callback)
                 callback(e);
         });
@@ -648,7 +691,9 @@ class Connection {
         msg.pos = 0;
         blr.pos = 0;
         blr.addByte(const_1.default.isc_dpb_version1);
-        blr.addString(const_1.default.isc_dpb_lc_ctype, options.encoding || 'UTF8', const_1.default.DEFAULT_ENCODING);
+        // charset names are sent verbatim — normalize case so encoding:
+        // 'utf8'/'win1251' (e.g. from URI query params) is accepted
+        blr.addString(const_1.default.isc_dpb_lc_ctype, String(options.encoding || 'UTF8').toUpperCase(), const_1.default.DEFAULT_ENCODING);
         // For Firebird 3+ (protocol 13+), add UTF-8 filename flag to ensure all DPB strings are handled with UTF-8
         if (this.accept.protocolVersion >= const_1.default.PROTOCOL_VERSION13) {
             blr.addByte(const_1.default.isc_dpb_utf8_filename);
@@ -750,8 +795,13 @@ class Connection {
         var blr = this._blr;
         blr.pos = 0;
         blr.addByte(const_1.default.isc_dpb_version1);
-        blr.addString(const_1.default.isc_dpb_set_db_charset, 'UTF8', const_1.default.DEFAULT_ENCODING);
-        blr.addString(const_1.default.isc_dpb_lc_ctype, 'UTF8', const_1.default.DEFAULT_ENCODING);
+        // honour options.encoding on the CREATE path too — hardcoding UTF8
+        // for lc_ctype made attachOrCreate silently ignore the requested
+        // connection charset (issue #319: 'Malformed string' for codepage
+        // text). The new database's DEFAULT charset follows the connection
+        // encoding unless options.defaultCharset overrides it.
+        blr.addString(const_1.default.isc_dpb_set_db_charset, String(options.defaultCharset || options.encoding || 'UTF8').toUpperCase(), const_1.default.DEFAULT_ENCODING);
+        blr.addString(const_1.default.isc_dpb_lc_ctype, String(options.encoding || 'UTF8').toUpperCase(), const_1.default.DEFAULT_ENCODING);
         // For Firebird 3+ (protocol 13+), add UTF-8 filename flag to ensure all DPB strings are handled with UTF-8
         if (this.accept.protocolVersion >= const_1.default.PROTOCOL_VERSION13) {
             blr.addByte(const_1.default.isc_dpb_utf8_filename);
@@ -835,7 +885,9 @@ class Connection {
     }
     throwClosed(callback) {
         var err = new Error('Connection is closed.');
-        this.db.emit('error', err);
+        // listeners only: the caller receives the error through its own
+        // callback below either way
+        this._emitError(err);
         if (callback)
             callback(err);
         return this;
@@ -1027,7 +1079,9 @@ class Connection {
         msg.addInt(transaction.handle);
         msg.addInt(0xFFFF);
         msg.addInt(3); // dialect = 3
-        msg.addString(query, const_1.default.DEFAULT_ENCODING);
+        // SQL text travels in the CONNECTION charset (codepage
+        // connections encode via codec — greek/cyrillic literals included)
+        msg.addStringBuffer(Xsql.encodeConnectionText(this.options, query));
         msg.addBlr(blr);
         msg.addInt(65535); // buffer_length
         if (this.accept.protocolVersion >= const_1.default.PROTOCOL_VERSION20) {
@@ -1075,7 +1129,9 @@ class Connection {
         msg.addInt(transaction.handle);
         msg.addInt(statement.handle);
         msg.addInt(3); // dialect = 3
-        msg.addString(query, const_1.default.DEFAULT_ENCODING);
+        // SQL text travels in the CONNECTION charset (codepage
+        // connections encode via codec — greek/cyrillic literals included)
+        msg.addStringBuffer(Xsql.encodeConnectionText(this.options, query));
         msg.addBlr(blr);
         msg.addInt(65535); // buffer_length
         if (this.accept.protocolVersion >= const_1.default.PROTOCOL_VERSION20) {
@@ -1100,10 +1156,13 @@ class Connection {
      * gets an in-order response (op_batch_cs for exec), so the regular
      * response queue keeps everything in sync.
      *
-     * rows: array of parameter arrays, one per record. BLOB/ARRAY columns
-     * are not supported yet. The callback receives a completion object:
-     * { recordCount, updateCounts, errors: [{recordNumber, error}],
-     *   errorRecordNumbers, success }.
+     * rows: array of parameter arrays, one per record. BLOB columns accept
+     * Buffers, strings, JSON-able objects or pre-created blob quad ids —
+     * values are uploaded as transaction blobs first (all initiated
+     * back-to-back so they pipeline) and the batch messages reference their
+     * ids. ARRAY columns are not supported. The callback receives a
+     * completion object: { recordCount, updateCounts, errors:
+     * [{recordNumber, error}], errorRecordNumbers, success }.
      */
     executeBatch(transaction, statement, rows, callback, options) {
         options = options || {};
@@ -1135,6 +1194,82 @@ class Connection {
                 return;
             }
         }
+        var self = this;
+        // BLOB pre-pass: upload every Buffer/string blob value as a
+        // transaction blob and replace it (in a cloned row) with the quad
+        // id the batch message will carry. All uploads are initiated
+        // back-to-back, so the create/segment/close ops pipeline on the
+        // wire instead of paying a round trip per blob.
+        var blobCols = [];
+        for (var bj = 0; bj < input.length; bj++) {
+            var bt = input[bj].type;
+            if (bt === const_1.default.SQL_BLOB || bt === const_1.default.SQL_QUAD) {
+                blobCols.push(bj);
+            }
+        }
+        // all-NULL blob columns are common — a large row set must not pay
+        // for a full clone when there is nothing to upload or unwrap
+        var needsBlobPass = false;
+        if (blobCols.length) {
+            outer: for (var ri = 0; ri < rows.length; ri++) {
+                for (var ci = 0; ci < blobCols.length; ci++) {
+                    var bv = rows[ri][blobCols[ci]];
+                    if (bv !== null && bv !== undefined) {
+                        needsBlobPass = true;
+                        break outer;
+                    }
+                }
+            }
+        }
+        if (needsBlobPass) {
+            var cloned = rows.map(function (r) { return r.slice(); });
+            var pendingBlobs = 1; // sentinel so zero uploads still settle
+            var blobFailure = null;
+            var settleBlobs = function (err) {
+                if (err && !blobFailure) {
+                    blobFailure = err;
+                }
+                if (--pendingBlobs) {
+                    return;
+                }
+                if (blobFailure) {
+                    (0, callback_1.doError)(blobFailure, callback);
+                    return;
+                }
+                self._executeBatchEncoded(transaction, statement, cloned, callback, options);
+            };
+            cloned.forEach(function (row) {
+                blobCols.forEach(function (j) {
+                    var v = row[j];
+                    if (v === null || v === undefined) {
+                        return;
+                    }
+                    // a pre-created blob id (SQLParamQuad wrapper) passes
+                    // through; plain {high, low} objects are deliberately NOT
+                    // treated as ids — they are legitimate JSON blob content
+                    // and would silently misroute to a bogus blob reference
+                    if (v instanceof Xsql.SQLParamQuad) {
+                        row[j] = v.value;
+                        return;
+                    }
+                    pendingBlobs++;
+                    self.uploadBlob(transaction, v, function (err, oid) {
+                        if (!err) {
+                            row[j] = oid;
+                        }
+                        settleBlobs(err);
+                    });
+                });
+            });
+            settleBlobs();
+            return;
+        }
+        this._executeBatchEncoded(transaction, statement, rows, callback, options);
+    }
+    /** Encode and send the batch packets (rows are fully materialized:
+     *  blob values already replaced by quad ids by executeBatch). */
+    _executeBatchEncoded(transaction, statement, rows, callback, options) {
+        var input = statement.input;
         var built;
         try {
             built = buildBatchEncoders(input, Object.assign({}, this.options, options));
@@ -1302,9 +1437,9 @@ class Connection {
                     if (Buffer.isBuffer(value))
                         b = value;
                     else if (typeof (value) === 'string')
-                        b = Buffer.from(value, const_1.default.DEFAULT_ENCODING);
+                        b = Xsql.encodeConnectionText(self.options, value);
                     else if (!isStream)
-                        b = Buffer.from(JSON.stringify(value), const_1.default.DEFAULT_ENCODING);
+                        b = Xsql.encodeConnectionText(self.options, JSON.stringify(value));
                     // Use configured transfer size or default to 1024
                     var chunkSize = self.options.blobChunkSize || 1024;
                     if (Buffer.isBuffer(b)) {
@@ -1445,14 +1580,18 @@ class Connection {
                                             ret[i] = new Xsql.SQLParamDouble(value);
                                         break;
                                     case 'string':
-                                        ret[i] = new Xsql.SQLParamString(value);
+                                        ret[i] = textParam(self.options, value);
                                         break;
                                     case 'boolean':
-                                        ret[i] = new Xsql.SQLParamBool(value);
+                                        // metadata-directed: BOOLEAN targets get a
+                                        // real blr_bool (issue #122); smallint
+                                        // targets keep the legacy 0/1 (BOOLEAN
+                                        // does not convert to numbers)
+                                        ret[i] = new Xsql.SQLParamBool(value, meta.type === const_1.default.SQL_BOOLEAN);
                                         break;
                                     default:
                                         //throw new Error('Unexpected parametter: ' + JSON.stringify(params) + ' - ' + JSON.stringify(input));
-                                        ret[i] = new Xsql.SQLParamString(value.toString());
+                                        ret[i] = textParam(self.options, value.toString());
                                         break;
                                 }
                             }
@@ -1683,6 +1822,33 @@ class Connection {
         msg.addInt(65535); // buffer_length
         this._queueEvent(callback);
     }
+    /**
+     * Resolve the pending blobAsText fetches of a decoded row batch
+     * (ret.arrBlob) and write the text back into ret.data. Reads run
+     * sequentially to respect Firebird's per-connection open-blob-handle
+     * limit (issue #387). Used by fetchAll for cursors and by
+     * transaction.execute for op_execute2 singletons (EXECUTE PROCEDURE /
+     * RETURNING — issue #305, whose blobs never resolved before).
+     */
+    resolveTextBlobs(transaction, ret, callback) {
+        const self = this;
+        const fns = (ret && ret.arrBlob) || [];
+        if (!fns.length) {
+            return callback();
+        }
+        const read = (index) => {
+            if (index >= fns.length) {
+                return callback();
+            }
+            fns[index](transaction).then((blob) => {
+                // nestTables === true rows: the value lives in the
+                // per-table sub-object, not on the row itself
+                Xsql.nestCell(ret.data[blob.row], blob.table)[blob.column] = applyTypeCast(self.options, blob.meta || {}, parseValueIfJson(blob.value, self.options));
+                read(index + 1);
+            }, callback);
+        };
+        read(0);
+    }
     fetchAll(statement, transaction, callback) {
         const self = this;
         const custom = statement.options || {};
@@ -1695,26 +1861,10 @@ class Connection {
                 return;
             }
             if (ret && ret.data && ret.data.length) {
-                // Read blobs sequentially instead of in parallel to avoid
-                // exceeding Firebird's per-connection open-blob-handle limit,
-                // which causes a server-side deadlock when many rows contain
-                // BLOBs and blobAsText is true. See issue #387.
-                const arrBlobFns = ret.arrBlob || [];
-                const readBlobsSequentially = (index, results) => {
-                    if (index >= arrBlobFns.length) {
-                        return Promise.resolve(results);
-                    }
-                    return arrBlobFns[index](transaction).then((v) => {
-                        results.push(v);
-                        return readBlobsSequentially(index + 1, results);
-                    });
-                };
-                readBlobsSequentially(0, []).then((arrBlob) => {
-                    for (let i = 0; i < arrBlob.length; i++) {
-                        const blob = arrBlob[i];
-                        // nestTables === true rows: the value lives in the
-                        // per-table sub-object, not on the row itself
-                        Xsql.nestCell(ret.data[blob.row], blob.table)[blob.column] = applyTypeCast(statement.connection.options, blob.meta || {}, parseValueIfJson(blob.value, statement.connection.options));
+                self.resolveTextBlobs(transaction, ret, (blobErr) => {
+                    if (blobErr) {
+                        callback(blobErr);
+                        return;
                     }
                     doSynchronousLoop(ret.data, (row, _i, next) => {
                         const pos = asStream ? streamIndex++ : (data.push(row) - 1);
@@ -1736,7 +1886,7 @@ class Connection {
                             self.fetch(statement, transaction, const_1.default.DEFAULT_FETCHSIZE, loop);
                         }
                     });
-                }).catch(callback);
+                });
                 return;
             }
             if (ret && ret.fetched) {
@@ -1794,6 +1944,47 @@ class Connection {
         msg.addBlr(blr);
         this._queueEvent(callback);
     }
+    /**
+     * Create a transaction blob, upload `value` (Buffer, string, or a
+     * JSON-able object) and deliver its quad id. executeBatch's blob
+     * pre-pass uses this: batch messages reference pre-created transaction
+     * blobs (the batch parameter buffer's default BLOB_NONE policy), just
+     * like the classic execute path stores blob params.
+     */
+    uploadBlob(transaction, value, callback) {
+        var self = this;
+        var b;
+        if (Buffer.isBuffer(value)) {
+            b = value;
+        }
+        else if (typeof value === 'string') {
+            b = Xsql.encodeConnectionText(this.options, value);
+        }
+        else {
+            b = Xsql.encodeConnectionText(this.options, JSON.stringify(value));
+        }
+        self.createBlob2(transaction, function (err, blob) {
+            if (err) {
+                return callback(err);
+            }
+            var chunkSize = self.options.blobChunkSize || 1024;
+            // bufferReader's next() drops errors — capture the first segment
+            // failure so a truncated upload is never reported as success
+            var segmentError = null;
+            bufferReader(b, chunkSize, function (part, next) {
+                self.batchSegments(blob, part, function (segErr) {
+                    if (segErr && !segmentError) {
+                        segmentError = segErr;
+                    }
+                    next();
+                });
+            }, function () {
+                self.closeBlob(blob, function (closeErr) {
+                    callback(segmentError || closeErr, blob.oid);
+                }, false);
+            });
+        });
+    }
     svcattach(options, callback, svc) {
         this._lowercase_keys = options.lowercase_keys || const_1.default.DEFAULT_LOWERCASE_KEYS;
         var database = options.database || options.filename;
@@ -2832,6 +3023,43 @@ function describe(buff, statement) {
     }
     unpackCharSetCollation(statement.input);
     unpackCharSetCollation(statement.output);
+    scaleOutputLengths(statement.output, statement.connection && statement.connection.options);
+}
+/**
+ * Widen declared OUTPUT byte lengths for text columns whose charset the
+ * server did NOT transliterate in the describe. Under a UTF8 connection
+ * the server rewrites known charsets (a WIN1251 VARCHAR(15) is described
+ * as UTF8 with length 60) — but NONE (and any untransliterated charset)
+ * keeps its native length, and the engine's fetch-time capacity check
+ * then treats those bytes as connection-charset characters: VARCHAR(15)
+ * NONE declared as 15 bytes only fits floor(15/4) = 3 characters and
+ * longer values fail with "string right truncation" (issue #422).
+ * Declaring charCapacity × connectionWidth bytes makes the check pass;
+ * the width-based trim in the text decoders restores the column's true
+ * character capacity. The native length is preserved for metadata.
+ */
+function scaleOutputLengths(output, options) {
+    if (!output || !output.length)
+        return;
+    const connWidth = Xsql.getFirebirdCharsetWidth(options && options.encoding);
+    if (connWidth <= 1)
+        return;
+    for (let i = 0; i < output.length; i++) {
+        const p = output[i];
+        if (!p || (p.type !== const_1.default.SQL_TEXT && p.type !== const_1.default.SQL_VARYING))
+            continue;
+        // OCTETS (id 1) is binary and never transliterated
+        if (p.charSetId === undefined || p.charSetId === 1)
+            continue;
+        const colWidth = (0, codepages_1.charsetWidthById)(p.charSetId);
+        if (colWidth >= connWidth)
+            continue;
+        p.nativeLength = p.length;
+        // BLR encodes the length as a 16-bit word — cap the widened value
+        // (a >16KB single-byte column keeps its full byte capacity, it just
+        // can't be over-declared four-fold)
+        p.length = Math.min(Math.floor(p.length / colWidth) * connWidth, Math.floor(0xFFFF / connWidth) * connWidth);
+    }
 }
 /**
  * Batch support: the engine requires every batch message to use EXACTLY the
@@ -2858,7 +3086,7 @@ function buildBatchEncoders(input, options) {
         return String(v);
     };
     var toBytes = function (v, meta, column) {
-        var b = Buffer.isBuffer(v) ? v : Buffer.from(toText(v), const_1.default.DEFAULT_ENCODING);
+        var b = Buffer.isBuffer(v) ? v : Xsql.encodeConnectionText(options, toText(v));
         if (b.length > meta.length) {
             throw new Error('Batch value for column ' + column + ' is ' + b.length +
                 ' bytes but the column accepts at most ' + meta.length + ' (' + (meta.field || '?') + ')');
@@ -2994,6 +3222,24 @@ function buildBatchEncoders(input, options) {
                 align(4);
                 offset += 4;
                 break;
+            case const_1.default.SQL_BLOB:
+            case const_1.default.SQL_QUAD:
+                // the value is a transaction blob quad id — placed by
+                // executeBatch's uploadBlob pre-pass, or passed by the
+                // caller directly. ISC_QUAD: two longs, align 4.
+                encoders.push((function (col) {
+                    return function (msg, v) {
+                        if (!v || typeof v.high !== 'number' || typeof v.low !== 'number') {
+                            throw new Error('Batch value for BLOB column ' + col +
+                                ' must be a Buffer, string, object, or blob quad id');
+                        }
+                        msg.addInt(v.high);
+                        msg.addInt(v.low);
+                    };
+                })(column));
+                align(4);
+                offset += 8;
+                break;
             default:
                 throw new Error('executeBatch does not support the type of parameter ' + column +
                     ' yet (' + (meta.field || '?') + ', SQL type ' + meta.type + ')');
@@ -3042,11 +3288,15 @@ function CalcBlr(blr, xsqlda) {
 }
 function fetch_blob_async_transaction(statement, id, column, row, meta, table) {
     const infoValue = { row, column, value: '', meta, table };
+    // decode ONCE from the concatenated bytes: per-segment toString() both
+    // ignored the connection charset (#301 — cyrillic mojibake) and could
+    // split a multi-byte UTF-8 character across segment boundaries
+    const chunks = [];
     return (transactionArg) => {
         const cacheKey = `${id.high}:${id.low}`;
         if (statement.connection._inlineBlobs && statement.connection._inlineBlobs.has(cacheKey)) {
             const data = statement.connection._inlineBlobs.get(cacheKey);
-            infoValue.value = data ? data.toString(const_1.default.DEFAULT_ENCODING) : '';
+            infoValue.value = data ? Xsql.decodeConnectionText(statement.connection.options, data) : '';
             return Promise.resolve(infoValue);
         }
         const singleTransaction = transactionArg === undefined;
@@ -3085,13 +3335,13 @@ function fetch_blob_async_transaction(statement, id, column, row, meta, table) {
                             }
                             if (ret.buffer) {
                                 const blr = new serialize_1.BlrReader(ret.buffer);
-                                const data = blr.readSegment();
-                                infoValue.value += data.toString(const_1.default.DEFAULT_ENCODING);
+                                chunks.push(blr.readSegment());
                             }
                             if (ret.handle !== 2) {
                                 read();
                                 return;
                             }
+                            infoValue.value = Xsql.decodeConnectionText(statement.connection.options, Buffer.concat(chunks));
                             statement.connection.closeBlob(blob);
                             if (singleTransaction) {
                                 transaction.commit((err) => {

package/lib/wire/database.d.ts

@@ -52,6 +52,15 @@ declare class Database extends Events.EventEmitter {
      * blobAsText and jsonAsObject all apply.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    /**
+     * Bulk-insert Writable (the COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows, they are flushed in chunks through the batch
+     * API on one prepared statement. Runs its own transaction — committed
+     * on finish, rolled back on error/destroy (all-or-nothing for the
+     * whole stream). BLOB columns accept Buffers/strings. After 'finish',
+     * stream.recordCount / stream.affectedRows carry the totals.
+     */
+    batchStream(query: string, options?: any): import("node:stream").Writable;
     query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): this;
     drop(callback?: SimpleCallback): void;
     /**

package/lib/wire/database.js

@@ -11,6 +11,7 @@ const xsqlvar_1 = require("./xsqlvar");
 const eventConnection_1 = __importDefault(require("./eventConnection"));
 const fbEventManager_1 = __importDefault(require("./fbEventManager"));
 const query_stream_1 = __importDefault(require("./query-stream"));
+const batch_stream_1 = __importDefault(require("./batch-stream"));
 /***************************************
  *
  *   Database
@@ -241,12 +242,7 @@ class Database extends events_1.default.EventEmitter {
                 }
                 if (!result.success) {
                     transaction.rollback(function () {
-                        var first = result.errors.length ? result.errors[0] : null;
-                        var batchError = first
-                            ? first.error
-                            : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
-                        batchError.batchCompletion = result;
-                        (0, callback_1.doError)(batchError, callback);
+                        (0, callback_1.doError)((0, utils_1.batchResultToError)(result), callback);
                     });
                     return;
                 }
@@ -347,6 +343,17 @@ class Database extends events_1.default.EventEmitter {
     queryStream(query, params, options) {
         return (0, query_stream_1.default)(this, query, params, options);
     }
+    /**
+     * Bulk-insert Writable (the COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows, they are flushed in chunks through the batch
+     * API on one prepared statement. Runs its own transaction — committed
+     * on finish, rolled back on error/destroy (all-or-nothing for the
+     * whole stream). BLOB columns accept Buffers/strings. After 'finish',
+     * stream.recordCount / stream.affectedRows carry the totals.
+     */
+    batchStream(query, options) {
+        return (0, batch_stream_1.default)(this, query, options, true);
+    }
     query(query, params, callback, options = {}) {
         if (params instanceof Function) {
             options = callback || {};

package/lib/wire/serialize.d.ts

@@ -48,6 +48,8 @@ export declare class XdrWriter {
     addDecFloat34(value: number | string | bigint): void;
     addUInt(value: number): void;
     addString(s: string, encoding: BufferEncoding): void;
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b: Buffer): void;
     addText(s: string, encoding: BufferEncoding): void;
     addParamBuffer(b: Buffer): void;
     addBlr(blr: BlrWriter): void;

package/lib/wire/serialize.js

@@ -277,6 +277,16 @@ class XdrWriter {
         this.buffer.fill(0, this.pos + len, this.pos + alen);
         this.pos += alen;
     }
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b) {
+        var alen = align(b.length);
+        this.ensure(alen + 4);
+        this.buffer.writeInt32BE(b.length, this.pos);
+        this.pos += 4;
+        b.copy(this.buffer, this.pos);
+        this.buffer.fill(0, this.pos + b.length, this.pos + alen);
+        this.pos += alen;
+    }
     addText(s, encoding) {
         var len = Buffer.byteLength(s, encoding);
         var alen = align(len);

package/lib/wire/socket.js

@@ -132,8 +132,14 @@ class Socket {
      * Compress and/or encrypt data before sending to socket.
      */
     write(data, defer = false) {
+        // Callers pass views of the connection's shared _msg buffer, and both
+        // net.Socket (when it cannot flush immediately) and zlib keep a
+        // REFERENCE to the chunk — a later sender rebuilding _msg would then
+        // corrupt this queued packet (intermittent, load-dependent). Own the
+        // bytes at the send boundary, once.
+        data = Buffer.from(data);
         if (process.env.FIREBIRD_DEBUG) {
-            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, Buffer.from(data).toString('hex'), this.encrypt, defer);
+            console.log('[fb-debug] socket.write: length=%d bytes=%s encrypt=%s defer=%s', data.length, data.toString('hex'), this.encrypt, defer);
         }
         if (defer) {
             // Accumulate deferred packets instead of overwriting.  Multiple
@@ -142,8 +148,8 @@ class Socket {
             // overwriting the buffer silently drops packets and desynchronises
             // the request/response queue, causing the connection to hang.
             this.buffer = this.buffer
-                ? Buffer.concat([this.buffer, Buffer.from(data)])
-                : Buffer.from(data);
+                ? Buffer.concat([this.buffer, data])
+                : data;
             return;
         }
         if (!defer && this.buffer) {

package/lib/wire/transaction.d.ts

@@ -48,6 +48,12 @@ declare class Transaction {
      * stream ends — commit or roll back yourself.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): import("node:stream").Readable;
+    /**
+     * Bulk-insert Writable running inside this transaction (see
+     * Database.batchStream). The transaction is NOT committed or rolled
+     * back by the stream — settle it yourself after 'finish'/'error'.
+     */
+    batchStream(query: string, options?: any): import("node:stream").Writable;
     query(query: string, params?: QueryParams | Callback, callback?: any, options?: InternalQueryOptions): void;
     /**
      * Execute `query` once per row in `rows` using the Firebird 4 batch API