node-firebird 2.12.0 → 2.14.0

package/README.md

@@ -14,7 +14,7 @@
 - [Connection types](#connection-types) — connection options, `firebird://` URIs and traditional connection strings, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, tagged-template queries (sql), named placeholders, nested result tables (nestTables), row-key transforms (transformKeys), result metadata / affected rows (withMeta), custom type parsers (typeCast), BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
-- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
+- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts incl. BLOBs), bulk-insert stream (batchStream), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
 - [Contributing](#contributing) · [Contributors](#contributors)
@@ -39,16 +39,31 @@ and 26 against Firebird 3, 4, 5 and 6).
 
 ## Usage
 
+CommonJS and ESM are both first-class (conditional `exports`):
+
 ```js
-var Firebird = require('node-firebird');
+// CommonJS
+const Firebird = require('node-firebird');
+
+// ESM — default and named imports both work
+import Firebird from 'node-firebird';
+import { attach, pool, GDSCode, SQL_TYPES } from 'node-firebird';
 ```
 
+The documented subpaths keep working in both module systems
+(`require('node-firebird/lib/gdscodes')`, …).
+
 TypeScript is fully supported — the driver itself is written in TypeScript and
-ships its own type declarations:
+ships its own type declarations, with generics on the query APIs:
 
 ```ts
 import * as Firebird from 'node-firebird';
 import type { Options, Database } from 'node-firebird';
+
+interface Emp { ID: number; NAME: string }
+const rows = await db.queryAsync<Emp>('SELECT ID, NAME FROM EMP');  // Emp[]
+db.query<Emp>('SELECT ID, NAME FROM EMP', [], (err, rows) => { /* rows: Emp[] */ });
+const r = await db.queryAsync<Emp>('SELECT ...', [], { withMeta: true }); // QueryResult<Emp>
 ```
 
 ### Developing the driver
