node-firebird 2.11.0 → 2.13.0

package/README.md

@@ -13,8 +13,8 @@
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
 - [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, named placeholders, nested result tables (nestTables), 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
+- [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 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
@@ -154,6 +169,14 @@ Notes:
 
 ### Connection options
 
+Settings you leave out fall back to environment variables first — using
+Firebird's own conventions (`ISC_USER` and `ISC_PASSWORD`, the same
+variables isql honours) plus `FIREBIRD_HOST`, `FIREBIRD_PORT`,
+`FIREBIRD_DATABASE` and `FIREBIRD_ROLE` — and to the built-in defaults
+below (SYSDBA / masterkey / 127.0.0.1) only after that. Explicitly
+provided options always win, so credentials can stay out of code the
+same way `PGUSER`/`PGPASSWORD` work with pg.
+
 ```js
 var options = {};
 
@@ -186,6 +209,7 @@ options.owner = undefined; // optional; owner of a newly created database — le
 options.jsonAsObject = false; // optional; automatically stringify parameters and parse query results that contain JSON (FB >= 6.0)
 options.namedPlaceholders = false; // set to true to allow :name placeholders in SQL with a { name: value } params object (see Named placeholders)
 options.nestTables = false; // true nests object rows by source table (row[table][column]); a string separator flattens to 'table<sep>column' keys — see Nested result tables (nestTables). Overridable per query
+options.transformKeys = undefined; // 'camel' (FIRST_NAME → firstName) or a (key) => key mapper for object-row keys — see Transforming row keys (transformKeys). Overridable per query
 options.typeCast = undefined; // optional; custom type parser called for every result column value (see Custom type parsers)
 options.statementCacheSize = 0; // optional; per-connection LRU cache of prepared statements, 0 = disabled (see Prepared-statement cache)
 ```
@@ -293,9 +317,11 @@ The pool is an `EventEmitter` and exposes live counters, following the
 ```js
 const pool = Firebird.pool(10, {
     ...options,
-    idleTimeoutMillis: 30000, // close connections idle for 30s…
-    min: 2,                   // …but always keep 2 alive
+    idleTimeoutMillis: 30000,   // close connections idle for 30s…
+    min: 2,                     // …but always keep 2 alive
     connectTimeout: 5000,
+    maxUses: 7500,              // retire a connection after 7500 checkouts (pg's maxUses)
+    maxLifetimeMillis: 3600000, // …or 1h after creation (Postgres.js's max_lifetime)
 });
 
 pool.on('connect', (db) => console.log('new server connection'));
@@ -318,6 +344,12 @@ console.log({
   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)).
+- `maxUses` and `maxLifetimeMillis` **recycle** physical connections: a
+  worn-out or over-age connection is closed for good when returned to the
+  pool (lifetime is also enforced on idle connections by the sweep, even
+  below `min`) and a replacement is created on demand. Recycling bounds
+  server-side resource drift on long-lived connections. Both default to 0
+  (off).
 - `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.
@@ -453,6 +485,63 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+### Tagged-template queries (sql)
+
+`db.sql` / `transaction.sql` offer a Postgres.js-style tagged-template API
+on top of the regular parameter machinery. Interpolated values are bound
+as positional parameters — never concatenated into the SQL — so the API is
+injection-safe by construction:
+
+```js
+const id = 2;
+const rows = await db.sql`SELECT NAME FROM EMP WHERE ID = ${id}`;
+// → executes  SELECT NAME FROM EMP WHERE ID = ?  with params [2]
+```
+
+The returned query is a **lazy thenable**: it runs when awaited (or via
+`.then`/`.catch`/`.finally`), exactly once. Until then it can be embedded
+in another tag as a **fragment**, splicing its text and parameters in
+place:
+
+```js
+const filter = db.sql`DEPT_ID = ${1} AND ACTIVE = ${true}`;
+const rows = await db.sql`SELECT * FROM EMP WHERE ${filter} ORDER BY ID`;
+```
+
+Arrays expand to placeholder lists (for `IN`), and calling the tag with a
+string produces a safely quoted, dot-qualified **identifier** for dynamic
+table/column names:
+
+```js
+await db.sql`SELECT * FROM EMP WHERE ID IN (${[1, 2, 3]})`;
+
+const col = 'NAME';
+await db.sql`SELECT ${db.sql(col)} FROM ${db.sql('S1.EMP')}`;
+// → SELECT "NAME" FROM "S1"."EMP"
+```
+
+`.options({...})` attaches per-query options (`timeout`, `signal`,
+`nestTables`, …), `.withMeta()` executes resolving the
+[full result object](#result-metadata-and-affected-rows-withmeta), and
+`.toQuery()` returns the compiled `{ text, params }` without executing —
+handy for logging and tests:
+
+```js
+const r = await db.sql`UPDATE EMP SET ACTIVE = false WHERE ID = ${9}`.withMeta();
+// r.affectedRows === 1
+```
+
+Sharp edges, made loud instead of silent: a query executes once, in the
+shape of its first consumer — consuming it again in the *other* shape
+(plain `await` after `.withMeta()`, or vice versa) throws, as does
+`.options()` after execution. Interpolating an **empty array** throws
+(it would compile to invalid SQL like `IN ()`), and circular fragments
+are rejected instead of overflowing the stack. The compiled text is
+positional-only, so the [named placeholders](#named-placeholders)
+rewriter is disabled for tagged queries — PSQL `:variable` references
+in an `EXECUTE BLOCK` template are safe even with `namedPlaceholders:
+true` on the connection.
+
 ### Named placeholders
 
 With the `namedPlaceholders: true` connection option, SQL may use `:name`
@@ -537,6 +626,76 @@ array rows are positional and need no qualification. Works on every
 supported Firebird version (the source-table metadata comes from the
 statement describe, available since Firebird 2.0).
 
+### Transforming row keys (transformKeys)
+
+`transformKeys` rewrites object-row keys — the counterpart of
+Postgres.js's `transform`. The built-in `'camel'` maps `FIRST_NAME` →
+`firstName`; a custom `(key) => key` mapper gives full control. Accepted
+at connection level and per query (per-query wins):
+
+```js
+const rows = await db.queryAsync('SELECT EMP_ID, FIRST_NAME FROM EMP_INFO', [],
+  { transformKeys: 'camel' });
+// rows[0] = { empId: 1, firstName: 'Ada' }
+```
+
+The transform runs after `lowercase_keys` and applies to both parts of
+[`nestTables`](#nested-result-tables-nesttables) keys (`row.e.empId`).
+Column *metadata* — `withMeta` `fields` and the `typeCast` hook — keeps
+the raw server aliases. A custom mapper that throws falls back to the
+untransformed key (with a console warning) rather than corrupting the
+row decode.
+
+### Result metadata and affected rows (withMeta)
+
+By default, queries deliver bare rows and DML row counts are not reported.
+The per-query `withMeta: true` option switches the result (callback and
+promise APIs alike) to a full result object, the counterpart of pg's
+`{ rows, rowCount, fields }` and mysql2's `affectedRows`:
+
+```js
+const r = await db.queryAsync('UPDATE EMP SET ACTIVE = false WHERE DEPT_ID = ?', [1],
+  { withMeta: true });
+// r = {
+//   rows: undefined,            // rows array (SELECT), row object (RETURNING), or undefined
+//   fields: [...],              // per-column metadata (see below)
+//   affectedRows: 2,            // what the server actually changed
+//   recordCounts: { selectCount: 0, insertCount: 0, updateCount: 2, deleteCount: 0 },
+//   warnings: [],               // isc_arg_warning entries from the execute response
+// }
+```
+
+For DML (`INSERT`/`UPDATE`/`DELETE`, including `... RETURNING` and
+`EXECUTE PROCEDURE`), `affectedRows` is the server-reported count
+(`isc_info_sql_records`) and `recordCounts` breaks it down per verb — this
+costs one extra lightweight info request per statement, which is why the
+option is opt-in. For `SELECT`, `affectedRows` is simply the number of rows
+returned (pg's `rowCount` convention) with no extra round-trip, and
+`recordCounts` is absent.
+
+Each entry in `fields` describes one output column — the same vocabulary
+the [typeCast hook](#custom-type-parsers-typecast) receives, plus
+nullability and the relation alias/schema:
+
+```js
+{ type: 448, typeName: 'VARYING', subType: 4, scale: 0, length: 80,
+  nullable: true, field: 'NAME', relation: 'EMP', relationAlias: '',
+  relationSchema: 'PUBLIC', alias: 'NAME' }
+```
+
+(`relationSchema` is filled on Firebird 6.0+; `subType` of a text column is
+its character-set id.) In TypeScript, `queryAsync<T>(sql, params,
+{ withMeta: true })` resolves to `QueryResult<T>` automatically. Server
+warnings attached to any response — not just queries — are also emitted as
+[`'warning'` driver events](#driver-events).
+
+The option is honoured by `query`/`execute` (and their `*Async` wrappers),
+on databases and transactions alike. It is ignored by the streaming APIs
+(`sequentially`, `queryStream` — rows bypass the result there) and by
+`executeBatch` (which has its own completion shape). For `EXECUTE
+PROCEDURE`, `affectedRows` reflects DML the procedure performed — a
+procedure that only returns values reports 0 alongside its row.
+
 ### Custom type parsers (typeCast)
 
 The `typeCast` connection option lets you override how column values are
@@ -1009,6 +1168,41 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+#### Savepoints
+
+`transaction.savepoint(work)` runs `work` inside a savepoint (Firebird
+1.5+): on resolve the savepoint is **released**, on reject the transaction
+**rolls back to the savepoint** — undoing only `work`'s changes — and the
+error is rethrown while the transaction itself stays usable. Calls nest;
+names are generated automatically. This is the counterpart of
+Postgres.js's `sql.savepoint()` and mirrors `db.withTransaction`'s style:
+
+```js
+await db.withTransaction(async (tx) => {
+  await tx.sql`INSERT INTO ORDERS VALUES (${1}, ${'paid'})`;
+
+  try {
+    await tx.savepoint(async () => {
+      await tx.sql`INSERT INTO AUDIT VALUES (${1}, ${'optional enrichment'})`;
+      await maybeFailingStep(tx);
+    });
+  } catch (err) {
+    // the AUDIT insert is undone; the ORDERS insert survives and the
+    // transaction continues toward commit
+  }
+});
+```
+
+If the rollback-to itself fails (e.g. the connection died), the original
+error is still thrown, with the rollback failure attached as
+`err.savepointRollbackError`. A release failure does **not** roll the
+work back — only a `work` failure does.
+
+> **Note:** do not run sibling savepoints concurrently on one transaction
+> (`Promise.all`): Firebird's `RELEASE SAVEPOINT` also releases every
+> savepoint created after it, so interleaved siblings would release each
+> other. Nested (awaited) savepoints are fine.
+
 ### Driver Events
 
 Driver events are synchronous notifications emitted on the `Database` object for connection-level operations. Subscribe with `db.on(eventName, handler)`.
@@ -1030,7 +1224,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) {
@@ -1060,6 +1258,15 @@ Firebird.attach(options, function (err, db) {
     // rows === Array
   });
 
+  db.on('warning', function (warning) {
+    // fired (next tick) for every isc_arg_warning the server attaches to a
+    // successful response — e.g. "parallel workers value capped" when
+    // parallelWorkers exceeds the server maximum. The listener above is
+    // registered inside the attach callback and still catches attach-time
+    // warnings, because emission is deferred by one tick.
+    // warning === { gdscode: Number, params?: Array, message: String }
+  });
+
   db.detach();
 });
 ```
@@ -1318,7 +1525,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
@@ -1582,11 +1809,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
@@ -1922,6 +2181,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/pool.d.ts

@@ -22,7 +22,12 @@ type AttachFn = (options: any, callback: Callback) => void;
  *
  * 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.
+ * this many ms; 0/absent = never), options.connectTimeout,
+ * options.maxUses (retire a connection after this many checkouts — pg's
+ * maxUses), options.maxLifetimeMillis (retire a connection this many ms
+ * after it was created — Postgres.js's max_lifetime). Retirement happens
+ * when the connection is returned to the pool, and the sweep also closes
+ * over-lifetime idle connections; a replacement is created on demand.
  */
 declare class Pool extends Events.EventEmitter {
     attach: AttachFn;
@@ -33,11 +38,19 @@ declare class Pool extends Events.EventEmitter {
     max: number;
     min: number;
     idleTimeoutMillis: number;
+    maxUses: number;
+    maxLifetimeMillis: number;
     pending: Callback[];
     options: any;
     _destroyed: boolean;
     _reaper: NodeJS.Timeout | null;
     constructor(attach: AttachFn, max: number, options: any);
+    /** True when the connection exceeded maxUses / maxLifetimeMillis.
+     *  Both stamps are set unconditionally when the pool creates the
+     *  connection, so they can be read bare here. */
+    _isExpired(db: any): boolean;
+    /** Close a healthy pooled connection for good (reaper/retirement path). */
+    _retire(db: any): void;
     /** Physical connections owned by the pool (idle + in use). */
     get totalCount(): number;
     /** Connections sitting idle in the pool. */

package/lib/pool.js

@@ -25,7 +25,12 @@ const callback_1 = require("./callback");
  *
  * 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.
+ * this many ms; 0/absent = never), options.connectTimeout,
+ * options.maxUses (retire a connection after this many checkouts — pg's
+ * maxUses), options.maxLifetimeMillis (retire a connection this many ms
+ * after it was created — Postgres.js's max_lifetime). Retirement happens
+ * when the connection is returned to the pool, and the sweep also closes
+ * over-lifetime idle connections; a replacement is created on demand.
  */
 class Pool extends events_1.default.EventEmitter {
     constructor(attach, max, options) {
@@ -38,21 +43,51 @@ class Pool extends events_1.default.EventEmitter {
         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.maxUses = (options && options.maxUses > 0) ? options.maxUses : 0;
+        this.maxLifetimeMillis = (options && options.maxLifetimeMillis > 0) ? options.maxLifetimeMillis : 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) {
+        // the sweep serves both idle eviction and lifetime retirement of
+        // idle connections; base its cadence on the tightest configured limit
+        var sweepBasis = Math.min(this.idleTimeoutMillis || Infinity, this.maxLifetimeMillis || Infinity);
+        if (sweepBasis !== Infinity) {
             var self = this;
-            // Sweep at half the idle timeout (bounded to 100ms..30s) so a
-            // connection lives at most ~1.5x idleTimeoutMillis. unref() keeps
+            // Sweep at half the basis (bounded to 100ms..30s) so a
+            // connection lives at most ~1.5x its limit. unref() keeps
             // the timer from holding the process open.
-            var interval = Math.min(Math.max(this.idleTimeoutMillis / 2, 100), 30000);
+            var interval = Math.min(Math.max(sweepBasis / 2, 100), 30000);
             this._reaper = setInterval(function () { self._reap(); }, interval);
             if (this._reaper.unref)
                 this._reaper.unref();
         }
     }
+    /** True when the connection exceeded maxUses / maxLifetimeMillis.
+     *  Both stamps are set unconditionally when the pool creates the
+     *  connection, so they can be read bare here. */
+    _isExpired(db) {
+        if (this.maxUses > 0 && db.__poolUseCount >= this.maxUses)
+            return true;
+        if (this.maxLifetimeMillis > 0 && Date.now() - db.__poolCreatedAt >= this.maxLifetimeMillis)
+            return true;
+        return false;
+    }
+    /** Close a healthy pooled connection for good (reaper/retirement path). */
+    _retire(db) {
+        var self = this;
+        this._forget(db);
+        db.connection._pooled = false;
+        try {
+            db.detach(function (err) {
+                if (err)
+                    self._emitError(err, db);
+            });
+        }
+        catch (e) {
+            self._emitError(e, db);
+        }
+    }
     /** Physical connections owned by the pool (idle + in use). */
     get totalCount() {
         return this.internaldb.length;
@@ -105,22 +140,20 @@ class Pool extends events_1.default.EventEmitter {
                 self._forget(db);
                 return;
             }
+            // lifetime retirement applies even below min — recycling is the
+            // point; replacements are created on demand
+            if (self._isExpired(db)) {
+                self._retire(db);
+                return;
+            }
+            if (!self.idleTimeoutMillis)
+                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);
-            }
+            self._retire(db);
         });
     }
     get(callback) {
@@ -155,6 +188,7 @@ class Pool extends events_1.default.EventEmitter {
             }
             // Idle connection available — hand it out immediately.
             self.dbinuse++;
+            db.__poolUseCount = (db.__poolUseCount || 0) + 1;
             self.emit('acquire', db);
             cb(null, db);
         }
@@ -212,6 +246,8 @@ class Pool extends events_1.default.EventEmitter {
                 }
                 if (!err) {
                     self.dbinuse++;
+                    db.__poolCreatedAt = Date.now();
+                    db.__poolUseCount = 1;
                     self.internaldb.push(db);
                     db.on('detach', function () {
                         // also in pool (could be a twice call to detach)
@@ -222,6 +258,13 @@ class Pool extends events_1.default.EventEmitter {
                             self.internaldb.splice(self.internaldb.indexOf(db), 1);
                             self.emit('remove', db);
                         }
+                        else if (self._isExpired(db)) {
+                            // worn out (maxUses / maxLifetimeMillis): close it
+                            // for good instead of returning it to the idle
+                            // pool. The re-fired detach event exits early via
+                            // the internaldb guard above.
+                            self._retire(db);
+                        }
                         else {
                             db.__poolIdleSince = Date.now();
                             self.pooldb.push(db);

package/lib/sql-template.d.ts

@@ -0,0 +1,81 @@
+/***************************************
+ *
+ *   Tagged-template query API (Postgres.js-style)
+ *
+ *   db.sql`SELECT * FROM EMP WHERE ID = ${id}`   →  lazy thenable query
+ *   db.sql('COLUMN NAME')                        →  quoted identifier
+ *
+ *   Interpolated values become positional `?` parameters — never string
+ *   concatenation — so the API is injection-safe by construction. A query
+ *   embedded inside another tag is treated as a fragment: its text and
+ *   parameters are spliced in place. Arrays expand to `?, ?, ?` lists for
+ *   IN clauses. Execution is lazy (on await/then) and happens exactly once.
+ *
+ ***************************************/
+import type { QueryOptions, QueryResult } from './types';
+/** Executor provided by Database/Transaction: runs text+params, resolves rows
+ *  (or the full QueryResult when options.withMeta is set). */
+export type SqlExecutor = (text: string, params: any[], options?: QueryOptions) => Promise<any>;
+/** A dynamically quoted identifier produced by sql('name'). */
+export declare class SqlIdentifier {
+    name: string;
+    constructor(name: string);
+}
+/**
+ * Quote a (possibly dot-qualified) identifier for dialect 3: each part is
+ * wrapped in double quotes with embedded quotes doubled, so user input can
+ * never break out of the identifier position.
+ */
+export declare function quoteIdentifier(name: string): string;
+/** Compiled form of a tagged query: SQL text with `?` placeholders + params. */
+export interface CompiledQuery {
+    text: string;
+    params: any[];
+}
+/**
+ * A lazily executed tagged query. Awaiting it (or calling then/catch/
+ * finally) runs it through the owning Database/Transaction exactly once;
+ * embedding it in another tag uses it as a fragment instead and never
+ * executes it.
+ */
+export declare class SqlQuery<T = any> implements PromiseLike<T[]> {
+    readonly strings: readonly string[];
+    readonly values: any[];
+    private executor;
+    private queryOptions?;
+    private executed?;
+    private executedMeta?;
+    constructor(executor: SqlExecutor, strings: readonly string[], values: any[]);
+    /** The compiled SQL text (`?` placeholders) and parameter array. */
+    toQuery(): CompiledQuery;
+    /**
+     * Attach per-query options (timeout, signal, nestTables, …). Must be
+     * called before the query executes — options attached afterwards would
+     * be silently ignored, so that throws instead.
+     */
+    options(queryOptions: QueryOptions): this;
+    /** Execute resolving the full { rows, fields, affectedRows, … } result. */
+    withMeta(): Promise<QueryResult<T>>;
+    /**
+     * A query executes exactly once, in the shape of its first consumer
+     * (plain rows via then/await, or the full result via withMeta).
+     * Consuming it again in the OTHER shape cannot be honoured from the
+     * cached promise, so it throws rather than silently returning the
+     * wrong shape.
+     */
+    private run;
+    then<R1 = T[], R2 = never>(onfulfilled?: ((value: T[]) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: any) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    catch<R = never>(onrejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<T[] | R>;
+    finally(onfinally?: (() => void) | null): Promise<T[]>;
+}
+/** The dual-use tag: template tag executes, string call quotes an identifier. */
+export interface SqlTag {
+    <T = any>(strings: TemplateStringsArray, ...values: any[]): SqlQuery<T>;
+    (identifier: string): SqlIdentifier;
+}
+/**
+ * Build the `sql` tag for a Database/Transaction. `executor` receives the
+ * compiled text, params and per-query options and must return a promise
+ * (Database/Transaction pass their queryAsync).
+ */
+export declare function makeSqlTag(executor: SqlExecutor): SqlTag;