node-firebird 2.10.0 → 2.12.0

package/src/types.ts

@@ -6,6 +6,9 @@
 // published declaration files.
 
 import type { Readable } from 'stream';
+import type { SqlTag } from './sql-template';
+
+export type { SqlTag, SqlQuery, SqlIdentifier, CompiledQuery } from './sql-template';
 
 export type DatabaseCallback = (err: any, db: Database) => void;
 export type TransactionCallback = (err: any, transaction: Transaction) => void;
@@ -127,6 +130,85 @@ 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;
+    /**
+     * Per-query override of the `transformKeys` connection option: rewrite
+     * object-row keys — `'camel'` turns `FIRST_NAME` into `firstName`, or
+     * pass a custom `(key) => key` mapper. Applied after `lowercase_keys`
+     * and to both parts of `nestTables` keys. Column metadata (`fields`,
+     * typeCast) keeps the raw server aliases.
+     */
+    transformKeys?: 'camel' | ((key: string) => string);
+    /**
+     * Deliver a full result object `{ rows, fields, affectedRows,
+     * recordCounts, warnings }` instead of the bare rows (callback and
+     * promise APIs). For DML, `affectedRows` is what the server actually
+     * changed (`isc_info_sql_records`, one extra lightweight info request
+     * per statement — hence opt-in) and `recordCounts` breaks it down per
+     * verb; for SELECT it is the number of rows returned (pg's `rowCount`
+     * convention) with no extra round-trip. `warnings` carries any
+     * `isc_arg_warning` entries from the execute response. Honoured by
+     * query/execute and their *Async wrappers only — ignored by the
+     * streaming APIs (sequentially/queryStream, where rows bypass the
+     * result) and executeBatch (which has its own completion shape).
+     */
+    withMeta?: boolean;
+}
+
+/** Column metadata delivered in withMeta results (`fields`) — the same
+ *  vocabulary the typeCast hook receives, plus nullable and the relation
+ *  alias/schema. */
+export interface FieldMetadata {
+    type: number;
+    typeName: string;
+    subType?: number;
+    scale?: number;
+    length?: number;
+    nullable?: boolean;
+    field?: string;
+    relation?: string;
+    relationAlias?: string;
+    relationSchema?: string;
+    alias?: string;
+}
+
+/** Per-verb server row counts of an executed DML statement. */
+export interface RecordCounts {
+    selectCount: number;
+    insertCount: number;
+    updateCount: number;
+    deleteCount: number;
+}
+
+/** An isc_arg_warning entry from a server response ('warning' driver event
+ *  and withMeta `warnings`). */
+export interface ServerWarning {
+    gdscode: number;
+    params?: (string | number)[];
+    message: string;
+}
+
+/** Full result shape delivered when `withMeta: true` is set. */
+export interface QueryResult<T = any> {
+    /** Rows array (SELECT), single row object (RETURNING / procedures), or undefined (plain DML). */
+    rows: T[] | T | undefined;
+    fields: FieldMetadata[];
+    /** DML: rows the server changed; SELECT: rows returned. */
+    affectedRows: number;
+    /** Set for DML statements only. */
+    recordCounts?: RecordCounts;
+    warnings: ServerWarning[];
 }
 
 export type QueryStreamOptions = QueryOptions & {
@@ -140,6 +222,13 @@ export type QueryStreamOptions = QueryOptions & {
 }
 
 export interface Database {
+    /**
+     * Tagged-template query API (Postgres.js-style): interpolated values
+     * become positional parameters, `sql('NAME')` quotes an identifier,
+     * embedded `sql` fragments compose, arrays expand to `?, ?, ?` lists.
+     * The returned query is a lazy thenable — it executes once, on await.
+     */
+    sql: SqlTag;
     detach(callback?: SimpleCallback): Database;
     transaction(options: TransactionOptions|Isolation|TransactionCallback, callback?: TransactionCallback): Database;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
@@ -164,8 +253,11 @@ export interface Database {
     createSchema(schemaName: string, tablespaceName?: string | QueryCallback, callback?: QueryCallback): Database;
 
     // Promise / async-await API (see README § Promises / async–await).
-    // Result metadata is only available through the callback API.
+    // Pass { withMeta: true } to resolve with the full QueryResult
+    // (rows + fields + affectedRows + warnings) instead of bare rows.
+    queryAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & { withMeta: true }): Promise<QueryResult<T>>;
     queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & { withMeta: true }): Promise<QueryResult<T>>;
     executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
     executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
@@ -189,6 +281,14 @@ export interface Database {
 }
 
 export interface Transaction {
+    /** Tagged-template query API running inside this transaction (see Database.sql). */
+    sql: SqlTag;
+    /**
+     * Run `work` inside a savepoint: released on resolve, rolled back TO
+     * (undoing only work's changes) on reject — the transaction stays
+     * usable either way. Nestable.
+     */
+    savepoint<T>(work: (transaction: Transaction) => Promise<T> | T): Promise<T>;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
     query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
@@ -207,7 +307,9 @@ export interface Transaction {
     rollbackRetaining(callback?: SimpleCallback): void;
 
     // Promise / async-await API
+    queryAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & { withMeta: true }): Promise<QueryResult<T>>;
     queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
+    executeAsync<T = any>(query: string, params: QueryParams | undefined, options: QueryOptions & { withMeta: true }): Promise<QueryResult<T>>;
     executeAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<T[]>;
     executeBatchAsync(query: string, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     sequentiallyAsync(query: string, params: QueryParams | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
@@ -314,6 +416,24 @@ 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;
+    /**
+     * Rewrite object-row keys (Postgres.js `transform` counterpart):
+     * `'camel'` turns `FIRST_NAME` into `firstName`, or pass a custom
+     * `(key) => key` mapper. Applied after `lowercase_keys` and to both
+     * parts of `nestTables` keys; column metadata keeps raw aliases.
+     * Overridable per query.
+     */
+    transformKeys?: 'camel' | ((key: string) => string);
     /**
      * TCP keepalive probing to detect dead/stale connections (same option
      * names as mysql2). On by default; set false to disable.
@@ -352,6 +472,20 @@ export interface Options {
      * Default 0 (idle connections are kept forever).
      */
     idleTimeoutMillis?: number;
+    /**
+     * Pool only: retire a physical connection after this many checkouts
+     * (pg's `maxUses`) — it is closed for good when returned to the pool
+     * and replaced on demand. Bounds server-side resource drift on
+     * long-lived connections. Default 0 (unlimited uses).
+     */
+    maxUses?: number;
+    /**
+     * Pool only: retire a physical connection this many milliseconds after
+     * it was created (Postgres.js's `max_lifetime`), on return to the pool
+     * or by the idle sweep — even below `min`; replacements are created on
+     * demand. Default 0 (unlimited lifetime).
+     */
+    maxLifetimeMillis?: number;
     /**
      * **Firebird 6.0+ only (Protocol 20+)**
      *

package/src/uri.ts

@@ -198,7 +198,59 @@ export function parseConnectionString(str: string): Options {
  */
 export function normalizeOptions<T>(options: T | string): T {
     if (typeof options === 'string') {
-        return parseConnectionString(options) as T;
+        options = parseConnectionString(options) as T;
     }
-    return options;
+    return applyEnvDefaults(options as any);
+}
+
+/**
+ * Fall back to environment variables for connection settings the caller
+ * did not provide — the pg-style convention using Firebird's own names:
+ * ISC_USER / ISC_PASSWORD (honoured by isql and every official tool) plus
+ * FIREBIRD_HOST / FIREBIRD_PORT / FIREBIRD_DATABASE / FIREBIRD_ROLE.
+ * Explicit options always win; the driver's built-in defaults (SYSDBA /
+ * masterkey / 127.0.0.1) still apply when neither is set. A fresh object
+ * is returned so caller-owned options objects are never mutated.
+ */
+const ENV_FALLBACKS: [string, string][] = [
+    ['user', 'ISC_USER'],
+    ['password', 'ISC_PASSWORD'],
+    ['host', 'FIREBIRD_HOST'],
+    ['port', 'FIREBIRD_PORT'],
+    ['database', 'FIREBIRD_DATABASE'],
+    ['role', 'FIREBIRD_ROLE'],
+];
+
+function applyEnvDefaults<T extends Record<string, any>>(options: T): T {
+    let out: any = options;
+    for (const [key, envName] of ENV_FALLBACKS) {
+        const value = process.env[envName];
+        // empty-string env vars (common in CI: `export ISC_PASSWORD=`)
+        // count as unset
+        if (value === undefined || value === '') {
+            continue;
+        }
+        // a service-manager connection's `database` selects the TARGET of
+        // backup/restore — never let a leftover env var pick that silently
+        if (key === 'database' && (options as any).manager) {
+            continue;
+        }
+        if (out[key] === undefined || out[key] === null || out[key] === '') {
+            if (out === options) {
+                out = { ...(options as any) };
+            }
+            if (key === 'port') {
+                const port = Number(value);
+                if (!Number.isFinite(port) || port <= 0) {
+                    // NaN is falsy: it would silently fall back to 3050
+                    // downstream instead of surfacing the typo
+                    throw new Error('Invalid FIREBIRD_PORT environment variable: ' + value);
+                }
+                out[key] = port;
+            } else {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
 }

package/src/wire/connection.ts

@@ -75,31 +75,8 @@ function statementCacheLimit(options: InternalOptions): number {
     return 0;
 }
 
-const SQL_TYPE_NAMES: Record<number, string> = {
-    [Const.SQL_TEXT]: 'TEXT',
-    [Const.SQL_VARYING]: 'VARYING',
-    [Const.SQL_SHORT]: 'SHORT',
-    [Const.SQL_LONG]: 'LONG',
-    [Const.SQL_FLOAT]: 'FLOAT',
-    [Const.SQL_DOUBLE]: 'DOUBLE',
-    [Const.SQL_D_FLOAT]: 'D_FLOAT',
-    [Const.SQL_TIMESTAMP]: 'TIMESTAMP',
-    [Const.SQL_BLOB]: 'BLOB',
-    [Const.SQL_ARRAY]: 'ARRAY',
-    [Const.SQL_QUAD]: 'QUAD',
-    [Const.SQL_TYPE_TIME]: 'TIME',
-    [Const.SQL_TYPE_DATE]: 'DATE',
-    [Const.SQL_INT64]: 'INT64',
-    [Const.SQL_INT128]: 'INT128',
-    [Const.SQL_TIMESTAMP_TZ]: 'TIMESTAMP_TZ',
-    [Const.SQL_TIMESTAMP_TZ_EX]: 'TIMESTAMP_TZ_EX',
-    [Const.SQL_TIME_TZ]: 'TIME_TZ',
-    [Const.SQL_TIME_TZ_EX]: 'TIME_TZ_EX',
-    [Const.SQL_DEC16]: 'DEC16',
-    [Const.SQL_DEC34]: 'DEC34',
-    [Const.SQL_BOOLEAN]: 'BOOLEAN',
-    [Const.SQL_NULL]: 'NULL',
-};
+// SQL type-code names live in xsqlvar.ts alongside the descriptors
+const SQL_TYPE_NAMES = Xsql.SQL_TYPE_NAMES;
 
 /**
  * Run the user's typeCast hook (options.typeCast) for one column value.
@@ -114,16 +91,7 @@ function applyTypeCast(options: InternalOptions, meta: Partial<Xsql.SQLVarBase>,
     if (typeof typeCast !== 'function') {
         return defaultValue;
     }
-    const column = {
-        type: meta.type!,
-        typeName: SQL_TYPE_NAMES[meta.type!] || 'UNKNOWN',
-        subType: meta.subType,
-        scale: meta.scale,
-        length: meta.length,
-        field: meta.field,
-        relation: meta.relation,
-        alias: meta.alias,
-    };
+    const column = Xsql.describeField(meta);
     // A hook exception must never escape into the row-decode loop: there it
     // would be mistaken for an incomplete packet and desync the response
     // queue (the same failure mode as issue #341). Fall back to the default
@@ -456,13 +424,38 @@ class Connection {
                             self._queue.length, self._pending.length, xdr.pos);
                     }
 
+                    // Surface isc_arg_warning entries (parsed since 2.10.0 but
+                    // dropped here): resolve their message text and emit them on
+                    // the Database on the next tick, so a listener registered
+                    // inside this very response's callback (e.g. right after
+                    // attach) still receives them.
+                    if (obj && obj.warnings && obj.warnings.length && self.db && typeof self.db.emit === 'function') {
+                        const warnings = obj.warnings;
+                        for (const w of warnings) {
+                            if (w.message === undefined) {
+                                w.message = lookupMessages([w]);
+                                if (!w.message || w.message === 'Unknow error') {
+                                    // codes newer than the bundled firebird.msg:
+                                    // still say something actionable
+                                    w.message = 'Firebird warning ' + w.gdscode +
+                                        (w.params && w.params.length ? ': ' + w.params.join(', ') : '');
+                                }
+                            }
+                        }
+                        process.nextTick(function () {
+                            for (const w of warnings) {
+                                self.db.emit('warning', w);
+                            }
+                        });
+                    }
+
                     if (obj && obj.status) {
                         obj.message = lookupMessages(obj.status);
                         doCallback(obj, cb);
                     } else {
                         doCallback(obj, cb);
                     }
-    
+
                 });
     
                 if (xdr.pos === 0) {
@@ -1984,6 +1977,34 @@ class Connection {
     }
 
 
+    /**
+     * Query runtime information about a prepared statement via op_info_sql
+     * (e.g. Const.RECORDS_INFO for the per-verb DML row counts). The
+     * response is a plain op_response whose buffer holds the info clusters.
+     */
+    statementInfo(statement: Statement, items: number[], callback?: QueueCallback) {
+        if (this._isClosed)
+            return this.throwClosed(callback);
+
+        this._pending.push('statementInfo');
+
+        var msg = this._msg;
+        var blr = this._blr;
+        msg.pos = 0;
+        blr.pos = 0;
+
+        blr.addBytes(items);
+
+        msg.addInt(Const.op_info_sql);
+        msg.addInt(statement.handle);
+        msg.addInt(0); // incarnation
+        msg.addBlr(blr);
+        msg.addInt(65535); // buffer_length
+
+        this._queueEvent(callback);
+    }
+
+
     fetchAll(statement: Statement, transaction: Transaction, callback: Callback<any[]>) {
         const self = this;
         const custom = statement.options || {};
@@ -2015,7 +2036,9 @@ class Connection {
                 readBlobsSequentially(0, []).then((arrBlob: any) => {
                     for (let i = 0; i < arrBlob.length; i++) {
                         const blob = arrBlob[i];
-                        ret.data[blob.row][blob.column] = applyTypeCast(
+                        // nestTables === true rows: the value lives in the
+                        // per-table sub-object, not on the row itself
+                        Xsql.nestCell(ret.data[blob.row], blob.table)[blob.column] = applyTypeCast(
                             statement.connection.options, blob.meta || {},
                             parseValueIfJson(blob.value, statement.connection.options));
                     }
@@ -2469,6 +2492,7 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                 delete data.frow;
                 delete data.frows;
                 delete data.fcols;
+                delete data.ftables;
 
                 if (isOpFetch && data.fop) { // could be set when a packet is not complete
                     data.readBuffer(68); // ??
@@ -2490,10 +2514,13 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                 data.frows = data.frows || [];
 
                 if (custom.asObject && !data.fcols) {
-                    if (lowercase_keys) {
-                        data.fcols = output.map((column: any) => column.alias.toLowerCase());
-                    } else {
-                        data.fcols = output.map((column: any) => column.alias);
+                    const nest = Xsql.resolveNestTables(custom, cnx.options);
+                    const transform = Xsql.resolveKeyTransform(custom, cnx.options);
+                    const columnKeys = Xsql.computeColumnKeys(output, nest, lowercase_keys, transform);
+                    data.fcols = columnKeys.map((k) => k.key);
+                    if (nest === true) {
+                        // computeColumnKeys always sets table when nesting
+                        data.ftables = columnKeys.map((k) => k.table!);
                     }
                 }
 
@@ -2521,7 +2548,10 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
 
                         if (!lowerV13 && nullBitSet!.get(data.fcolumn)) {
                             const nullKey = custom.asObject ? data.fcols![data.fcolumn!] : data.fcolumn;
-                            data.frow[nullKey] = applyTypeCast(cnx.options, item, null);
+                            // ftables is only set when nestTables === true, so
+                            // the default path writes straight into the row
+                            (data.ftables ? Xsql.nestCell(data.frow, data.ftables[data.fcolumn!]) : data.frow)[nullKey] =
+                                applyTypeCast(cnx.options, item, null);
 
                             continue;
                         }
@@ -2538,7 +2568,8 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
 
                             if (item.type === Const.SQL_BLOB && value !== null) {
                                 if (item.subType === Const.isc_blob_text && cnx.options.blobAsText) {
-                                    value = fetch_blob_async_transaction(statement, value, key, row, item);
+                                    value = fetch_blob_async_transaction(statement, value, key, row, item,
+                                        data.ftables && data.ftables[data.fcolumn!]);
                                     arrBlob.push(value);
                                     pendingTextBlob = true;
                                 } else {
@@ -2546,7 +2577,7 @@ function decodeResponse(data: XdrReader, callback: QueueCallback | undefined, cn
                                 }
                             }
 
-                            data.frow[key] = pendingTextBlob
+                            (data.ftables ? Xsql.nestCell(data.frow, data.ftables[data.fcolumn!]) : data.frow)[key] = pendingTextBlob
                                 ? value
                                 : applyTypeCast(cnx.options, item, parseValueIfJson(value, cnx.options));
                         } catch (e) {
@@ -3475,8 +3506,8 @@ function CalcBlr(blr: BlrWriter, xsqlda: any[]) {
     blr.addByte(Const.blr_eoc);
 }
 
-function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase) {
-    const infoValue = { row, column, value: '', meta };
+function fetch_blob_async_transaction(statement: Statement, id: Quad, column: string | number, row: number, meta?: Xsql.SQLVarBase, table?: string) {
+    const infoValue = { row, column, value: '', meta, table };
 
     return (transactionArg: any) => {
         const cacheKey = `${id.high}:${id.low}`;

package/src/wire/const.ts

@@ -587,6 +587,12 @@ const sqlInfo = {
     isc_info_sql_stmt_type : 21,
     isc_info_sql_get_plan : 22,
     isc_info_sql_records : 23,
+    // per-verb row counts nested inside an isc_info_sql_records cluster
+    // (inf_pub.h isc_info_req_*)
+    isc_info_req_select_count : 13,
+    isc_info_req_insert_count : 14,
+    isc_info_req_update_count : 15,
+    isc_info_req_delete_count : 16,
     isc_info_sql_batch_fetch : 24,
     isc_info_sql_relation_alias : 25, // >: 2.0
     isc_info_sql_explain_plan : 26, // >= 3.0
@@ -626,6 +632,7 @@ const DESCRIBE = [
     sqlInfo.isc_info_sql_length,
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
+    sqlInfo.isc_info_sql_relation_alias, // FB 2.0+: query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -654,6 +661,7 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_field,
     sqlInfo.isc_info_sql_relation,
     sqlInfo.isc_info_sql_relation_schema, // FB 6.0: schema of source relation
+    sqlInfo.isc_info_sql_relation_alias, // query alias of the source relation (nestTables)
     //isc_info_sql_owner,
     sqlInfo.isc_info_sql_alias,
     sqlInfo.isc_info_sql_describe_end,
@@ -667,6 +675,12 @@ const DESCRIBE_WITH_SCHEMA = [
     sqlInfo.isc_info_sql_describe_end
 ];
 
+// op_info_sql request for the per-verb DML row counts of an executed
+// statement (withMeta / affectedRows).
+const RECORDS_INFO = [
+    sqlInfo.isc_info_sql_records,
+];
+
 /***********************/
 /*   ISC Services      */
 /***********************/
@@ -908,6 +922,7 @@ const Const = Object.freeze({
     ...defaultOptions,
     DESCRIBE,
     DESCRIBE_WITH_SCHEMA,
+    RECORDS_INFO,
     ...dpb,
     ...dsql,
     ...fetchOp,

package/src/wire/database.ts

@@ -2,6 +2,8 @@ import Events from 'events';
 import { doError, fromCallback, type Callback, type SimpleCallback } from '../callback';
 import { escape } from '../utils';
 import Const from './const';
+import { makeSqlTag, type SqlTag } from '../sql-template';
+import { computeColumnKeys, nestCell, resolveKeyTransform, resolveNestTables } from './xsqlvar';
 import EventConnection from './eventConnection';
 import FbEventManager from './fbEventManager';
 import makeQueryStream from './query-stream';
@@ -94,35 +96,47 @@ function readblob(blob: any, callback: Callback): void {
     });
 }
 
-function fetchBlobSyncRow(row: any, meta: any[], callback: Callback): void {
-    if (!row || !meta || !meta.length) {
+function fetchBlobSyncRow(row: any, meta: any[], nestTables: boolean | string | undefined, lowercaseKeys: boolean | undefined, transform: ((key: string) => string) | undefined, callback: Callback): void {
+    if (!row || !meta || !meta.length || !meta.some((m) => m && m.type === Const.SQL_BLOB)) {
         callback(null, row);
         return;
     }
 
-    const rowKeys = Object.keys(row);
-    const blobColumns: string[] = [];
+    // locate blob cells by the same key computation the fetch decoder used,
+    // rather than assuming Object.keys(row) is index-aligned with meta —
+    // duplicate JOIN column names (and nested rows) break that alignment.
+    // Array rows (sequentially's legacy boolean form) are keyed by index.
+    const isArrayRow = Array.isArray(row);
+    const keys = isArrayRow ? null : computeColumnKeys(meta, nestTables, lowercaseKeys, transform);
+    const blobCells: { target: any; key: string | number }[] = [];
 
     for (let i = 0; i < meta.length; i++) {
-        if (meta[i] && meta[i].type === Const.SQL_BLOB && rowKeys[i] !== undefined) {
-            blobColumns.push(rowKeys[i]);
+        if (!meta[i] || meta[i].type !== Const.SQL_BLOB) {
+            continue;
+        }
+        const target = keys ? nestCell(row, keys[i].table) : row;
+        const key = keys ? keys[i].key : i;
+        // duplicate aliases collapse onto one cell — read it only once
+        if (typeof target[key] === 'function' &&
+            !blobCells.some((cell) => cell.target === target && cell.key === key)) {
+            blobCells.push({ target, key });
         }
     }
 
-    if (!blobColumns.length) {
+    if (!blobCells.length) {
         callback(null, row);
         return;
     }
 
-    let pending = blobColumns.length;
+    let pending = blobCells.length;
     let blobErr: any;
 
-    blobColumns.forEach(function(columnName) {
-        readblob(row[columnName], function(err: any, data: any) {
+    blobCells.forEach(function(cell) {
+        readblob(cell.target[cell.key], function(err: any, data: any) {
             if (err && !blobErr) {
                 blobErr = err;
             }
-            row[columnName] = data;
+            cell.target[cell.key] = data;
             pending--;
             if (pending === 0) {
                 callback(blobErr, row);
@@ -134,6 +148,7 @@ function fetchBlobSyncRow(row: any, meta: any[], callback: Callback): void {
 class Database extends Events.EventEmitter {
     connection: Connection;
     eventid: number;
+    private _sql?: SqlTag;
 
     constructor(connection: Connection) {
         super();
@@ -142,6 +157,17 @@ class Database extends Events.EventEmitter {
         this.eventid = 1;
     }
 
+    /**
+     * Tagged-template query API: db.sql`SELECT ... ${value}` (see README).
+     * Built lazily on first access; the compiled text is positional-only,
+     * so the namedPlaceholders rewriter is disabled — any `:token` in the
+     * template is PSQL (EXECUTE BLOCK), not a placeholder.
+     */
+    get sql(): SqlTag {
+        return this._sql || (this._sql = makeSqlTag((text, params, options) =>
+            this.queryAsync(text, params, { ...options, namedPlaceholders: false })));
+    }
+
     escape(value: any): string {
         return escape(value, this.connection.accept.protocolVersion);
     }
@@ -312,6 +338,9 @@ class Database extends Events.EventEmitter {
         }
 
         var self = this;
+        var keyResolutionDone = false;
+        var resolvedNest: boolean | string | undefined;
+        var resolvedTransform: ((key: string) => string) | undefined;
         var _on = function(row: any, i: number, meta: any[], next: (err?: any) => void) {
             var done = false;
             var finish = function(err?: any) {
@@ -322,7 +351,15 @@ class Database extends Events.EventEmitter {
                 next(err);
             };
 
-            fetchBlobSyncRow(row, meta, function(blobErr: any) {
+            // options is read at call time, after the normalization below;
+            // both values are query-invariant, so resolve them once on the
+            // first row instead of allocating per row
+            if (!keyResolutionDone) {
+                resolvedNest = resolveNestTables(options as any, self.connection.options);
+                resolvedTransform = resolveKeyTransform(options as any, self.connection.options);
+                keyResolutionDone = true;
+            }
+            fetchBlobSyncRow(row, meta, resolvedNest, self.connection._lowercase_keys, resolvedTransform, function(blobErr: any) {
                 if (blobErr) {
                     finish(blobErr);
                     return;
@@ -537,8 +574,9 @@ class Database extends Events.EventEmitter {
     /*
      * Promise / async-await API.
      * Each *Async method wraps its callback counterpart; the callback API
-     * stays untouched. Result metadata is only available through the
-     * callback API — the promises resolve with the rows alone.
+     * stays untouched. The promises resolve with the rows alone unless
+     * { withMeta: true } is passed, which resolves the full
+     * { rows, fields, affectedRows, recordCounts, warnings } result.
      */
 
     queryAsync(query: string, params?: QueryParams, options?: InternalQueryOptions): Promise<any[]> {

package/src/wire/serialize.ts

@@ -197,7 +197,11 @@ export class BlrReader {
                 value = this.buffer.readInt16LE(this.pos);
                 break;
             case 4:
-                value = this.buffer.readInt32LE(this.pos)
+                value = this.buffer.readInt32LE(this.pos);
+                break;
+            case 8:
+                // e.g. record counts above 2^31 (isc_info_sql_records)
+                value = Number(this.buffer.readBigInt64LE(this.pos));
         }
         this.pos += len;
         return value;
@@ -440,8 +444,10 @@ export class XdrReader {
     frow?: any;
     /** rows decoded so far in this call */
     frows?: any[];
-    /** cached object-row keys (column aliases) */
+    /** cached object-row keys (column aliases, qualified when nestTables is set) */
     fcols?: string[];
+    /** cached per-column table keys when nestTables === true */
+    ftables?: string[];
 
     constructor(buffer: Buffer) {
         this.buffer = buffer;