node-firebird 2.6.0 → 2.8.0

package/README.md

@@ -14,7 +14,7 @@
 - [Connection types](#connection-types) — connection options, classic connections, pooling
 - [Database object (db)](#database-object-db) — database, transaction and statement methods/options
 - [Examples](#examples) — parametrized queries, 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), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
+- [Extensive Examples](#extensive-examples) — DECFLOAT/INT128, query cancellation (AbortSignal), batch execution (bulk inserts), 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)
@@ -133,9 +133,9 @@ Available wrappers:
 
 - **module** — `Firebird.attachAsync(options)`, `createAsync`, `attachOrCreateAsync`, `dropAsync`; resolve with a `Database` (or a `ServiceManager` when `options.manager` is `true`)
 - **pool** — `pool.getAsync()`, `pool.destroyAsync()`, `pool.withConnection(work)`
-- **database** — `db.queryAsync(sql, params?, options?)`, `executeAsync`, `sequentiallyAsync(sql, params?, onRow, options?)`, `transactionAsync(options?)`, `newStatementAsync(sql)`, `attachEventAsync()`, `detachAsync()`, `dropAsync()`, `db.withTransaction(work, options?)`
-- **transaction** — `queryAsync`, `executeAsync`, `sequentiallyAsync`, `newStatementAsync`, `commitAsync`, `rollbackAsync`, `commitRetainingAsync`, `rollbackRetainingAsync`
-- **statement** — `executeAsync(transaction, params?, options?)`, `fetchAsync`, `fetchScrollAsync`, `fetchAllAsync`, `closeAsync`, `dropAsync`, `releaseAsync`
+- **database** — `db.queryAsync(sql, params?, options?)`, `executeAsync`, `executeBatchAsync(sql, rows, options?)`, `sequentiallyAsync(sql, params?, onRow, options?)`, `transactionAsync(options?)`, `newStatementAsync(sql)`, `attachEventAsync()`, `detachAsync()`, `dropAsync()`, `db.withTransaction(work, options?)`
+- **transaction** — `queryAsync`, `executeAsync`, `executeBatchAsync`, `sequentiallyAsync`, `newStatementAsync`, `commitAsync`, `rollbackAsync`, `commitRetainingAsync`, `rollbackRetainingAsync`
+- **statement** — `executeAsync(transaction, params?, options?)`, `executeBatchAsync(transaction, rows, options?)`, `fetchAsync`, `fetchScrollAsync`, `fetchAllAsync`, `closeAsync`, `dropAsync`, `releaseAsync`
 
 Notes:
 
@@ -217,6 +217,44 @@ pool.get(function (err, db) {
 pool.destroy();
 ```
 
+#### Pool events and metrics
+
+The pool is an `EventEmitter` and exposes live counters, following the
+`pg.Pool` conventions:
+
+```js
+const pool = Firebird.pool(10, {
+    ...options,
+    idleTimeoutMillis: 30000, // close connections idle for 30s…
+    min: 2,                   // …but always keep 2 alive
+    connectTimeout: 5000,
+});
+
+pool.on('connect', (db) => console.log('new server connection'));
+pool.on('acquire', (db) => console.log('connection handed to a caller'));
+pool.on('release', (db) => console.log('connection returned to the pool'));
+pool.on('remove',  (db) => console.log('connection closed & removed'));
+pool.on('error',   (err, db) => console.error('background pool error', err));
+
+// live metrics — e.g. for a /health endpoint or periodic monitoring
+console.log({
+    total:   pool.totalCount,   // physical connections (idle + in use)
+    idle:    pool.idleCount,    // available in the pool
+    active:  pool.activeCount,  // handed out to callers
+    waiting: pool.waitingCount, // get() calls queued for a free slot
+});
+```
+
+- `idleTimeoutMillis` closes connections that sat idle in the pool for that
+  long, never shrinking below `min` — long-lived pools no longer hold every
+  connection they ever created (issue [#329](https://github.com/hgourvest/node-firebird/issues/329)).
+  The sweep also evicts idle connections whose socket has died, so callers
+  don't receive them after a server restart (issue [#343](https://github.com/hgourvest/node-firebird/issues/343)).
+- `error` is a background-error channel (idle eviction failures and the
+  like); unlike a plain `EventEmitter`, it is only emitted when a listener
+  is attached, so existing applications keep working unchanged.
+- Metrics are plain getters — reading them has no side effects.
+
 #### Advanced Pooling Features
 
 The pool implementation includes several safeguards for reliability:
@@ -224,6 +262,7 @@ The pool implementation includes several safeguards for reliability:
 1.  **Connection Timeout**: Use `options.connectTimeout` to prevent the pool from hanging if a server accepts the TCP connection but fails to respond to the Firebird wire protocol (e.g., during high load or authentication stalls).
 2.  **Pool Destruction**: Calling `pool.destroy()` now immediately drains the `pending` queue, notifying all waiting callers with an error. It also prevents any further `pool.get()` calls.
 3.  **Slot Recovery**: If a connection attempt times out, the pool slot is correctly freed so subsequent requests can be served. Late-arriving connections are automatically discarded to prevent resource leaks.
+4.  **Idle Reaping & Health**: `idleTimeoutMillis`/`min` shrink the pool when traffic drops and evict dead idle connections (see [Pool events and metrics](#pool-events-and-metrics)).
 
 #### Pool Lifecycle State Diagram
 
@@ -277,6 +316,7 @@ sequenceDiagram
 
 - `db.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
 - `db.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
+- `db.executeBatch(query, rows, function(err, result), options)` - bulk execution in one round-trip, all-or-nothing (FB >= 4.0, see [Batch Execution](#batch-execution-firebird-40))
 - `db.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
 - `db.detach(function(err))` detach a database
 - `db.transaction(options, function(err, transaction))` create transaction
@@ -303,6 +343,7 @@ const options = {
 
 - `transaction.query(query, [params], function(err, result), options)` - classic query, returns Array of Object
 - `transaction.execute(query, [params], function(err, result), options)` - classic query, returns Array of Array
+- `transaction.executeBatch(query, rows, function(err, result), options)` - bulk execution with per-record errors (FB >= 4.0, see [Batch Execution](#batch-execution-firebird-40))
 - `transaction.sequentially(query, [params], function(row, index), function(err), options)` - sequentially query
 - `transaction.commit(function(err))` commit current transaction
 - `transaction.rollback(function(err))` rollback current transaction
@@ -1192,6 +1233,60 @@ Notes:
 - A signal that is already aborted rejects immediately with an `AbortError`
   without contacting the server; cancelling an idle connection is harmless.
 
+### Batch Execution (Firebird 4.0+)
+
+`executeBatch` sends many parameter rows for one statement in a single
+round-trip using the Firebird 4 wire batch API (`op_batch_create` /
+`op_batch_msg` / `op_batch_exec`) — typically 5–10× faster than executing
+row by row. Available on the database, transaction and statement objects, in
+callback and promise flavours.
+
+```js
+const rows = [
+    [1, 'Alice', 10.50, new Date(), true,  100n],
+    [2, 'Bob',   null,  new Date(), false, null],   // NULLs per column
+    [3, 'Carol', 7.25,  new Date(), true,  300n],
+];
+
+// database level: own transaction, all-or-nothing (rollback if any record fails)
+const res = await db.executeBatchAsync(
+    'INSERT INTO t (id, name, amount, created, active, big) VALUES (?, ?, ?, ?, ?, ?)',
+    rows);
+console.log(res.recordCount, res.updateCounts, res.success);
+
+// transaction level: partial success — failed records are reported,
+// the rest can still be committed
+const tr = await db.transactionAsync();
+const r = await tr.executeBatchAsync('INSERT INTO t (...) VALUES (?, ?, ?, ?, ?, ?)', rows);
+if (!r.success) {
+    console.log('failed record indexes:', r.errorRecordNumbers);   // 0-based
+    console.log('first error:', r.errors[0].error.message);
+}
+await tr.commitAsync();
+```
+
+The result object contains `recordCount`, `updateCounts` (one entry per
+record), `errors` (`{ recordNumber, error }` with full gdscode details),
+`errorRecordNumbers` and `success`. At the database level a failed batch
+rejects with the first record error, carrying the full completion state as
+`err.batchCompletion`.
+
+Options (last argument): `chunkSize` (rows per `op_batch_msg` packet,
+default 500), `multiError` (default `true` — collect all record errors
+instead of stopping at the first), `bufferSize` (server-side batch buffer
+in bytes).
+
+Notes:
+
+- Requires wire protocol 16+ (Firebird 4.0 or newer server).
+- 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.
+- Oversized `CHAR`/`VARCHAR` values fail the batch client-side before
+  anything is sent; server-side record errors (constraint violations,
+  truncation…) are reported per record.
+
 ### Statement Timeouts (Firebird 4.0+)
 Setting a statement timeout allows the client to automatically abort queries that take too long on the server.
 ```js

package/lib/pool.d.ts

@@ -3,19 +3,61 @@
  *   Simple Pooling
  *
  ***************************************/
+import Events from 'events';
 import type { Callback } from './callback';
 type AttachFn = (options: any, callback: Callback) => void;
-declare class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+declare class Pool extends Events.EventEmitter {
     attach: AttachFn;
     internaldb: any[];
     pooldb: any[];
     dbinuse: number;
     _creating: number;
     max: number;
+    min: number;
+    idleTimeoutMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
+    _reaper: NodeJS.Timeout | null;
     constructor(attach: AttachFn, max: number, options: any);
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount(): number;
+    /** Connections sitting idle in the pool. */
+    get idleCount(): number;
+    /** Connections currently handed out to callers. */
+    get activeCount(): number;
+    /** get() requests queued for a free slot. */
+    get waitingCount(): number;
+    /** True when the connection can no longer be used. */
+    _isDead(db: any): boolean;
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db: any): void;
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err: any, db?: any): void;
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap(): void;
     get(callback: Callback): this;
     check(): this;
     destroy(callback?: (err?: any) => void): void;

package/lib/pool.js

@@ -4,18 +4,124 @@
  *   Simple Pooling
  *
  ***************************************/
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const events_1 = __importDefault(require("events"));
 const callback_1 = require("./callback");
-class Pool {
+/**
+ * Connection pool with pg.Pool-style observability.
+ *
+ * Events (all optional to listen to):
+ *   'connect' (db)      — a new physical connection was established
+ *   'acquire' (db)      — a connection was handed to a caller
+ *   'release' (db)      — a connection was returned to the idle pool
+ *   'remove'  (db)      — a physical connection left the pool for good
+ *   'error'   (err, db) — a background error (idle eviction, reaper detach);
+ *                         only emitted when a listener is attached, so
+ *                         existing applications never crash on it
+ *
+ * Metrics: totalCount, idleCount, activeCount, waitingCount.
+ *
+ * Options: max (factory argument), options.min (floor the reaper never
+ * shrinks below), options.idleTimeoutMillis (close idle connections after
+ * this many ms; 0/absent = never), options.connectTimeout.
+ */
+class Pool extends events_1.default.EventEmitter {
     constructor(attach, max, options) {
+        super();
         this.attach = attach;
         this.internaldb = []; // connections created by the pool (for destroy)
         this.pooldb = []; // connections available in the pool (idle)
         this.dbinuse = 0; // connections currently handed out to callers
         this._creating = 0; // connections currently being created (attach in flight)
         this.max = max || 4;
+        this.min = (options && options.min > 0) ? Math.min(options.min, this.max) : 0;
+        this.idleTimeoutMillis = (options && options.idleTimeoutMillis > 0) ? options.idleTimeoutMillis : 0;
         this.pending = []; // callbacks waiting for a free slot
         this.options = options;
         this._destroyed = false; // true after destroy() — prevents further use
+        this._reaper = null;
+        if (this.idleTimeoutMillis) {
+            var self = this;
+            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // the timer from holding the process open.
+            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            this._reaper = setInterval(function () { self._reap(); }, interval);
+            if (this._reaper.unref)
+                this._reaper.unref();
+        }
+    }
+    /** Physical connections owned by the pool (idle + in use). */
+    get totalCount() {
+        return this.internaldb.length;
+    }
+    /** Connections sitting idle in the pool. */
+    get idleCount() {
+        return this.pooldb.length;
+    }
+    /** Connections currently handed out to callers. */
+    get activeCount() {
+        return this.dbinuse;
+    }
+    /** get() requests queued for a free slot. */
+    get waitingCount() {
+        return this.pending.length;
+    }
+    /** True when the connection can no longer be used. */
+    _isDead(db) {
+        return !db.connection || db.connection._isClosed || db.connection._isDetach ||
+            !db.connection._socket || db.connection._socket.destroyed;
+    }
+    /** Drop a physical connection from the pool's books and emit 'remove'. */
+    _forget(db) {
+        var idx = this.internaldb.indexOf(db);
+        if (idx !== -1)
+            this.internaldb.splice(idx, 1);
+        idx = this.pooldb.indexOf(db);
+        if (idx !== -1)
+            this.pooldb.splice(idx, 1);
+        this.emit('remove', db);
+    }
+    /** Emit 'error' only when someone listens — never crash the app. */
+    _emitError(err, db) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err, db);
+    }
+    /**
+     * Idle sweep: evict dead idle connections immediately and close healthy
+     * ones that have been idle longer than idleTimeoutMillis, keeping at
+     * least `min` physical connections. (issue #329)
+     */
+    _reap() {
+        if (this._destroyed)
+            return;
+        var self = this;
+        var now = Date.now();
+        // iterate over a copy — we splice from pooldb while walking
+        this.pooldb.slice().forEach(function (db) {
+            if (self._isDead(db)) {
+                self._forget(db);
+                return;
+            }
+            if (self.internaldb.length <= self.min)
+                return;
+            var idleSince = typeof db.__poolIdleSince === 'number' ? db.__poolIdleSince : now;
+            if (now - idleSince < self.idleTimeoutMillis)
+                return;
+            self._forget(db);
+            db.connection._pooled = false;
+            try {
+                db.detach(function (err) {
+                    if (err)
+                        self._emitError(err, db);
+                });
+            }
+            catch (e) {
+                self._emitError(e, db);
+            }
+        });
     }
     get(callback) {
         // [Fix 2] Reject immediately if the pool has already been destroyed.
@@ -41,16 +147,15 @@ class Pool {
         if (self.pooldb.length) {
             var db = self.pooldb.shift();
             // Discard connections that have been closed or destroyed while idle
-            if (db.connection && (db.connection._isClosed || db.connection._isDetach || !db.connection._socket || db.connection._socket.destroyed)) {
-                var idx = self.internaldb.indexOf(db);
-                if (idx !== -1)
-                    self.internaldb.splice(idx, 1);
+            if (self._isDead(db)) {
+                self._forget(db);
                 self.pending.unshift(cb);
                 setImmediate(function () { self.check(); });
                 return self;
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            self.emit('acquire', db);
             cb(null, db);
         }
         else {
@@ -113,13 +218,20 @@ class Pool {
                         if (self.pooldb.indexOf(db) !== -1 || self.internaldb.indexOf(db) === -1)
                             return;
                         // if not usable don't put it back in the pool
-                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false)
+                        if (db.connection._isClosed || db.connection._isDetach || db.connection._pooled === false) {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
-                        else
+                            self.emit('remove', db);
+                        }
+                        else {
+                            db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);
+                            self.emit('release', db);
+                        }
                         self.dbinuse--;
                         self.check();
                     });
+                    self.emit('connect', db);
+                    self.emit('acquire', db);
                 }
                 cb(err, db);
             });
@@ -132,6 +244,10 @@ class Pool {
     destroy(callback) {
         var self = this;
         self._destroyed = true;
+        if (self._reaper) {
+            clearInterval(self._reaper);
+            self._reaper = null;
+        }
         // [Fix 4] Drain pending callbacks so callers are not left hanging.
         // This is critical when destroy() is called as a recovery measure after
         // a timeout: without draining, every concurrent pool.get() that had not
@@ -170,6 +286,7 @@ class Pool {
                 self.pooldb.splice(_db_in_pool, 1);
                 db.connection._pooled = false;
                 db.detach(detachCallback);
+                self.emit('remove', db);
             }
             else {
                 // [Fix 5] Connection is currently in use (dbinuse > 0).

package/lib/types.d.ts

@@ -64,6 +64,32 @@ export type TransactionOptions = {
     wait?: boolean;
     waitTimeout?: number;
 };
+/** Result of an executeBatch call (Firebird 4 batch API, protocol 16+). */
+export interface BatchResult {
+    /** Total number of records processed by the server. */
+    recordCount: number;
+    /** Per-record update counts (in record order). */
+    updateCounts: number[];
+    /** Per-record failures with full status vectors (capped by `detailedErrors`). */
+    errors: Array<{
+        recordNumber: number;
+        error: Error;
+    }>;
+    /** Record numbers of ALL failed records (detailed + status-less). */
+    errorRecordNumbers: number[];
+    /** True when every record executed without error. */
+    success: boolean;
+}
+export type BatchOptions = {
+    /** Continue past per-record errors and report them all (default true). */
+    multiError?: boolean;
+    /** Server-side batch buffer limit in bytes (BATCH_TAG_BUFFER_BYTES_SIZE). */
+    bufferSize?: number;
+    /** Max number of detailed per-record status vectors returned (server default 64). */
+    detailedErrors?: number;
+    /** Rows per op_batch_msg packet (default 500). */
+    chunkSize?: number;
+};
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
@@ -83,6 +109,8 @@ export interface Database {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
@@ -93,6 +121,7 @@ export interface Database {
     createSchema(schemaName: string, tablespaceName?: string | QueryCallback, callback?: QueryCallback): Database;
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -116,6 +145,8 @@ export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
     query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
     execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
+    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
@@ -123,6 +154,7 @@ export interface Transaction {
     rollbackRetaining(callback?: SimpleCallback): void;
     queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
     executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
+    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
@@ -139,7 +171,10 @@ export interface Statement {
     fetch(transaction: Transaction, count: number, callback: QueryCallback): void;
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
+    /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
+    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;
@@ -189,6 +224,19 @@ export interface Options {
      * expected Firebird server response time under load.
      */
     connectTimeout?: number;
+    /**
+     * Pool only: minimum number of physical connections the idle reaper
+     * keeps alive. Only meaningful together with `idleTimeoutMillis`.
+     * Default 0 (the pool may shrink to no connections).
+     */
+    min?: number;
+    /**
+     * Pool only: close connections that have been idle in the pool for this
+     * many milliseconds, never shrinking below `min`. Dead idle connections
+     * (server restarts, dropped sockets) are evicted on the same sweep.
+     * Default 0 (idle connections are kept forever).
+     */
+    idleTimeoutMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -230,9 +278,24 @@ export interface Options {
 export interface SvcMgrOptions extends Options {
     manager: true;
 }
+export type PoolEvent = 'connect' | 'acquire' | 'release' | 'remove' | 'error';
 export interface ConnectionPool {
     get(callback: DatabaseCallback): void;
     destroy(callback?: SimpleCallback): void;
+    /** Physical connections owned by the pool (idle + in use). */
+    readonly totalCount: number;
+    /** Connections sitting idle in the pool. */
+    readonly idleCount: number;
+    /** Connections currently handed out to callers. */
+    readonly activeCount: number;
+    /** get() requests queued for a free slot. */
+    readonly waitingCount: number;
+    on(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    on(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    once(event: 'connect' | 'acquire' | 'release' | 'remove', listener: (db: Database) => void): this;
+    once(event: 'error', listener: (err: Error, db?: Database) => void): this;
+    off(event: PoolEvent, listener: (...args: any[]) => void): this;
+    removeListener(event: PoolEvent, listener: (...args: any[]) => void): this;
     getAsync(): Promise<Database>;
     destroyAsync(): Promise<void>;
     /** Acquire a connection, run `work`, always return the connection to the pool. */

package/lib/wire/connection.d.ts

@@ -64,6 +64,8 @@ declare class Connection {
      * op_cancel packet itself has no response, so nothing is queued here.
      */
     cancelOperation(kind: any, callback: any): this;
+    /** Write a prebuilt packet and queue its response callback. */
+    _queueEventBuffer(buffer: any, callback: any): void;
     _queueEvent(callback: any, defer?: boolean): void;
     connect(options: any, callback: any): void;
     attach(options: any, callback?: any, db?: any): void;
@@ -82,6 +84,19 @@ declare class Connection {
     allocateAndPrepareStatement(transaction: any, query: any, plan: any, callback: any): void;
     prepare(transaction: any, query: any, plan: any, callback: any): void;
     prepareStatement(transaction: any, statement: any, query: any, plan: any, callback: any): this;
+    /**
+     * Execute a statement once per row using the Firebird 4 batch API
+     * (protocol 16+): op_batch_create + op_batch_msg(s) + op_batch_exec +
+     * op_batch_rls, all pipelined in a single network flush. Every packet
+     * gets an in-order response (op_batch_cs for exec), so the regular
+     * response queue keeps everything in sync.
+     *
+     * rows: array of parameter arrays, one per record. BLOB/ARRAY columns
+     * are not supported yet. The callback receives a completion object:
+     * { recordCount, updateCounts, errors: [{recordNumber, error}],
+     *   errorRecordNumbers, success }.
+     */
+    executeBatch(transaction: any, statement: any, rows: any, callback: any, options: any): this;
     executeStatement(transaction: any, statement: any, params: any, callback: any, custom: any): this;
     sendExecute(op: number, statement: any, transaction: any, callback: any, parameters?: any[]): void;
     fetch(statement: any, transaction: any, count: any, callback: any): void;