node-firebird 2.10.0 → 2.12.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, 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
+- [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), statement timeouts, scrollable cursors, RETURNING multiple rows, SKIP LOCKED, advanced pooling
 - [Using node-firebird with Express.js](#using-node-firebird-with-expressjs)
 - [FAQ](#faq)
@@ -154,6 +154,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 = {};
 
@@ -185,6 +193,8 @@ options.searchPath = undefined; // optional; ordered list/array of schemas to re
 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.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)
 ```
@@ -292,9 +302,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'));
@@ -317,6 +329,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.
@@ -452,6 +470,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`
@@ -492,6 +567,120 @@ 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).
+
+### 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
@@ -964,6 +1153,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)`.
@@ -1015,6 +1239,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();
 });
 ```

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;