node-firebird 2.12.0 → 2.14.0

package/src/pool-cluster.ts

@@ -0,0 +1,319 @@
+/***************************************
+ *
+ *   PoolCluster — multi-host pooling (primaries/replicas, failover)
+ *
+ *   The mysql2 PoolCluster model on top of this driver's Pool: named
+ *   nodes, each backed by a regular connection pool (health checks,
+ *   recycling and metrics included), selected by glob pattern +
+ *   selector. Consecutive connection failures take a node offline
+ *   (with optional timed restoration), and get() fails over to the
+ *   next matching online node.
+ *
+ ***************************************/
+
+import Events from 'events';
+import { fromCallback, withPooledConnection } from './callback';
+import type { Callback } from './callback';
+import { parseConnectionString } from './uri';
+import Pool from './pool';
+
+type AttachFn = (options: any, callback: Callback) => void;
+
+export type ClusterSelector = 'rr' | 'random' | 'order';
+
+export interface PoolClusterOptions {
+    /** Options shared by every node (user, password, database, …). */
+    defaults?: any;
+    /** name → per-node option overrides (host, port, …). */
+    nodes?: Record<string, any>;
+    /** Per-node pool size (default 4). */
+    max?: number;
+    /** Default selector for get()/of() (default 'rr'). */
+    selector?: ClusterSelector;
+    /**
+     * Consecutive connection failures after which a node goes offline
+     * (default 5; 0 disables offlining).
+     */
+    removeNodeErrorCount?: number;
+    /**
+     * Milliseconds after which an offline node is restored and probed
+     * again (default 30000; 0 = stay offline until restore()/remove()).
+     */
+    restoreNodeTimeout?: number;
+}
+
+interface ClusterNode {
+    name: string;
+    options: any;
+    pool: Pool;
+    online: boolean;
+    errorCount: number;
+    restoreTimer: NodeJS.Timeout | null;
+}
+
+function patternToRegExp(pattern: string): RegExp {
+    const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp('^' + escaped + '$');
+}
+
+/**
+ * Events: 'online' (name) — node restored; 'offline' (name) — node taken
+ * out of rotation after too many connection failures; 'remove' (name) —
+ * node removed via remove().
+ */
+class PoolCluster extends Events.EventEmitter {
+    private attach: AttachFn;
+    private nodes = new Map<string, ClusterNode>();
+    private rrIndex = new Map<string, number>();
+    private max: number;
+    private defaults: any;
+    private selector: ClusterSelector;
+    private removeNodeErrorCount: number;
+    private restoreNodeTimeout: number;
+    private _destroyed = false;
+
+    constructor(attach: AttachFn, options?: PoolClusterOptions) {
+        super();
+        options = options || {};
+        this.attach = attach;
+        this.defaults = options.defaults || {};
+        this.max = options.max && options.max > 0 ? options.max : 4;
+        this.selector = options.selector || 'rr';
+        this.removeNodeErrorCount = options.removeNodeErrorCount !== undefined ? options.removeNodeErrorCount : 5;
+        this.restoreNodeTimeout = options.restoreNodeTimeout !== undefined ? options.restoreNodeTimeout : 30000;
+
+        for (const [name, overrides] of Object.entries(options.nodes || {})) {
+            this.add(name, overrides);
+        }
+    }
+
+    /** Register a node; its pool is created lazily-safe right away. */
+    add(name: string, overrides?: any): this {
+        if (this._destroyed) {
+            throw new Error('PoolCluster has been destroyed');
+        }
+        if (this.nodes.has(name)) {
+            throw new Error('PoolCluster node already exists: ' + name);
+        }
+        // a connection-string override must be parsed, not object-spread
+        // into character-indexed garbage
+        if (typeof overrides === 'string') {
+            overrides = parseConnectionString(overrides);
+        }
+        const nodeOptions = { ...this.defaults, ...(overrides || {}) };
+        this.nodes.set(name, {
+            name,
+            options: nodeOptions,
+            pool: new Pool(this.attach, nodeOptions.max || this.max, { ...nodeOptions, isPool: true }),
+            online: true,
+            errorCount: 0,
+            restoreTimer: null,
+        });
+        return this;
+    }
+
+    /** Remove a node for good, destroying its pool. */
+    remove(name: string, callback?: (err?: any) => void): void {
+        const node = this.nodes.get(name);
+        if (!node) {
+            if (callback) callback();
+            return;
+        }
+        this.nodes.delete(name);
+        if (node.restoreTimer) {
+            clearTimeout(node.restoreTimer);
+        }
+        this.emit('remove', name);
+        node.pool.destroy(callback);
+    }
+
+    /** Bring an offline node back into rotation immediately. */
+    restore(name: string): void {
+        const node = this.nodes.get(name);
+        if (!node || node.online) {
+            return;
+        }
+        if (node.restoreTimer) {
+            clearTimeout(node.restoreTimer);
+            node.restoreTimer = null;
+        }
+        node.online = true;
+        node.errorCount = 0;
+        this.emit('online', name);
+    }
+
+    /** name → { online, errorCount, pool metrics } for every node. */
+    status(): Record<string, any> {
+        const out: Record<string, any> = {};
+        for (const node of this.nodes.values()) {
+            out[node.name] = {
+                online: node.online,
+                errorCount: node.errorCount,
+                totalCount: node.pool.totalCount,
+                idleCount: node.pool.idleCount,
+                activeCount: node.pool.activeCount,
+                waitingCount: node.pool.waitingCount,
+            };
+        }
+        return out;
+    }
+
+    private matching(pattern: string): ClusterNode[] {
+        const re = patternToRegExp(pattern);
+        const out: ClusterNode[] = [];
+        for (const node of this.nodes.values()) {
+            if (re.test(node.name)) {
+                out.push(node);
+            }
+        }
+        return out;
+    }
+
+    private pick(pattern: string, selector: ClusterSelector, exclude: Set<string>): ClusterNode | null {
+        const candidates = this.matching(pattern).filter((n) => n.online && !exclude.has(n.name));
+        if (!candidates.length) {
+            return null;
+        }
+        if (selector === 'random') {
+            return candidates[Math.floor(Math.random() * candidates.length)];
+        }
+        if (selector === 'order') {
+            return candidates[0];
+        }
+        // round-robin per pattern; only the FIRST pick of a get() advances
+        // the counter — failover re-picks reuse it, or a run of failovers
+        // would skew the distribution toward nodes after the failing ones
+        const index = this.rrIndex.get(pattern) || 0;
+        if (exclude.size === 0) {
+            this.rrIndex.set(pattern, index + 1);
+        }
+        return candidates[index % candidates.length];
+    }
+
+    private noteFailure(node: ClusterNode): void {
+        // a node removed while a get was in flight must not accumulate
+        // counters, emit 'offline', or arm a restore timer nobody clears
+        if (!this.nodes.has(node.name)) {
+            return;
+        }
+        node.errorCount++;
+        if (!this.removeNodeErrorCount || node.errorCount < this.removeNodeErrorCount || !node.online) {
+            return;
+        }
+        node.online = false;
+        this.emit('offline', node.name);
+        if (this.restoreNodeTimeout > 0) {
+            node.restoreTimer = setTimeout(() => {
+                node.restoreTimer = null;
+                this.restore(node.name);
+            }, this.restoreNodeTimeout);
+            if (node.restoreTimer.unref) {
+                node.restoreTimer.unref();
+            }
+        }
+    }
+
+    /**
+     * Acquire a connection from a node matching `pattern` (default '*').
+     * Connection failures mark the node and FAIL OVER to the next
+     * matching online node; only when every candidate has failed does the
+     * callback receive the last error. Release connections with
+     * db.detach(), exactly like a plain pool.
+     */
+    get(pattern: string | Callback, selector?: ClusterSelector | Callback, callback?: Callback): void {
+        if (typeof pattern === 'function') {
+            callback = pattern;
+            pattern = '*';
+        }
+        if (typeof selector === 'function') {
+            callback = selector;
+            selector = undefined;
+        }
+        if (this._destroyed) {
+            callback!(new Error('PoolCluster has been destroyed'), null);
+            return;
+        }
+
+        const sel = (selector as ClusterSelector) || this.selector;
+        const tried = new Set<string>();
+        const self = this;
+
+        const attempt = (lastError?: any) => {
+            const node = self.pick(pattern as string, sel, tried);
+            if (!node) {
+                callback!(lastError || new Error('PoolCluster: no online node matches pattern "' + pattern + '"'), null);
+                return;
+            }
+            tried.add(node.name);
+            node.pool.get((err: any, db: any) => {
+                if (err) {
+                    self.noteFailure(node);
+                    attempt(err);
+                    return;
+                }
+                node.errorCount = 0;
+                callback!(null, db);
+            });
+        };
+        attempt();
+    }
+
+    getAsync(pattern?: string, selector?: ClusterSelector): Promise<any> {
+        const self = this;
+        return fromCallback((cb) => self.get(pattern || '*', selector, cb));
+    }
+
+    /**
+     * A pool-like facade bound to a pattern (mysql2's cluster.of):
+     * { get, getAsync, withConnection } routed through the cluster's
+     * selection and failover.
+     */
+    of(pattern: string, selector?: ClusterSelector) {
+        const self = this;
+        return {
+            get(callback: Callback) {
+                self.get(pattern, selector, callback);
+            },
+            getAsync() {
+                return self.getAsync(pattern, selector);
+            },
+            withConnection<T>(work: (db: any) => Promise<T> | T): Promise<T> {
+                return self.withConnection(pattern, work, selector);
+            },
+        };
+    }
+
+    /** Run `work` with a connection from a matching node, always released. */
+    withConnection<T>(pattern: string, work: (db: any) => Promise<T> | T, selector?: ClusterSelector): Promise<T> {
+        return withPooledConnection(() => this.getAsync(pattern, selector), work);
+    }
+
+    /** Destroy every node's pool. */
+    destroy(callback?: (err?: any) => void): void {
+        this._destroyed = true;
+        const nodes = [...this.nodes.values()];
+        this.nodes.clear();
+        let remaining = nodes.length;
+        if (!remaining) {
+            if (callback) callback();
+            return;
+        }
+        let firstError: any = null;
+        for (const node of nodes) {
+            if (node.restoreTimer) {
+                clearTimeout(node.restoreTimer);
+            }
+            node.pool.destroy((err?: any) => {
+                if (err && !firstError) firstError = err;
+                if (--remaining === 0 && callback) callback(firstError);
+            });
+        }
+    }
+
+    destroyAsync(): Promise<void> {
+        const self = this;
+        return fromCallback((cb) => self.destroy(cb));
+    }
+}
+
+export default PoolCluster;

