node-firebird 2.9.0 → 2.11.0

package/README.md

@@ -13,7 +13,7 @@
 - [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, BLOBs, streaming big data, transactions, driver events, database events (POST_EVENT), service manager, charsets/encoding, Firebird 3.0–6.0 features
+- [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
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
@@ -136,6 +136,7 @@ Available wrappers:
 - **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`
+- **service manager** — every [Service Manager function](#service-manager-functions) has an `*Async` counterpart (`backupAsync`, `restoreAsync`, `getUsersAsync`, `addUserAsync`, `getFbserverInfosAsync`, `startTraceAsync`, …); stream-producing functions resolve with the `Readable`, info functions with the info object
 
 Notes:
 
@@ -174,13 +175,19 @@ options.wireCrypt = Firebird.WIRE_CRYPT_ENABLE; // default; set to Firebird.WIRE
 options.pluginName = undefined; // optional, auto-negotiated; can be set to Firebird.AUTH_PLUGIN_SRP256, Firebird.AUTH_PLUGIN_SRP, or Firebird.AUTH_PLUGIN_LEGACY
 options.dbCryptConfig = undefined; // optional; database encryption key for encrypted databases. Use 'base64:<value>' for base64-encoded keys or plain text
 options.connectTimeout = 10000; // optional; timeout in ms for a single pool.get() attach operation (default: no timeout)
+options.enableKeepAlive = true; // TCP keepalive probing to detect dead/stale connections (same option names as mysql2); set to false to disable
+options.keepAliveInitialDelay = 60000; // ms a socket must be idle before the first keepalive probe (ignored when enableKeepAlive is false)
 options.parallelWorkers = undefined; // optional; request multiple thread workers for maintenance/index tasks (FB >= 5)
 options.maxInlineBlobSize = undefined; // optional; threshold size in bytes for inline blob transmission (default 65535, FB >= 5.0.3)
-options.maxNegotiatedProtocols = 10; // optional; limit maximum protocol versions negotiated (default 10 for compatibility, set to 11 for FB >= 6.0)
-options.defaultSchema = undefined; // optional; sets session CURRENT_SCHEMA at connect time (FB >= 6.0)
+options.maxNegotiatedProtocols = undefined; // optional; cap how many protocol versions are offered, oldest first (default: all, up to Protocol 20; set to 10 to stop at Protocol 19)
+options.defaultSchema = undefined; // optional; sets session CURRENT_SCHEMA at connect time by putting the schema first in the search path (FB >= 6.0)
 options.searchPath = undefined; // optional; ordered list/array of schemas to resolve unqualified object references (FB >= 6.0)
+options.owner = undefined; // optional; owner of a newly created database — lets a superuser create a database for another user (create only, FB >= 6.0)
 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.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)
 ```
 
 ### Connection URI strings
@@ -486,6 +493,178 @@ the per-query option:
 await db.queryAsync(execBlockSql, [], { namedPlaceholders: false });
 ```
 
+### Nested result tables (nestTables)
+
+In a `JOIN`, columns sharing a name overwrite each other in object rows —
+`SELECT EMP.ID, DEPT.ID ...` leaves only one `ID` key. The `nestTables`
+option (same as mysql2's) qualifies row keys by source table instead. It is
+accepted at connection level and per query; the per-query value wins.
+
+With `nestTables: true` each row nests one sub-object per table:
+
+```js
+const rows = await db.queryAsync(
+  'SELECT EMP.ID, EMP.NAME, DEPT.ID, DEPT.NAME FROM EMP JOIN DEPT ON DEPT.ID = EMP.DEPT_ID',
+  [], { nestTables: true });
+// rows[0] = { EMP: { ID: 10, NAME: 'Ada' }, DEPT: { ID: 1, NAME: 'Engineering' } }
+```
+
+With a string separator the keys stay flat but qualified:
+
+```js
+const rows = await db.queryAsync(sql, [], { nestTables: '_' });
+// rows[0] = { EMP_ID: 10, EMP_NAME: 'Ada', DEPT_ID: 1, DEPT_NAME: 'Engineering' }
+```
+
+The table qualifier is the query's relation alias when one is used, the
+table name otherwise — so self-joins nest cleanly:
+
+```js
+const rows = await db.queryAsync(
+  'SELECT E.NAME, B.NAME FROM EMP E LEFT JOIN EMP B ON B.ID = E.BOSS_ID',
+  [], { nestTables: true });
+// rows[0] = { E: { NAME: 'Grace' }, B: { NAME: 'Ada' } }
+```
+
+Expression columns (no source table) qualify as `''`, exactly like mysql2:
+they land under the `''` key when nesting (`row[''].ANSWER`) and get the
+bare separator prefix in separator mode (`row._ANSWER`) — always prefixing
+keeps qualified keys collision-free (a bare expression alias could
+otherwise collide with a real `table<sep>column` key). Keys honour
+`lowercase_keys`, and the option composes with
+`typeCast`, `blobAsText` and `queryStream`. Object rows only: `db.execute`
+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).
+
+### Custom type parsers (typeCast)
+
+The `typeCast` connection option lets you override how column values are
+decoded, per SQL type or per column — the same idea as mysql2's `typeCast`
+and pg's `setTypeParser`. The hook is called for **every column value of
+every result row** (including `NULL`s); whatever it returns becomes the
+value in the row. Call `next()` to get the value the driver would produce
+by default (after `blobAsText` / `jsonAsObject` are applied).
+
+```js
+const Firebird = require('node-firebird');
+
+Firebird.attach({
+    ...options,
+    typeCast: (column, next) => {
+        // dates as ISO strings instead of Date objects
+        if (column.typeName === 'DATE') {
+            const v = next();
+            return v === null ? null : v.toISOString().slice(0, 10);
+        }
+        // BIGINT columns as strings
+        if (column.type === Firebird.SQL_TYPES.SQL_INT64 && !column.scale) {
+            return String(next());
+        }
+        return next(); // everything else: default decoding
+    },
+}, (err, db) => { /* ... */ });
+```
+
+`column` describes the result column:
+
+| Property   | Meaning                                                             |
+| :--------- | :------------------------------------------------------------------ |
+| `type`     | Firebird SQL type code — compare against `Firebird.SQL_TYPES.*`      |
+| `typeName` | Friendly name: `'VARYING'`, `'INT64'`, `'DATE'`, `'BLOB'`, ...       |
+| `subType`  | Column subtype (`1` = text for BLOBs)                                |
+| `scale`    | Negative decimal scale for `NUMERIC`/`DECIMAL` (e.g. `-2`)           |
+| `length`   | Declared length in bytes                                             |
+| `field`    | Column name in the table                                             |
+| `relation` | Table name                                                           |
+| `alias`    | SELECT-list alias (the row key for object rows)                      |
+
+Notes:
+
+- Non-text BLOB columns reach the hook as the usual asynchronous fetch
+  function; text BLOBs with `blobAsText: true` reach it as the resolved
+  string.
+- The hook must be a **pure function** of its inputs: when a response
+  spans multiple TCP packets the affected rows can be decoded more than
+  once, calling the hook again for the same value.
+- The hook runs for every value on the hot row-decoding path — keep it
+  cheap, and prefer dispatching on `column.type`/`column.typeName` early.
+- Exceptions thrown by the hook are caught: the default value is used and
+  a warning is printed. A throw cannot be allowed to escape into the wire
+  decoder, so validate inside the hook and encode failures in the value.
+
+### Prepared-statement cache
+
+Setting `statementCacheSize` keeps a per-connection LRU cache of prepared
+statements (like mysql2's statement cache): running the same SQL string
+again transparently reuses the already-prepared server-side statement,
+skipping the prepare round-trip. No API changes are needed — `db.query`,
+`tx.query`, `sequentially`, `executeBatch` and the `*Async` wrappers all
+benefit automatically.
+
+```js
+Firebird.attach({ ...options, statementCacheSize: 100 }, (err, db) => {
+    // the second identical query reuses the prepared statement
+    db.query('SELECT * FROM t WHERE id = ?', [1], () => {
+        db.query('SELECT * FROM t WHERE id = ?', [2], () => { /* ... */ });
+    });
+});
+```
+
+How it works:
+
+- The number is the maximum of **idle** statements kept per connection;
+  the least-recently-used statement is dropped when the limit is exceeded.
+- A cached statement leaves the cache while in use, so concurrent runs of
+  the same SQL never share a server-side cursor — extra preparations run
+  in parallel and only one goes back into the cache.
+- Statements that failed and DDL statements are never cached.
+- Cache keys are exact SQL strings (after the `namedPlaceholders`
+  rewrite), so use parametrized queries to get hits.
+- The legacy `cacheQuery: true` / `maxCachedQuery` options remain
+  supported and now map onto the same LRU cache (with a default limit of
+  100 instead of the old unbounded map).
+
+> **Note (DDL):** a statement prepared before a metadata change (e.g.
+> `ALTER TABLE`) may fail when reused. If you mix DDL with hot queries on
+> the same connection, keep the cache small or disabled.
+
+### Streaming rows with queryStream
+
+`db.queryStream(sql, params, options)` returns an **object-mode
+`Readable`** emitting one row per chunk — the counterpart of
+`pg-query-stream` and mysql2's `.stream()`. It is built on
+`sequentially()`'s backpressure: fetching from the server pauses while
+the stream's buffer is full and resumes as the consumer drains it, so
+constant memory is used regardless of the result size.
+
+```js
+const { pipeline } = require('stream/promises');
+
+// async iteration
+for await (const row of db.queryStream('SELECT * FROM big_table')) {
+    console.log(row.ID);
+}
+
+// or piping into any Writable/Transform (HTTP response, CSV encoder, ...)
+await pipeline(
+    db.queryStream('SELECT * FROM big_table WHERE grp = ?', [42]),
+    myCsvTransform,
+    res);
+```
+
+- `db.queryStream` runs in its own transaction (like `db.query`);
+  `transaction.queryStream` runs inside your transaction, which is *not*
+  committed when the stream ends.
+- Destroying the stream early — including an error mid-`pipeline()` —
+  aborts the fetch and releases the statement; the connection stays
+  usable.
+- Options: everything `query` accepts (e.g. `signal`), plus
+  `highWaterMark` (rows buffered before fetching pauses, default 16) and
+  `asObject: false` for array rows.
+- Rows go through the regular decode path, so `typeCast`, `blobAsText`
+  and `jsonAsObject` all apply.
+
 ### Tablespaces and Schema Partitioning (Firebird 6.0+)
 
 For Firebird 6.0+ (Protocol 20+), you can create and manage physical tablespace locations and logical schema namespaces, optionally partitioning schemas into specific physical tablespaces.
@@ -1020,6 +1199,26 @@ var fbsvc = {
 
 ```
 
+Every function also has a promise-returning `*Async` counterpart (no
+callback argument): stream-producing functions resolve with the
+`Readable`, info functions with the info object.
+
+```js
+const svc = await Firebird.attachAsync({ ...options, manager: true });
+try {
+    const info = await svc.getFbserverInfosAsync();
+    console.log(info.fbversion);
+
+    const backup = await svc.backupAsync({
+        database: '/DB/MYDB.FDB',
+        files: [{ filename: '/DB/MYDB.FBK' }]
+    });
+    for await (const line of backup) console.log(line);
+} finally {
+    await svc.detachAsync();
+}
+```
+
 ### Backup Service example
 
 ```js
@@ -1758,13 +1957,13 @@ db.transaction(function (err, tx) {
 
 #### Is the wire protocol version hard-coded?
 
-No. node-firebird negotiates the highest protocol version both the client and server support, up to `options.maxNegotiatedProtocols` (default `10`, i.e. Protocol 19 — see [Protocol Implementation Status](ROADMAP.md#4-protocol-implementation-status) in the roadmap for the full version table). Raise it if you're on Firebird 6.0 and want to attempt Protocol 20:
+No. node-firebird negotiates the highest protocol version both the client and server support — up to Protocol 20 (Firebird 6.0) by default; see [Protocol Implementation Status](ROADMAP.md#4-protocol-implementation-status) in the roadmap for the full version table. Servers ignore protocol versions they do not know, so offering the full list is safe on old servers too. To cap negotiation at an older protocol, limit how many versions are offered (the list is ordered oldest first):
 
 ```js
-options.maxNegotiatedProtocols = 11; // offers Protocol 20 as well as 19
+options.maxNegotiatedProtocols = 10; // stop at Protocol 19 (pre-Firebird 6 behavior)
 ```
 
-The default is capped at 10 (Protocol 19) rather than the full list because Protocol 20 has a known query-preparation hang on some Firebird 6.0 builds — see the "Firebird 6 and Beyond" note in [ROADMAP.md](ROADMAP.md#4-protocol-implementation-status).
+Historical note: Protocol 20 used to be excluded by default because of a query-preparation hang — the client did not send the `p_sqlst_flags` field that protocol 20 added to `op_prepare_statement`, leaving the server blocked mid-packet. The field is now sent and Protocol 20 is fully negotiated.
 
 #### BLOB reads/writes are very slow, especially for large files over a remote connection
 
@@ -1821,6 +2020,12 @@ db.query('SELECT * FROM ACTORS WHERE NAME LIKE ?', ['James Wick%'], function (er
 });
 ```
 
+#### attach() *sometimes* fails with gdscode 335544472 ("Your user name and password are not defined") even though the credentials are correct
+
+If the failure is intermittent — the same code with the same credentials succeeds on most attempts and fails on others — update the driver: versions before 2.8.1 had two serialization mismatches in the SRP (Srp/Srp256/384/512) proof-of-password computation that made roughly 1 in 80 attaches fail with exactly this error (whenever the ephemeral SRP values happened to have a leading zero byte). Fixed in 2.8.1; see [issue #421](https://github.com/hgourvest/node-firebird/issues/421) and [issue #347](https://github.com/hgourvest/node-firebird/issues/347). Switching the user to `Legacy_UserManager`/`Legacy_Auth` "fixed" it on older versions only because that avoids the SRP code path entirely — with 2.8.1+ this workaround is no longer needed.
+
+If the failure is consistent, the credentials really don't match an account for the authentication plugin in use: check `AuthServer`/`UserManager` in `firebird.conf` and remember that SRP and Legacy user managers keep separate password stores — a user created under one plugin does not automatically exist for the other.
+
 ## Contributing
 
 Contributions are welcome — code, documentation, and bug reports alike.

package/lib/index.d.ts

@@ -24,6 +24,11 @@ export declare const ISOLATION_REPEATABLE_READ: number[];
 export declare const ISOLATION_SERIALIZABLE: number[];
 export declare const ISOLATION_READ_COMMITTED_READ_ONLY: number[];
 export declare const escape: typeof escapeValue;
+/**
+ * Firebird SQL type codes, as seen in `column.type` inside a `typeCast`
+ * hook (each code also has a friendly `column.typeName`).
+ */
+export declare const SQL_TYPES: Readonly<Record<string, number>>;
 /**
  * The most recent Connection created by attach()/create()/attachOrCreate().
  * Kept for backwards compatibility with the previous CommonJS module where

package/lib/index.js

@@ -17,7 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseNamedPlaceholders = exports.parseConnectionString = exports.parseConnectionUri = exports.connection = exports.escape = exports.ISOLATION_READ_COMMITTED_READ_ONLY = exports.ISOLATION_SERIALIZABLE = exports.ISOLATION_REPEATABLE_READ = exports.ISOLATION_READ_COMMITTED = exports.ISOLATION_READ_UNCOMMITTED = exports.WIRE_CRYPT_ENABLE = exports.WIRE_CRYPT_DISABLE = exports.AUTH_PLUGIN_SRP512 = exports.AUTH_PLUGIN_SRP384 = exports.AUTH_PLUGIN_SRP256 = exports.AUTH_PLUGIN_SRP = exports.AUTH_PLUGIN_LEGACY = exports.GDSCode = void 0;
+exports.parseNamedPlaceholders = exports.parseConnectionString = exports.parseConnectionUri = exports.connection = exports.SQL_TYPES = exports.escape = exports.ISOLATION_READ_COMMITTED_READ_ONLY = exports.ISOLATION_SERIALIZABLE = exports.ISOLATION_REPEATABLE_READ = exports.ISOLATION_READ_COMMITTED = exports.ISOLATION_READ_UNCOMMITTED = exports.WIRE_CRYPT_ENABLE = exports.WIRE_CRYPT_DISABLE = exports.AUTH_PLUGIN_SRP512 = exports.AUTH_PLUGIN_SRP384 = exports.AUTH_PLUGIN_SRP256 = exports.AUTH_PLUGIN_SRP = exports.AUTH_PLUGIN_LEGACY = exports.GDSCode = void 0;
 exports.attach = attach;
 exports.drop = drop;
 exports.create = create;
@@ -63,6 +63,35 @@ exports.ISOLATION_REPEATABLE_READ = const_1.default.ISOLATION_REPEATABLE_READ;
 exports.ISOLATION_SERIALIZABLE = const_1.default.ISOLATION_SERIALIZABLE;
 exports.ISOLATION_READ_COMMITTED_READ_ONLY = const_1.default.ISOLATION_READ_COMMITTED_READ_ONLY;
 exports.escape = utils_1.escape;
+/**
+ * Firebird SQL type codes, as seen in `column.type` inside a `typeCast`
+ * hook (each code also has a friendly `column.typeName`).
+ */
+exports.SQL_TYPES = Object.freeze({
+    SQL_TEXT: const_1.default.SQL_TEXT,
+    SQL_VARYING: const_1.default.SQL_VARYING,
+    SQL_SHORT: const_1.default.SQL_SHORT,
+    SQL_LONG: const_1.default.SQL_LONG,
+    SQL_FLOAT: const_1.default.SQL_FLOAT,
+    SQL_DOUBLE: const_1.default.SQL_DOUBLE,
+    SQL_D_FLOAT: const_1.default.SQL_D_FLOAT,
+    SQL_TIMESTAMP: const_1.default.SQL_TIMESTAMP,
+    SQL_BLOB: const_1.default.SQL_BLOB,
+    SQL_ARRAY: const_1.default.SQL_ARRAY,
+    SQL_QUAD: const_1.default.SQL_QUAD,
+    SQL_TYPE_TIME: const_1.default.SQL_TYPE_TIME,
+    SQL_TYPE_DATE: const_1.default.SQL_TYPE_DATE,
+    SQL_INT64: const_1.default.SQL_INT64,
+    SQL_INT128: const_1.default.SQL_INT128,
+    SQL_TIMESTAMP_TZ: const_1.default.SQL_TIMESTAMP_TZ,
+    SQL_TIMESTAMP_TZ_EX: const_1.default.SQL_TIMESTAMP_TZ_EX,
+    SQL_TIME_TZ: const_1.default.SQL_TIME_TZ,
+    SQL_TIME_TZ_EX: const_1.default.SQL_TIME_TZ_EX,
+    SQL_DEC16: const_1.default.SQL_DEC16,
+    SQL_DEC34: const_1.default.SQL_DEC34,
+    SQL_BOOLEAN: const_1.default.SQL_BOOLEAN,
+    SQL_NULL: const_1.default.SQL_NULL,
+});
 function attach(options, callback) {
     options = (0, uri_1.normalizeOptions)(options);
     var host = options.host || const_1.default.DEFAULT_HOST;
@@ -135,6 +164,8 @@ function attachOrCreate(options, callback) {
                 if (!err) {
                     if (self.db)
                         self.db.emit('connect', ret);
+                    // DatabaseCallback stays permissive (db non-optional) for
+                    // API users; internally the error path passes no db
                     (0, callback_1.doCallback)(ret, callback);
                     return;
                 }

package/lib/pool.js

@@ -141,7 +141,7 @@ class Pool extends events_1.default.EventEmitter {
             return self;
         if ((self.dbinuse + self._creating) >= self.max)
             return self;
-        var cb = self.pending.shift();
+        const cb = self.pending.shift();
         if (!cb)
             return self;
         if (self.pooldb.length) {

package/lib/srp.d.ts

@@ -22,7 +22,7 @@ export declare function clientSeed(a?: bigint): KeyPair;
  * @param b BigInt Server private key.
  * @returns {{private: BigInt, public: BigInt}}
  */
-export declare function serverSeed(user: string, password: string, salt: Buffer, b?: bigint | string, hashAlgo?: string): KeyPair;
+export declare function serverSeed(user: string, password: string, salt: Buffer | string, b?: bigint | string, hashAlgo?: string): KeyPair;
 /**
  * Server session secret.
  *
@@ -34,11 +34,11 @@ export declare function serverSeed(user: string, password: string, salt: Buffer,
  * @param b BigInt Server private key.
  * @returns {BigInt}
  */
-export declare function serverSession(user: string, password: string, salt: Buffer, A: bigint, B: bigint, b: bigint, hashAlgo?: string): bigint;
+export declare function serverSession(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, b: bigint, hashAlgo?: string): bigint;
 /**
  * M = H(H(N) xor H(g), H(I), s, A, B, K)
  */
-export declare function clientProof(user: string, password: string, salt: Buffer, A: bigint, B: bigint, a: bigint, hashAlgo?: string): ClientProof;
+export declare function clientProof(user: string, password: string, salt: Buffer | string, A: bigint, B: bigint, a: bigint, hashAlgo?: string): ClientProof;
 /**
  *  Pad hex string.
  */

package/lib/types.d.ts

@@ -1,3 +1,4 @@
+import type { Readable } from 'stream';
 export type DatabaseCallback = (err: any, db: Database) => void;
 export type TransactionCallback = (err: any, transaction: Transaction) => void;
 export type QueryCallback = (err: any, result: any[]) => void;
@@ -114,6 +115,27 @@ export type QueryOptions = {
      * it cancels whatever is currently executing on the connection.
      */
     signal?: AbortSignal;
+    /**
+     * Per-query override of the `nestTables` connection option (mysql2
+     * semantics). `true` nests each object row by source table:
+     * `row[table][column]` — the table key is the query's relation alias
+     * when one is used (`FROM emp e` → `row.E`), the table name otherwise,
+     * and `''` for expression columns. A string separator flattens keys
+     * instead: `nestTables: '_'` → `row.EMP_NAME`; expression columns get
+     * the bare separator prefix (`row._ANSWER`, as in mysql2). Keys honour
+     * `lowercase_keys`. Object rows only — `db.execute` array rows are
+     * unaffected.
+     */
+    nestTables?: boolean | string;
+};
+export type QueryStreamOptions = QueryOptions & {
+    /**
+     * Rows buffered internally before fetching pauses (object-mode
+     * Readable highWaterMark, default 16).
+     */
+    highWaterMark?: number;
+    /** Emit array rows instead of objects (like db.execute). */
+    asObject?: boolean;
 };
 export interface Database {
     detach(callback?: SimpleCallback): Database;
@@ -124,6 +146,13 @@ export interface Database {
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` and return an object-mode Readable emitting one row per
+     * chunk, with backpressure (fetching pauses while the buffer is full).
+     * Runs in its own transaction. Destroying the stream early aborts the
+     * fetch and releases the statement.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -160,6 +189,12 @@ export interface Transaction {
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
     executeBatch(query: string, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
     sequentially(query: string, params: QueryParams, rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    /**
+     * Run `query` inside this transaction and return an object-mode
+     * Readable emitting one row per chunk, with backpressure. The
+     * transaction is NOT committed when the stream ends.
+     */
+    queryStream(query: string, params?: QueryParams, options?: QueryStreamOptions): Readable;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
@@ -231,6 +266,26 @@ export interface Options {
      * per-query `namedPlaceholders: false` override.
      */
     namedPlaceholders?: boolean;
+    /**
+     * Qualify object-row keys by source table (same option as mysql2), so
+     * JOINed columns with the same name stop overwriting each other:
+     * `true` nests each row as `row[table][column]`; a string separator
+     * flattens to `row['table' + sep + 'column']`. See
+     * `QueryOptions.nestTables` for the exact key rules. Applies wherever
+     * object rows are produced (query / sequentially / queryStream);
+     * array rows (execute) are unaffected. Overridable per query.
+     */
+    nestTables?: boolean | string;
+    /**
+     * TCP keepalive probing to detect dead/stale connections (same option
+     * names as mysql2). On by default; set false to disable.
+     */
+    enableKeepAlive?: boolean;
+    /**
+     * Milliseconds a socket must be idle before the first TCP keepalive
+     * probe is sent (default 60000). Ignored when enableKeepAlive is false.
+     */
+    keepAliveInitialDelay?: number;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;
@@ -262,11 +317,11 @@ export interface Options {
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
-     * Sets the session's current schema at connection time.  Equivalent to
-     * executing `SET SCHEMA <name>` immediately after connecting.
-     *
-     * Unqualified object references (tables, procedures, etc.) that do not
-     * match any schema in the `searchPath` fall back to `PUBLIC`.
+     * Sets the session's current schema at connection time. `CURRENT_SCHEMA`
+     * in Firebird is the first existing schema of the search path, so this
+     * option is implemented by putting the schema at the front of the
+     * `searchPath` sent to the server (with `PUBLIC` kept as a fallback when
+     * no explicit `searchPath` is given).
      *
      * Example: `defaultSchema: 'myapp'`
      */
@@ -288,6 +343,18 @@ export interface Options {
      * (typically `PUBLIC` then `SYSTEM`).
      */
     searchPath?: string | string[];
+    /**
+     * **Firebird 6.0+ only**
+     *
+     * Owner of a newly created database (`isc_dpb_owner`), allowing a
+     * superuser to create a database owned by another user
+     * ([firebird#7718](https://github.com/FirebirdSQL/firebird/issues/7718)).
+     * Only honored by `create`/`attachOrCreate` when the database is
+     * created; ignored on plain attach and by older servers.
+     *
+     * Example: `owner: 'APP_OWNER'`
+     */
+    owner?: string;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *
@@ -296,7 +363,55 @@ export interface Options {
      * text/BLOB columns back into JavaScript objects/arrays.
      */
     jsonAsObject?: boolean;
+    /**
+     * Custom type parser (mysql2-style). Called for every column value of
+     * every result row (including NULLs); whatever it returns becomes the
+     * value in the row. Call `next()` to get the value the driver would
+     * produce by default (after `blobAsText`/`jsonAsObject` are applied).
+     *
+     * ```js
+     * typeCast: (column, next) =>
+     *     column.typeName === 'INT64' ? Number(next()) : next()
+     * ```
+     *
+     * Non-text BLOB columns reach the hook as the usual fetch function;
+     * text BLOBs with `blobAsText` reach it as the resolved string. The
+     * hook must be a pure function: a row can be decoded more than once
+     * when a response spans TCP packets.
+     */
+    typeCast?: TypeCastFunction;
+    /**
+     * Per-connection LRU cache of prepared statements (like mysql2's
+     * statement cache). `db.query`/`tx.query` and friends transparently
+     * reuse the prepared handle for a repeated SQL string, skipping the
+     * prepare round-trip on hot paths. The number is the maximum of idle
+     * cached statements; least-recently-used ones are dropped over the
+     * limit. 0 / unset = disabled. Statements that failed and DDL are
+     * never cached; concurrent runs of the same SQL never share a
+     * statement (extra preparations are simply not cached).
+     */
+    statementCacheSize?: number;
 }
+/** Column metadata passed to the {@link Options.typeCast} hook. */
+export interface TypeCastColumn {
+    /** Firebird SQL type code (see the exported `SQL_TYPES` map). */
+    type: number;
+    /** Friendly name of the type code: 'VARYING', 'INT64', 'BLOB', ... */
+    typeName: string;
+    /** Column subtype (e.g. 1 = text for BLOBs; charset id for strings). */
+    subType?: number;
+    /** Negative decimal scale for NUMERIC/DECIMAL columns (e.g. -2). */
+    scale?: number;
+    /** Declared length in bytes. */
+    length?: number;
+    /** Column name in the table. */
+    field?: string;
+    /** Table (relation) name. */
+    relation?: string;
+    /** Alias used in the SELECT list (the row key for object rows). */
+    alias?: string;
+}
+export type TypeCastFunction = (column: TypeCastColumn, next: () => any) => any;
 export interface SvcMgrOptions extends Options {
     manager: true;
 }
@@ -506,4 +621,49 @@ export interface ServiceManager {
     hasRunningAction(options: ReadableOptions, callback: ReadableCallback): void;
     readusers(options: ReadableOptions, callback: ReadableCallback): void;
     readlimbo(options: ReadableOptions, callback: ReadableCallback): void;
+    detachAsync(force?: boolean): Promise<void>;
+    backupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    nbackupAsync(options: BackupOptions): Promise<NodeJS.ReadableStream>;
+    restoreAsync(options: RestoreOptions): Promise<NodeJS.ReadableStream>;
+    nrestoreAsync(options: NRestoreOptions): Promise<NodeJS.ReadableStream>;
+    setDialectAsync(db: string, dialect: 1 | 3): Promise<NodeJS.ReadableStream>;
+    setSweepintervalAsync(db: string, interval: number): Promise<any>;
+    setCachebufferAsync(db: string, nbpages: any): Promise<NodeJS.ReadableStream>;
+    BringOnlineAsync(db: string): Promise<NodeJS.ReadableStream>;
+    ShutdownAsync(db: string, kind: ShutdownKind, delay: number, mode?: ShutdownMode): Promise<NodeJS.ReadableStream>;
+    setShadowAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setForcewriteAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReservespaceAsync(db: string, val: boolean): Promise<NodeJS.ReadableStream>;
+    setReadonlyModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    setReadwriteModeAsync(db: string): Promise<NodeJS.ReadableStream>;
+    validateAsync(options: ValidateOptions): Promise<NodeJS.ReadableStream>;
+    commitAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    rollbackAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    recoverAsync(db: string, transactid: number): Promise<NodeJS.ReadableStream>;
+    getStatsAsync(options: StatsOptions): Promise<NodeJS.ReadableStream>;
+    getLogAsync(options: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    getUsersAsync(username?: string | null): Promise<ServerInfo>;
+    addUserAsync(username: string, password: string, info?: UserInfo): Promise<NodeJS.ReadableStream>;
+    editUserAsync(username: string, info: UserInfo): Promise<NodeJS.ReadableStream>;
+    removeUserAsync(username: string, rolename?: string | null): Promise<NodeJS.ReadableStream>;
+    getFbserverInfosAsync(infos?: ServerInfoReq, options?: {
+        buffersize?: number;
+        timeout?: number;
+    }): Promise<ServerInfo>;
+    startTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    suspendTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    resumeTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    stopTraceAsync(options: TraceOptions): Promise<NodeJS.ReadableStream>;
+    getTraceListAsync(options?: ReadableOptions): Promise<NodeJS.ReadableStream>;
+    readlineAsync(options?: ReadableOptions): Promise<{
+        result: number;
+        line: string;
+    }>;
+    readeofAsync(options?: ReadableOptions): Promise<{
+        result: number;
+        line: string;
+    }>;
+    hasRunningActionAsync(options?: ReadableOptions): Promise<any>;
+    readusersAsync(options?: ReadableOptions): Promise<any>;
+    readlimboAsync(options?: ReadableOptions): Promise<any>;
 }

package/lib/uri.js

@@ -15,14 +15,14 @@ exports.normalizeOptions = normalizeOptions;
  */
 const BOOLEAN_KEYS = new Set([
     'lowercase_keys', 'blobAsText', 'wireCompression', 'manager',
-    'namedPlaceholders',
+    'namedPlaceholders', 'enableKeepAlive',
 ]);
 /** Option keys coerced to number when they arrive as URI query parameters. */
 const NUMBER_KEYS = new Set([
     'port', 'pageSize', 'timeout', 'retryConnectionInterval',
     'blobChunkSize', 'blobReadChunkSize', 'wireCrypt', 'parallelWorkers',
     'maxInlineBlobSize', 'maxNegotiatedProtocols', 'connectTimeout',
-    'min', 'idleTimeoutMillis',
+    'min', 'idleTimeoutMillis', 'keepAliveInitialDelay',
 ]);
 function coerce(key, value) {
     if (BOOLEAN_KEYS.has(key)) {