@@ -340,6 +355,48 @@ console.log({
   is attached, so existing applications keep working unchanged.
 - Metrics are plain getters — reading them has no side effects.
 
+#### Multi-host pooling (PoolCluster)
+
+For primary/replica topologies (Firebird 4+ logical replication) or plain
+redundancy, `Firebird.poolCluster` manages one pool per named node with
+pattern-based selection and automatic failover — the mysql2 `PoolCluster`
+model:
+
+```js
+const cluster = Firebird.poolCluster({
+  defaults: { user: 'SYSDBA', password: 'masterkey', database: '/data/app.fdb', connectTimeout: 5000 },
+  nodes: {
+    primary:  { host: 'db-primary' },
+    replica1: { host: 'db-replica-1' },
+    replica2: { host: 'db-replica-2' },
+  },
+  max: 4,                    // per-node pool size
+  selector: 'rr',            // 'rr' | 'random' | 'order' (first online match)
+  removeNodeErrorCount: 5,   // offline a node after N consecutive connection failures
+  restoreNodeTimeout: 30000, // put it back into rotation after 30s (0 = manual restore())
+});
+
+// writes go to the primary, reads round-robin across replicas
+await cluster.withConnection('primary', db => db.queryAsync('UPDATE ...'));
+const rows = await cluster.withConnection('replica*', db => db.queryAsync('SELECT ...'));
+
+// or bind a pattern once (mysql2's cluster.of)
+const replicas = cluster.of('replica*', 'rr');
+const db = await replicas.getAsync();  // release with db.detach(), as with a plain pool
+```
+
+A failed connection attempt marks the node and **fails over** to the next
+matching online node; only when every candidate has failed does the call
+error (set `connectTimeout` in `defaults` so dead-but-routable hosts fail
+fast). Nodes taken offline emit `'offline'`, restorations emit
+`'online'`, and `cluster.status()` returns per-node
+`{ online, errorCount, totalCount, idleCount, activeCount, waitingCount }`
+for monitoring. Each node's pool is a regular
+[connection pool](#pool-events-and-metrics) — health checks, idle
+reaping, `maxUses`/`maxLifetimeMillis` recycling and keepalive all apply
+per node. `add(name, overrides)` / `remove(name)` manage nodes at
+runtime; `destroy()` closes everything.
+
 #### Advanced Pooling Features
 
 The pool implementation includes several safeguards for reliability:
@@ -1209,7 +1266,11 @@ Firebird.attach(options, function (err, db) {
   });
 
   db.on('error', function (err) {
-    // connection-level errors (socket errors, closed connection, etc.)
+    // connection-level errors (socket errors, closed connection, etc.).
+    // Delivered to listeners only: without one, background failures (e.g.
+    // a failed automatic reconnect) are NOT re-thrown as uncaught
+    // exceptions — the operations they affect still receive the error
+    // through their own callbacks/promises.
   });
 
   db.on('transaction', function (options) {
@@ -1506,7 +1567,27 @@ Commonly used Firebird character sets are automatically mapped to their correspo
 | `ASCII`                | `ascii`                 | 7-bit ASCII. |
 | `NONE`                 | `latin1`                | Raw/unspecified character set. Treated as binary-safe 8-bit characters. |
 
-Accented characters and fixed-length `CHAR(N)` column whitespace/truncation are handled automatically matching the connection character set width definitions.
+Beyond Node's native encodings, the driver ships **codepage codecs** for the
+single-byte charsets (decode *and* encode — columns, parameters, SQL
+literals and `blobAsText` blobs all transcode):
+
+> `WIN1250`–`WIN1258` (Central European, Cyrillic, Greek, Turkish, Hebrew,
+> Arabic, Baltic, Vietnamese), `ISO8859_2`–`ISO8859_9`, `ISO8859_13`,
+> `KOI8R`, `KOI8U`, `DOS866`
+
+```js
+const options = { /* ... */ encoding: 'WIN1251' };
+await db.queryAsync('INSERT INTO T VALUES (?)', ['Привет']); // encoded as cp1251
+```
+
+The codecs are built from Node's ICU tables at first use (present in every
+official Node build). `attachOrCreate`/`create` honour `options.encoding`
+for the new database's default charset too. Accented characters and
+fixed-length `CHAR(N)` whitespace/truncation are handled automatically per
+the charset width — and single-byte columns (including charset `NONE`) are
+readable in full under the default UTF8 connection (the declared fetch
+lengths are widened per the charset-width ratio, fixing the
+`string right truncation` errors of issue [#422](https://github.com/hgourvest/node-firebird/issues/422)).
 
 #### Custom Charset Connection Example
 ```js
@@ -1770,11 +1851,43 @@ Notes:
 - Values are encoded from the statement's own parameter metadata, so
   NUMERIC/DECIMAL scale, `BIGINT`/`INT128` (pass `BigInt`), `BOOLEAN`,
   `TIMESTAMP`/`DATE`/`TIME`, `FLOAT`/`DOUBLE` and `DECFLOAT` all round-trip
-  exactly. BLOB and ARRAY parameters are not supported in batches yet.
+  exactly.
+- `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 the blob ops pipeline on the
+  wire — and the batch messages reference their ids. `ARRAY` parameters
+  are not supported.
 - Oversized `CHAR`/`VARCHAR` values fail the batch client-side before
   anything is sent; server-side record errors (constraint violations,
   truncation…) are reported per record.
 
+### Bulk-insert stream (batchStream, Firebird 4.0+)
+
+`db.batchStream(sql, options)` is the COPY FROM analogue: an object-mode
+`Writable` that flushes parameter-array rows in chunks through one
+prepared statement using the batch API. The Database form runs its own
+transaction — **committed on finish, rolled back on error or destroy**,
+all-or-nothing for the whole stream:
+
+```js
+const { pipeline } = require('stream/promises');
+
+const stream = db.batchStream('INSERT INTO EVENTS VALUES (?, ?, ?)', {
+  flushRows: 1000, // rows buffered per batch flush (default 1000)
+});
+
+await pipeline(mySourceOfRowArrays, stream); // e.g. a CSV parser
+console.log(stream.recordCount, stream.affectedRows); // totals after 'finish'
+```
+
+Backpressure is the `Writable` machinery itself: writes pause while a
+chunk is in flight, so an arbitrarily large source never accumulates in
+memory beyond `flushRows`. BLOB columns accept Buffers/strings per the
+batch rules above. `transaction.batchStream(sql, options)` runs inside an
+existing transaction and leaves commit/rollback to you. The remaining
+options (`chunkSize`, `bufferSize`, …) pass through to
+[executeBatch](#batch-execution-firebird-40).
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js
@@ -2110,6 +2223,25 @@ app.get('/users/:id/picture', withConnection(pool, function (db, req, res, done)
 
 Answers to recurring questions from the [issue tracker](https://github.com/hgourvest/node-firebird/issues).
 
+#### Text comes back as `������` with a WIN1250/1251/1253/1257 database (issue [#319](https://github.com/hgourvest/node-firebird/issues/319))
+
+Resolved — the driver now ships codepage codecs for the single-byte
+charsets (`WIN1250`–`WIN1258`, `ISO8859_2`–`9`/`13`, `KOI8R`/`KOI8U`,
+`DOS866`): just set the matching connection encoding and both reads and
+writes transcode correctly, including parameters, SQL literals and
+`blobAsText` blobs:
+
+```js
+const options = { /* ... */ encoding: 'WIN1253' };
+```
+
+See [§ Character Set & Encoding Support](#character-set--encoding-support).
+For a charset *outside* that list (e.g. `DOS437`/`DOS850`), the
+[iconv-lite](https://www.npmjs.com/package/iconv-lite) escape hatch still
+works: connect with `encoding: 'NONE'`, read raw bytes via `latin1` in a
+[`typeCast` hook](#custom-type-parsers-typecast) and decode with the real
+codepage; write already-encoded bytes as Buffer parameters.
+
 #### Can I use aggregate functions like `LIST()`? I get "no database to handle" when I call the result.
 
 Yes — `LIST()` is plain SQL and needs no special driver support. The error happens because `LIST()` returns a text blob (subtype 1), and blob columns come back from `db.query`/`transaction.query` as **async reader functions** bound to the transaction the query ran in (see [Reading Blobs](#reading-blobs-asynchronous)). Calling that function without a transaction — or with a different one — is what throws "no database to handle".

package/lib/callback.d.ts

@@ -28,6 +28,13 @@ export declare function toError(err: any): Error;
  * Run a callback-style operation and return a Promise for its result.
  * Usage: fromCallback<Database>(cb => attach(options, cb))
  */
+/**
+ * Run `work` with a pooled connection and always return it to its pool
+ * (detach) when the promise settles — a detach hiccup never masks the
+ * outcome of `work`. Shared by Pool.withConnection and
+ * PoolCluster.withConnection so the release semantics cannot drift.
+ */
+export declare function withPooledConnection<T>(getAsync: () => Promise<any>, work: (db: any) => Promise<T> | T): Promise<T>;
 export declare function fromCallback<T = any>(executor: (cb: Callback<T>) => void): Promise<T>;
 export declare function doError(obj: any, callback?: (...args: any[]) => void): void;
 export declare function doCallback<T>(obj: T, callback?: Callback<T>): void;

package/lib/callback.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toError = toError;
+exports.withPooledConnection = withPooledConnection;
 exports.fromCallback = fromCallback;
 exports.doError = doError;
 exports.doCallback = doCallback;
@@ -23,6 +24,21 @@ function toError(err) {
  * Run a callback-style operation and return a Promise for its result.
  * Usage: fromCallback<Database>(cb => attach(options, cb))
  */
+/**
+ * Run `work` with a pooled connection and always return it to its pool
+ * (detach) when the promise settles — a detach hiccup never masks the
+ * outcome of `work`. Shared by Pool.withConnection and
+ * PoolCluster.withConnection so the release semantics cannot drift.
+ */
+async function withPooledConnection(getAsync, work) {
+    const db = await getAsync();
+    try {
+        return await work(db);
+    }
+    finally {
+        await new Promise(function (resolve) { db.detach(function () { resolve(); }); });
+    }
+}
 function fromCallback(executor) {
     return new Promise(function (resolve, reject) {
         executor(function (err, result) {

package/lib/index.d.ts

@@ -1,4 +1,6 @@
 import Connection from './wire/connection';
+import PoolCluster from './pool-cluster';
+import type { PoolClusterOptions } from './pool-cluster';
 import { escape as escapeValue } from './utils';
 import { parseConnectionUri, parseConnectionString } from './uri';
 import type { Options, SvcMgrOptions, DatabaseCallback, ServiceManagerCallback, SimpleCallback, ConnectionPool, Database, ServiceManager } from './types';
@@ -41,6 +43,14 @@ export declare function drop(options: Options | string, callback: SimpleCallback
 export declare function create(options: Options | string, callback: DatabaseCallback): void;
 export declare function attachOrCreate(options: Options | string, callback: DatabaseCallback): void;
 export declare function pool(max: number, options: Options | string): ConnectionPool;
+/**
+ * Multi-host pooling (primaries/replicas, failover): named nodes, each
+ * backed by a regular pool, selected by glob pattern + 'rr'/'random'/
+ * 'order' selector, with connection-failure failover and error-based
+ * node offlining. See README § Multi-host pooling.
+ */
+export declare function poolCluster(options?: PoolClusterOptions): PoolCluster;
+export type { PoolClusterOptions, ClusterSelector } from './pool-cluster';
 export { parseConnectionUri, parseConnectionString };
 export { parseNamedPlaceholders } from './named-params';
 export declare function attachAsync(options: SvcMgrOptions): Promise<ServiceManager>;

package/lib/index.js

@@ -23,6 +23,7 @@ exports.drop = drop;
 exports.create = create;
 exports.attachOrCreate = attachOrCreate;
 exports.pool = pool;
+exports.poolCluster = poolCluster;
 exports.attachAsync = attachAsync;
 exports.createAsync = createAsync;
 exports.attachOrCreateAsync = attachOrCreateAsync;
@@ -31,6 +32,7 @@ const const_1 = __importDefault(require("./wire/const"));
 const callback_1 = require("./callback");
 const connection_1 = __importDefault(require("./wire/connection"));
 const pool_1 = __importDefault(require("./pool"));
+const pool_cluster_1 = __importDefault(require("./pool-cluster"));
 const utils_1 = require("./utils");
 const uri_1 = require("./uri");
 Object.defineProperty(exports, "parseConnectionUri", { enumerable: true, get: function () { return uri_1.parseConnectionUri; } });
@@ -178,6 +180,17 @@ function attachOrCreate(options, callback) {
 function pool(max, options) {
     return new pool_1.default(attach, max, Object.assign({}, (0, uri_1.normalizeOptions)(options), { isPool: true }));
 }
+/**
+ * Multi-host pooling (primaries/replicas, failover): named nodes, each
+ * backed by a regular pool, selected by glob pattern + 'rr'/'random'/
+ * 'order' selector, with connection-failure failover and error-based
+ * node offlining. See README § Multi-host pooling.
+ */
+function poolCluster(options) {
+    const normalized = { ...(options || {}) };
+    normalized.defaults = (0, uri_1.normalizeOptions)(normalized.defaults || {});
+    return new pool_cluster_1.default(attach, normalized);
+}
 var named_params_1 = require("./named-params");
 Object.defineProperty(exports, "parseNamedPlaceholders", { enumerable: true, get: function () { return named_params_1.parseNamedPlaceholders; } });
 function attachAsync(options) {

package/lib/pool-cluster.d.ts

@@ -0,0 +1,89 @@
+/***************************************
+ *
+ *   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 type { Callback } from './callback';
+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;
+}
+/**
+ * Events: 'online' (name) — node restored; 'offline' (name) — node taken
+ * out of rotation after too many connection failures; 'remove' (name) —
+ * node removed via remove().
+ */
+declare class PoolCluster extends Events.EventEmitter {
+    private attach;
+    private nodes;
+    private rrIndex;
+    private max;
+    private defaults;
+    private selector;
+    private removeNodeErrorCount;
+    private restoreNodeTimeout;
+    private _destroyed;
+    constructor(attach: AttachFn, options?: PoolClusterOptions);
+    /** Register a node; its pool is created lazily-safe right away. */
+    add(name: string, overrides?: any): this;
+    /** Remove a node for good, destroying its pool. */
+    remove(name: string, callback?: (err?: any) => void): void;
+    /** Bring an offline node back into rotation immediately. */
+    restore(name: string): void;
+    /** name → { online, errorCount, pool metrics } for every node. */
+    status(): Record<string, any>;
+    private matching;
+    private pick;
+    private noteFailure;
+    /**
+     * 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;
+    getAsync(pattern?: string, selector?: ClusterSelector): Promise<any>;
+    /**
+     * 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): {
+        get(callback: Callback): void;
+        getAsync(): Promise<any>;
+        withConnection<T>(work: (db: any) => Promise<T> | T): Promise<T>;
+    };
+    /** 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>;
+    /** Destroy every node's pool. */
+    destroy(callback?: (err?: any) => void): void;
+    destroyAsync(): Promise<void>;
+}
+export default PoolCluster;

package/lib/pool-cluster.js

@@ -0,0 +1,266 @@
+"use strict";
+/***************************************
+ *
+ *   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.
+ *
+ ***************************************/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const events_1 = __importDefault(require("events"));
+const callback_1 = require("./callback");
+const uri_1 = require("./uri");
+const pool_1 = __importDefault(require("./pool"));
+function patternToRegExp(pattern) {
+    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_1.default.EventEmitter {
+    constructor(attach, options) {
+        super();
+        this.nodes = new Map();
+        this.rrIndex = new Map();
+        this._destroyed = false;
+        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, overrides) {
+        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 = (0, uri_1.parseConnectionString)(overrides);
+        }
+        const nodeOptions = { ...this.defaults, ...(overrides || {}) };
+        this.nodes.set(name, {
+            name,
+            options: nodeOptions,
+            pool: new pool_1.default(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, callback) {
+        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) {
+        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() {
+        const out = {};
+        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;
+    }
+    matching(pattern) {
+        const re = patternToRegExp(pattern);
+        const out = [];
+        for (const node of this.nodes.values()) {
+            if (re.test(node.name)) {
+                out.push(node);
+            }
+        }
+        return out;
+    }
+    pick(pattern, selector, exclude) {
+        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];
+    }
+    noteFailure(node) {
+        // 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, selector, callback) {
+        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 || this.selector;
+        const tried = new Set();
+        const self = this;
+        const attempt = (lastError) => {
+            const node = self.pick(pattern, 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, db) => {
+                if (err) {
+                    self.noteFailure(node);
+                    attempt(err);
+                    return;
+                }
+                node.errorCount = 0;
+                callback(null, db);
+            });
+        };
+        attempt();
+    }
+    getAsync(pattern, selector) {
+        const self = this;
+        return (0, callback_1.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, selector) {
+        const self = this;
+        return {
+            get(callback) {
+                self.get(pattern, selector, callback);
+            },
+            getAsync() {
+                return self.getAsync(pattern, selector);
+            },
+            withConnection(work) {
+                return self.withConnection(pattern, work, selector);
+            },
+        };
+    }
+    /** Run `work` with a connection from a matching node, always released. */
+    withConnection(pattern, work, selector) {
+        return (0, callback_1.withPooledConnection)(() => this.getAsync(pattern, selector), work);
+    }
+    /** Destroy every node's pool. */
+    destroy(callback) {
+        this._destroyed = true;
+        const nodes = [...this.nodes.values()];
+        this.nodes.clear();
+        let remaining = nodes.length;
+        if (!remaining) {
+            if (callback)
+                callback();
+            return;
+        }
+        let firstError = null;
+        for (const node of nodes) {
+            if (node.restoreTimer) {
+                clearTimeout(node.restoreTimer);
+            }
+            node.pool.destroy((err) => {
+                if (err && !firstError)
+                    firstError = err;
+                if (--remaining === 0 && callback)
+                    callback(firstError);
+            });
+        }
+    }
+    destroyAsync() {
+        const self = this;
+        return (0, callback_1.fromCallback)((cb) => self.destroy(cb));
+    }
+}
+exports.default = PoolCluster;

package/lib/pool.js

@@ -352,16 +352,8 @@ class Pool extends events_1.default.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(work) {
-        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(function (resolve) { db.detach(function () { resolve(); }); });
-        }
+    withConnection(work) {
+        return (0, callback_1.withPooledConnection)(() => this.getAsync(), work);
     }
 }
 module.exports = Pool;