package/src/pool.ts

@@ -5,7 +5,7 @@
  ***************************************/
 
 import Events from 'events';
-import { fromCallback } from './callback';
+import { fromCallback, withPooledConnection } from './callback';
 import type { Callback } from './callback';
 
 type AttachFn = (options: any, callback: Callback) => void;
@@ -385,15 +385,8 @@ class Pool extends Events.EventEmitter {
      * Run `work` with a connection from the pool, returning it to the pool
      * (detach) when the returned promise settles — success or failure.
      */
-    async withConnection<T>(work: (db: any) => Promise<T> | T): Promise<T> {
-        const db = await this.getAsync();
-        try {
-            return await work(db);
-        } finally {
-            // A pooled detach only returns the connection to the pool; do not
-            // let a detach hiccup mask the outcome of `work`.
-            await new Promise<void>(function(resolve) { db.detach(function() { resolve(); }); });
-        }
+    withConnection<T>(work: (db: any) => Promise<T> | T): Promise<T> {
+        return withPooledConnection(() => this.getAsync(), work);
     }
 }
 

package/src/types.ts

@@ -5,7 +5,7 @@
 // They now live in the TypeScript source tree and are compiled into the
 // published declaration files.
 
-import type { Readable } from 'stream';
+import type { Readable, Writable } from 'stream';
 import type { SqlTag } from './sql-template';
 
 export type { SqlTag, SqlQuery, SqlIdentifier, CompiledQuery } from './sql-template';
@@ -211,6 +211,22 @@ export interface QueryResult<T = any> {
     warnings: ServerWarning[];
 }
 
+/** Options for batchStream: the executeBatch options plus stream tuning. */
+export type BatchStreamOptions = BatchOptions & {
+    /** Rows buffered per executeBatch flush (default 1000). */
+    flushRows?: number;
+    /** Writable highWaterMark in rows (default: flushRows). */
+    highWaterMark?: number;
+};
+
+/** The Writable returned by batchStream, with totals valid after 'finish'. */
+export interface BatchStream extends Writable {
+    /** Records the server processed so far. */
+    recordCount: number;
+    /** Sum of per-record update counts so far. */
+    affectedRows: number;
+}
+
 export type QueryStreamOptions = QueryOptions & {
     /**
      * Rows buffered internally before fetching pauses (object-mode
@@ -232,8 +248,8 @@ export interface Database {
     detach(callback?: SimpleCallback): Database;
     transaction(options: TransactionOptions|Isolation|TransactionCallback, callback?: TransactionCallback): Database;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
-    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
-    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
+    query<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): Database;
+    execute<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): Database;
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
@@ -244,6 +260,13 @@ export interface Database {
      * fetch and releases the statement.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
+    /**
+     * Bulk-insert Writable (COPY FROM analogue, Firebird 4.0+): write
+     * parameter-array rows; they are flushed in chunks through the batch
+     * API. Runs its own transaction — committed on finish, rolled back on
+     * error/destroy. BLOB columns accept Buffers/strings.
+     */
+    batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -290,8 +313,8 @@ export interface Transaction {
      */
     savepoint<T>(work: (transaction: Transaction) => Promise<T> | T): Promise<T>;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
-    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
-    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
+    query<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): void;
+    execute<T = any>(query: string, params: QueryParams, callback: (err: any, result: T[], meta?: any[], isSelect?: boolean) => void, options?: QueryOptions): void;
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
@@ -301,6 +324,11 @@ export interface Transaction {
      * transaction is NOT committed when the stream ends.
      */
     queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
+    /**
+     * Bulk-insert Writable inside this transaction (see
+     * Database.batchStream); commit/rollback stays with the caller.
+     */
+    batchStream(query: string, options?: BatchStreamOptions): BatchStream;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
@@ -416,6 +444,13 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Default character set of a NEWLY CREATED database (create /
+     * attachOrCreate only). Falls back to the connection `encoding`, then
+     * UTF8 — pass e.g. `defaultCharset: 'UTF8'` to keep a modern database
+     * default while connecting with a legacy codepage `encoding`.
+     */
+    defaultCharset?: string;
     /**
      * Qualify object-row keys by source table (same option as mysql2), so
      * JOINed columns with the same name stop overwriting each other:

package/src/utils.ts

@@ -108,6 +108,21 @@ export const parseDate = (str: string): Date => {
 /**
  * Get Error Message per gdscode
  */
+/**
+ * Turn a failed executeBatch completion into the all-or-nothing error
+ * shape shared by database.executeBatch and batchStream: the first
+ * record's own error (or a synthesized summary), with the full
+ * completion attached as err.batchCompletion.
+ */
+export const batchResultToError = (result: { errors: { error: any }[]; errorRecordNumbers: number[] }): any => {
+    const first = result.errors.length ? result.errors[0] : null;
+    const err: any = first
+        ? first.error
+        : new Error('Batch failed for record(s) ' + result.errorRecordNumbers.join(', '));
+    err.batchCompletion = result;
+    return err;
+};
+
 export const lookupMessages = (status: FbStatusItem[]): string => {
     const messages = status.map((item) => {
         let text = MessagesError[item.gdscode];
@@ -143,7 +158,10 @@ export const escape = function(value: any, protocolVersion?: number): string {
         case 'number':
             return value.toString();
         case 'string':
-            return "'" + value.replace(/'/g, "''").replace(/\\/g, '\\\\') + "'";
+            // Firebird string literals have NO backslash escapes — only the
+            // quote is doubled. Doubling backslashes corrupted the data
+            // (issue #156: '\' arrived as '\\').
+            return "'" + value.replace(/'/g, "''") + "'";
     }
 
     if (value instanceof Date)

package/src/wire/batch-stream.ts

@@ -0,0 +1,121 @@
+/***************************************
+ *
+ *   batchStream — object-mode Writable over the Firebird 4 batch API
+ *
+ *   The COPY FROM analogue: write parameter rows, they are flushed in
+ *   chunks through statement.executeBatch (single prepared statement,
+ *   protocol-level batching, BLOB values included). Backpressure is the
+ *   Writable machinery itself: a write callback is held while a chunk
+ *   is in flight.
+ *
+ ***************************************/
+
+import { Writable } from 'stream';
+import { fromCallback } from '../callback';
+import { batchResultToError } from '../utils';
+
+/**
+ * Build the Writable for Database.batchStream / Transaction.batchStream.
+ * With `ownsTransaction` (the Database form) the stream runs its own
+ * transaction: committed on finish, rolled back on error/destroy —
+ * all-or-nothing for the whole stream. The Transaction form leaves
+ * commit/rollback to the caller.
+ *
+ * Rows accumulate up to options.flushRows (default 1000) per
+ * executeBatch flush; the remaining executeBatch options (chunkSize,
+ * bufferSize, …) pass through. After 'finish', stream.recordCount and
+ * stream.affectedRows carry the totals.
+ */
+function makeBatchStream(target: any, query: string, options: any, ownsTransaction: boolean): Writable {
+    options = options || {};
+    const flushRows = options.flushRows > 0 ? Math.floor(options.flushRows) : 1000;
+
+    const batchOptions = { ...options };
+    delete batchOptions.flushRows;
+    delete batchOptions.highWaterMark;
+
+    let transaction: any = null;
+    let statement: any = null;
+    let buffered: any[][] = [];
+
+    const init = async () => {
+        if (statement) {
+            return;
+        }
+        transaction = ownsTransaction ? await target.transactionAsync() : target;
+        statement = await fromCallback((cb) => transaction.newStatement(query, cb));
+    };
+
+    const flush = async () => {
+        if (!buffered.length) {
+            return;
+        }
+        await init();
+        const chunk = buffered;
+        buffered = [];
+        const result: any = await fromCallback((cb) =>
+            statement.executeBatch(transaction, chunk, cb, batchOptions));
+        if (!result.success) {
+            // the same all-or-nothing error shape database.executeBatch uses
+            throw batchResultToError(result);
+        }
+        (stream as any).recordCount += result.recordCount;
+        for (const count of result.updateCounts) {
+            (stream as any).affectedRows += count;
+        }
+    };
+
+    const cleanup = async (commit: boolean) => {
+        if (statement) {
+            const stmt = statement;
+            statement = null;
+            await new Promise<void>((resolve) => stmt.release(() => resolve()));
+        }
+        if (ownsTransaction && transaction) {
+            const tx = transaction;
+            transaction = null;
+            await (commit ? tx.commitAsync() : tx.rollbackAsync());
+        }
+    };
+
+    const stream = new Writable({
+        objectMode: true,
+        highWaterMark: options.highWaterMark > 0 ? options.highWaterMark : flushRows,
+
+        write(row: any, _enc: any, cb: (err?: any) => void) {
+            if (!Array.isArray(row)) {
+                cb(new Error('batchStream expects parameter-array rows'));
+                return;
+            }
+            buffered.push(row);
+            if (buffered.length >= flushRows) {
+                flush().then(() => cb(), cb);
+            } else {
+                cb();
+            }
+        },
+
+        final(cb: (err?: any) => void) {
+            // an empty stream finishes without touching the server at all
+            // (flush() early-returns and init never runs)
+            flush()
+                .then(() => cleanup(true))
+                .then(() => cb(), (err) => {
+                    // the failed stream must not commit half a bulk load
+                    cleanup(false).catch(() => { /* rollback best-effort */ });
+                    cb(err);
+                });
+        },
+
+        destroy(err: any, cb: (err?: any) => void) {
+            cleanup(false)
+                .then(() => cb(err), () => cb(err));
+        },
+    });
+
+    (stream as any).recordCount = 0;
+    (stream as any).affectedRows = 0;
+    return stream;
+}
+
+export = makeBatchStream;