node-firebird 2.13.0 → 2.14.0

package/README.md

@@ -355,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:

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;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.13.0",
+    "version": "2.14.0",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/callback.ts

@@ -45,6 +45,21 @@ export 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 async function withPooledConnection<T>(getAsync: () => Promise<any>, work: (db: any) => Promise<T> | T): Promise<T> {
+    const db = await getAsync();
+    try {
+        return await work(db);
+    } finally {
+        await new Promise<void>(function(resolve) { db.detach(function() { resolve(); }); });
+    }
+}
+
 export function fromCallback<T = any>(executor: (cb: Callback<T>) => void): Promise<T> {
     return new Promise<T>(function(resolve, reject) {
         executor(function(err?: any, result?: T) {

package/src/index.ts

@@ -2,6 +2,8 @@ import Const from './wire/const';
 import { doError, doCallback, fromCallback, type Callback } from './callback';
 import Connection from './wire/connection';
 import Pool from './pool';
+import PoolCluster from './pool-cluster';
+import type { PoolClusterOptions } from './pool-cluster';
 import { escape as escapeValue } from './utils';
 import { parseConnectionUri, parseConnectionString, normalizeOptions } from './uri';
 import type {
@@ -194,6 +196,19 @@ export function pool(max: number, options: Options | string): ConnectionPool {
 	return new Pool(attach, max, Object.assign({}, 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.
+ */
+export function poolCluster(options?: PoolClusterOptions): PoolCluster {
+	const normalized: PoolClusterOptions = { ...(options || {}) };
+	normalized.defaults = normalizeOptions(normalized.defaults || {});
+	return new PoolCluster(attach, normalized);
+}
+export type { PoolClusterOptions, ClusterSelector } from './pool-cluster';
+
 export { parseConnectionUri, parseConnectionString };
 export { parseNamedPlaceholders } from './named-params';
 

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);
     }
 }