node-firebird 2.12.0 → 2.13.0

package/src/wire/connection.ts

@@ -8,6 +8,7 @@ import * as srp from '../srp';
 import * as crypt from '../unix-crypt';
 import Const from './const';
 import * as Xsql from './xsqlvar';
+import { charsetWidthById } from './codepages';
 import ServiceManager from './service';
 import Database from './database';
 import Statement from './statement';
@@ -78,6 +79,21 @@ function statementCacheLimit(options: InternalOptions): number {
 // 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: InternalOptions, value: string) {
+    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
@@ -263,6 +279,25 @@ class Connection {
     }
 
 
+    /**
+     * 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: any) {
+        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: string, port: number, callback: SimpleCallback | undefined) {
 
         var self = this;
@@ -287,6 +322,15 @@ class Connection {
 
             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
@@ -297,14 +341,14 @@ class Connection {
                     ctx.connect(self.options, function(err: any) {
 
                         if (err) {
-                            self.db.emit('error', err);
+                            self._emitError(err);
                             return;
                         }
 
                         ctx.attach(self.options, function(err: any) {
 
                             if (err) {
-                                self.db.emit('error', err);
+                                self._emitError(err);
                                 return;
                             }
 
@@ -321,11 +365,13 @@ class Connection {
         });
     
         self._socket.on('error', function(e: any) {
-    
+
             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);
@@ -767,7 +813,9 @@ class Connection {
         blr.pos = 0;
     
         blr.addByte(Const.isc_dpb_version1);
-        blr.addString(Const.isc_dpb_lc_ctype, options.encoding || 'UTF8', Const.DEFAULT_ENCODING);
+        // charset names are sent verbatim — normalize case so encoding:
+        // 'utf8'/'win1251' (e.g. from URI query params) is accepted
+        blr.addString(Const.isc_dpb_lc_ctype, String(options.encoding || 'UTF8').toUpperCase(), Const.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.PROTOCOL_VERSION13) {
@@ -895,8 +943,15 @@ class Connection {
     
         blr.pos = 0;
         blr.addByte(Const.isc_dpb_version1);
-        blr.addString(Const.isc_dpb_set_db_charset, 'UTF8', Const.DEFAULT_ENCODING);
-        blr.addString(Const.isc_dpb_lc_ctype, 'UTF8', Const.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.isc_dpb_set_db_charset,
+            String(options.defaultCharset || options.encoding || 'UTF8').toUpperCase(), Const.DEFAULT_ENCODING);
+        blr.addString(Const.isc_dpb_lc_ctype,
+            String(options.encoding || 'UTF8').toUpperCase(), Const.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.PROTOCOL_VERSION13) {
@@ -1004,7 +1059,9 @@ class Connection {
 
     throwClosed(callback: ((err: Error, ...args: any[]) => void) | undefined) {
         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;
@@ -1254,7 +1311,9 @@ class Connection {
         msg.addInt(transaction.handle);
         msg.addInt(0xFFFF);
         msg.addInt(3); // dialect = 3
-        msg.addString(query, Const.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.PROTOCOL_VERSION20) {
@@ -1316,7 +1375,9 @@ class Connection {
         msg.addInt(transaction.handle);
         msg.addInt(statement.handle);
         msg.addInt(3); // dialect = 3
-        msg.addString(query, Const.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.PROTOCOL_VERSION20) {
@@ -1348,10 +1409,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: Transaction, statement: Statement, rows: QueryParams[], callback: BatchCb | undefined, options?: BatchOptions) {
         options = options || {};
@@ -1389,6 +1453,90 @@ class Connection {
             }
         }
 
+        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: number[] = [];
+        for (var bj = 0; bj < input.length; bj++) {
+            var bt = input[bj].type;
+            if (bt === Const.SQL_BLOB || bt === Const.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] as any[])[blobCols[ci]];
+                    if (bv !== null && bv !== undefined) {
+                        needsBlobPass = true;
+                        break outer;
+                    }
+                }
+            }
+        }
+
+        if (needsBlobPass) {
+            var cloned: any[][] = rows.map(function(r) { return (r as any[]).slice(); });
+            var pendingBlobs = 1; // sentinel so zero uploads still settle
+            var blobFailure: any = null;
+            var settleBlobs = function(err?: any) {
+                if (err && !blobFailure) {
+                    blobFailure = err;
+                }
+                if (--pendingBlobs) {
+                    return;
+                }
+                if (blobFailure) {
+                    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: any, oid: any) {
+                        if (!err) {
+                            row[j] = oid;
+                        }
+                        settleBlobs(err);
+                    });
+                });
+            });
+            settleBlobs();
+            return;
+        }
+
+        this._executeBatchEncoded(transaction, statement, rows as any[][], callback, options);
+    }
+
+
+    /** Encode and send the batch packets (rows are fully materialized:
+     *  blob values already replaced by quad ids by executeBatch). */
+    _executeBatchEncoded(transaction: Transaction, statement: Statement, rows: any[][], callback: BatchCb | undefined, options: BatchOptions) {
+        var input = statement.input;
         var built;
         try {
             built = buildBatchEncoders(input, Object.assign({}, this.options, options));
@@ -1584,9 +1732,9 @@ class Connection {
                     if (Buffer.isBuffer(value))
                         b = value;
                     else if (typeof(value) === 'string')
-                        b = Buffer.from(value, Const.DEFAULT_ENCODING);
+                        b = Xsql.encodeConnectionText(self.options, value);
                     else if (!isStream)
-                        b = Buffer.from(JSON.stringify(value), Const.DEFAULT_ENCODING);
+                        b = Xsql.encodeConnectionText(self.options, JSON.stringify(value));
     
                     // Use configured transfer size or default to 1024
                     var chunkSize = self.options.blobChunkSize || 1024;
@@ -1737,14 +1885,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.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;
                                 }
                             }
@@ -2005,6 +2157,37 @@ class Connection {
     }
 
 
+    /**
+     * 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: Transaction, ret: any, callback: (err?: any) => void) {
+        const self = this;
+        const fns = (ret && ret.arrBlob) || [];
+        if (!fns.length) {
+            return callback();
+        }
+        const read = (index: number) => {
+            if (index >= fns.length) {
+                return callback();
+            }
+            fns[index](transaction).then((blob: any) => {
+                // 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: Statement, transaction: Transaction, callback: Callback<any[]>) {
         const self = this;
         const custom = statement.options || {};
@@ -2018,29 +2201,10 @@ class Connection {
             }
 
             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: any, results: any) => {
-                    if (index >= arrBlobFns.length) {
-                        return Promise.resolve(results);
-                    }
-                    return arrBlobFns[index](transaction).then((v: any) => {
-                        results.push(v);
-                        return readBlobsSequentially(index + 1, results);
-                    });
-                };
-
-                readBlobsSequentially(0, []).then((arrBlob: any) => {
-                    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?: any) => {
+                    if (blobErr) {
+                        callback(blobErr);
+                        return;
                     }
 
                     doSynchronousLoop(ret.data, (row, _i, next) => {
@@ -2062,7 +2226,7 @@ class Connection {
                             self.fetch(statement, transaction, Const.DEFAULT_FETCHSIZE, loop);
                         }
                     });
-                }).catch(callback);
+                });
                 return;
             }
 
@@ -2134,6 +2298,48 @@ class Connection {
     }
 
 
+    /**
+     * 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: Transaction, value: any, callback: (err: any, oid?: any) => void) {
+        var self = this;
+        var b: Buffer;
+        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: any, blob: any) {
+            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: any = null;
+            bufferReader(b, chunkSize, function(part, next) {
+                self.batchSegments(blob, part, function(segErr: any) {
+                    if (segErr && !segmentError) {
+                        segmentError = segErr;
+                    }
+                    next();
+                } as any);
+            }, function() {
+                self.closeBlob(blob, function(closeErr: any) {
+                    callback(segmentError || closeErr, blob.oid);
+                } as any, false);
+            });
+        });
+    }
+
+
     svcattach(options: InternalOptions, callback?: Callback<ServiceManager>, svc?: ServiceManager) {
         this._lowercase_keys = options.lowercase_keys || Const.DEFAULT_LOWERCASE_KEYS;
         var database = options.database || options.filename;
@@ -3288,6 +3494,43 @@ function describe(buff: Buffer, statement: 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: any[], options: any) {
+    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.SQL_TEXT && p.type !== Const.SQL_VARYING)) continue;
+        // OCTETS (id 1) is binary and never transliterated
+        if (p.charSetId === undefined || p.charSetId === 1) continue;
+        const colWidth = 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);
+    }
 }
 
 /**
@@ -3313,7 +3556,7 @@ function buildBatchEncoders(input: any[], options: any) {
         return String(v);
     };
     var toBytes = function(v: any, meta: any, column: number): Buffer {
-        var b = Buffer.isBuffer(v) ? v : Buffer.from(toText(v), Const.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 || '?') + ')');
@@ -3451,6 +3694,24 @@ function buildBatchEncoders(input: any[], options: any) {
                 align(4); offset += 4;
                 break;
 
+            case Const.SQL_BLOB:
+            case Const.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: any, v: any) {
+                        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 + ')');
@@ -3508,12 +3769,16 @@ function CalcBlr(blr: BlrWriter, xsqlda: any[]) {
 
 function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase, table?: string) {
     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: Buffer[] = [];
 
     return (transactionArg: any) => {
         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.DEFAULT_ENCODING) : '';
+            infoValue.value = data ? Xsql.decodeConnectionText(statement.connection.options, data) : '';
             return Promise.resolve(infoValue);
         }
 
@@ -3557,8 +3822,7 @@ function fetch_blob_async_transaction(statement: Statement, id: Quad, column: st
 
                             if (ret.buffer) {
                                 const blr = new BlrReader(ret.buffer);
-                                const data = blr.readSegment();
-                                infoValue.value += data.toString(Const.DEFAULT_ENCODING);
+                                chunks.push(blr.readSegment());
                             }
 
                             if (ret.handle !== 2) {
@@ -3566,6 +3830,8 @@ function fetch_blob_async_transaction(statement: Statement, id: Quad, column: st
                                 return;
                             }
 
+                            infoValue.value = Xsql.decodeConnectionText(
+                                statement.connection.options, Buffer.concat(chunks));
                             statement.connection.closeBlob(blob);
                             if (singleTransaction) {
                                 transaction.commit((err: any) => {

package/src/wire/database.ts

@@ -1,12 +1,13 @@
 import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
-import { escape } from '../utils';
+import { batchResultToError, escape } from '../utils';
 import Const from './const';
 import { makeSqlTag, type SqlTag } from '../sql-template';
 import { computeColumnKeys, nestCell, resolveKeyTransform, resolveNestTables } from './xsqlvar';
 import EventConnection from './eventConnection';
 import FbEventManager from './fbEventManager';
 import makeQueryStream from './query-stream';
+import makeBatchStream from './batch-stream';
 import type Connection from './connection';
 import type Transaction from './transaction';
 import type Statement from './statement';
@@ -300,12 +301,7 @@ class Database extends Events.EventEmitter {
 
                 if (!result.success) {
                     transaction.rollback(function() {
-                        var first = result.errors.length ? result.errors[0] : null;
-                        var batchError: any = first
-                            ? first.error
-                            : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
-                        batchError.batchCompletion = result;
-                        doError(batchError, callback);
+                        doError(batchResultToError(result), callback);
                     });
                     return;
                 }
@@ -415,6 +411,18 @@ class Database extends Events.EventEmitter {
         return makeQueryStream(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: string, options?: any) {
+        return makeBatchStream(this, query, options, true);
+    }
+
     query(query: string, params?: QueryParams | Callback, callback?: any, options: InternalQueryOptions = {}): this {
         if (params instanceof Function) {
             options = callback || {};

package/src/wire/serialize.ts

@@ -346,6 +346,17 @@ export class XdrWriter {
         this.pos += alen;
     }
 
+    /** addString for pre-encoded bytes (codepage connection charsets). */
+    addStringBuffer(b: Buffer): void {
+        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: string, encoding: BufferEncoding): void {
         var len = Buffer.byteLength(s, encoding);
         var alen = align(len);

package/src/wire/socket.ts

@@ -163,9 +163,15 @@ class Socket {
      * Compress and/or encrypt data before sending to socket.
      */
     write(data: Buffer | Uint8Array, defer = false): void {
+        // 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);
+                data.length, (data as Buffer).toString('hex'), this.encrypt, defer);
         }
         if (defer) {
             // Accumulate deferred packets instead of overwriting.  Multiple
@@ -174,8 +180,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 as Buffer);
             return;
         }