node-firebird 2.8.1 → 2.9.0

package/README.md

@@ -11,9 +11,9 @@
 - [Installation](#installation)
 - [Usage](#usage) — including [developing the driver](#developing-the-driver)
 - [Promises and async/await](#promises-and-asyncawait) — the `*Async` API plus `withConnection` / `withTransaction` helpers
-- [Connection types](#connection-types) — connection options, classic connections, pooling
+- [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, 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, 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)
@@ -180,8 +180,69 @@ options.maxNegotiatedProtocols = 10; // optional; limit maximum protocol version
 options.defaultSchema = undefined; // optional; sets session CURRENT_SCHEMA at connect time (FB >= 6.0)
 options.searchPath = undefined; // optional; ordered list/array of schemas to resolve unqualified object references (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)
 ```
 
+### Connection URI strings
+
+Everywhere an options object is accepted — `attach`, `create`,
+`attachOrCreate`, `drop`, `Firebird.pool()` and their `*Async`
+counterparts — a `firebird://` URI string works too, which is handy for
+12-factor apps and containers that configure the database via a single
+environment variable:
+
+```js
+const db = await Firebird.attachAsync(process.env.DATABASE_URL);
+// e.g. DATABASE_URL=firebird://SYSDBA:masterkey@db.example.com:3050//var/fb/prod.fdb?encoding=UTF8
+
+const pool = Firebird.pool(10,
+    'firebird://app:secret@localhost/appdb?lowercase_keys=true&idleTimeoutMillis=30000');
+```
+
+The database part after `host[:port]/` can be:
+
+| URI | database |
+| :--- | :--- |
+| `firebird://host/employee` | the alias `employee` |
+| `firebird://host//var/fb/prod.fdb` | `/var/fb/prod.fdb` (explicit absolute path) |
+| `firebird://host/var/fb/prod.fdb` | `/var/fb/prod.fdb` (a database part with `/` is a path — aliases cannot contain slashes) |
+| `firebird://host/C:/fbdata/prod.fdb` | the Windows path `C:/fbdata/prod.fdb` |
+
+Query parameters map 1:1 onto the connection options above and are coerced
+to the right type (`?pageSize=8192&lowercase_keys=true&wireCompression=1`).
+Credentials and paths are URL-decoded, so reserved characters can be
+percent-encoded (`p%40ss` for `p@ss`); `user`/`password` may alternatively
+be passed as query parameters. IPv6 hosts use brackets:
+`firebird://[::1]:3050/employee`. The parser is exported as
+`Firebird.parseConnectionUri(uri)` if you need the resulting options object.
+
+### Traditional connection strings (old style)
+
+The classic Firebird connection string format — the same
+`[host[/port]:]{path | alias}` strings isql and the other Firebird tools
+use — is accepted everywhere too:
+
+```js
+const db = await Firebird.attachAsync('db.example.com/3051:/var/fb/prod.fdb');
+```
+
+| Connection string | meaning |
+| :--- | :--- |
+| `employee` | the alias `employee` on `127.0.0.1:3050` |
+| `/var/fb/prod.fdb` | a path on `127.0.0.1:3050` |
+| `db.example.com:employee` | the alias `employee` on `db.example.com:3050` |
+| `db.example.com/3051:/var/fb/prod.fdb` | host and explicit port |
+| `myserver:C:\fbdata\prod.fdb` | a Windows path behind a host |
+| `C:\fbdata\prod.fdb` | a single character before `:` is a drive letter, not a host (same rule as Firebird) |
+| `[::1]/3050:employee` | IPv6 hosts use brackets |
+
+Unlike `firebird://` URIs, traditional strings carry no credentials or
+options — the driver defaults apply (`SYSDBA`/`masterkey`, port 3050), and
+the port must be numeric (`/etc/services` names are not resolved). Use the
+URI form or an options object when you need to set anything else.
+`Firebird.parseConnectionString(str)` parses both forms and is what
+`attach`/`create`/`pool` use internally for string arguments.
+
 ### Classic
 
 ```js
@@ -385,6 +446,46 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
+### Named placeholders
+
+With the `namedPlaceholders: true` connection option, SQL may use `:name`
+markers and parameters may be passed as a values-by-name object instead of
+a positional array. The rewrite happens client-side before the statement is
+prepared, so it works on every Firebird version; positional `?` arrays keep
+working unchanged on the same connection.
+
+```js
+const db = await Firebird.attachAsync({ ...options, namedPlaceholders: true });
+// or: firebird://user:pass@host/db?namedPlaceholders=true
+
+const rows = await db.queryAsync(
+  'SELECT * FROM USERS WHERE ALIAS = :alias AND CREATED > :since',
+  { alias: 'Peter', since: new Date(2026, 0, 1) });
+
+// A name may repeat — it binds once per occurrence:
+await db.queryAsync(
+  'SELECT * FROM T WHERE A = :v OR B = :v', { v: 42 });
+
+// Batch rows can be objects too (Firebird 4.0+):
+await db.executeBatchAsync(
+  'INSERT INTO USERS (ID, ALIAS) VALUES (:id, :alias)',
+  [{ id: 1, alias: 'a' }, { id: 2, alias: 'b' }]);
+```
+
+Placeholders inside string literals (`'...'`), quoted identifiers (`"..."`),
+comments and `q'{...}'` alternative literals are left untouched. A key
+present with value `null` binds SQL `NULL`; a *missing* key raises
+`Missing value for named placeholder(s): ...`.
+
+The scanner has no SQL grammar, so inside an `EXECUTE BLOCK` body every
+PSQL `:variable` reference looks like a placeholder too. The option is
+therefore off by default — and can be disabled for a single statement with
+the per-query option:
+
+```js
+await db.queryAsync(execBlockSql, [], { namedPlaceholders: false });
+```
+
 ### 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.

package/lib/index.d.ts

@@ -1,5 +1,6 @@
 import Connection from './wire/connection';
 import { escape as escapeValue } from './utils';
+import { parseConnectionUri, parseConnectionString } from './uri';
 import type { Options, SvcMgrOptions, DatabaseCallback, ServiceManagerCallback, SimpleCallback, ConnectionPool, Database, ServiceManager } from './types';
 export * from './types';
 export { GDSCode } from './gdscodes';
@@ -29,14 +30,16 @@ export declare const escape: typeof escapeValue;
  * the connection was stored on the module object itself.
  */
 export declare let connection: Connection | undefined;
-export declare function attach(options: Options, callback: DatabaseCallback): void;
+export declare function attach(options: Options | string, callback: DatabaseCallback): void;
 export declare function attach(options: SvcMgrOptions, callback: ServiceManagerCallback): void;
-export declare function drop(options: Options, callback: SimpleCallback): void;
-export declare function create(options: Options, callback: DatabaseCallback): void;
-export declare function attachOrCreate(options: Options, callback: DatabaseCallback): void;
-export declare function pool(max: number, options: Options): ConnectionPool;
+export declare function drop(options: Options | string, callback: SimpleCallback): void;
+export declare function create(options: Options | string, callback: DatabaseCallback): void;
+export declare function attachOrCreate(options: Options | string, callback: DatabaseCallback): void;
+export declare function pool(max: number, options: Options | string): ConnectionPool;
+export { parseConnectionUri, parseConnectionString };
+export { parseNamedPlaceholders } from './named-params';
 export declare function attachAsync(options: SvcMgrOptions): Promise<ServiceManager>;
-export declare function attachAsync(options: Options): Promise<Database>;
-export declare function createAsync(options: Options): Promise<Database>;
-export declare function attachOrCreateAsync(options: Options): Promise<Database>;
-export declare function dropAsync(options: Options): Promise<void>;
+export declare function attachAsync(options: Options | string): Promise<Database>;
+export declare function createAsync(options: Options | string): Promise<Database>;
+export declare function attachOrCreateAsync(options: Options | string): Promise<Database>;
+export declare function dropAsync(options: Options | string): Promise<void>;

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.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.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;
@@ -32,6 +32,9 @@ const callback_1 = require("./callback");
 const connection_1 = __importDefault(require("./wire/connection"));
 const pool_1 = __importDefault(require("./pool"));
 const utils_1 = require("./utils");
+const uri_1 = require("./uri");
+Object.defineProperty(exports, "parseConnectionUri", { enumerable: true, get: function () { return uri_1.parseConnectionUri; } });
+Object.defineProperty(exports, "parseConnectionString", { enumerable: true, get: function () { return uri_1.parseConnectionString; } });
 __exportStar(require("./types"), exports);
 var gdscodes_1 = require("./gdscodes");
 Object.defineProperty(exports, "GDSCode", { enumerable: true, get: function () { return gdscodes_1.GDSCode; } });
@@ -61,6 +64,7 @@ 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;
 function attach(options, callback) {
+    options = (0, uri_1.normalizeOptions)(options);
     var host = options.host || const_1.default.DEFAULT_HOST;
     var port = options.port || const_1.default.DEFAULT_PORT;
     var manager = options.manager || false;
@@ -83,7 +87,7 @@ function attach(options, callback) {
     }, options);
 }
 function drop(options, callback) {
-    attach(options, function (err, db) {
+    attach((0, uri_1.normalizeOptions)(options), function (err, db) {
         if (err) {
             callback({ error: err, message: "Drop error" });
             return;
@@ -92,6 +96,7 @@ function drop(options, callback) {
     });
 }
 function create(options, callback) {
+    options = (0, uri_1.normalizeOptions)(options);
     var host = options.host || const_1.default.DEFAULT_HOST;
     var port = options.port || const_1.default.DEFAULT_PORT;
     var cnx = exports.connection = new connection_1.default(host, port, function (err) {
@@ -112,6 +117,7 @@ function create(options, callback) {
     }, options);
 }
 function attachOrCreate(options, callback) {
+    options = (0, uri_1.normalizeOptions)(options);
     var host = options.host || const_1.default.DEFAULT_HOST;
     var port = options.port || const_1.default.DEFAULT_PORT;
     var cnx = exports.connection = new connection_1.default(host, port, function (err) {
@@ -139,8 +145,10 @@ function attachOrCreate(options, callback) {
 }
 // Pooling
 function pool(max, options) {
-    return new pool_1.default(attach, max, Object.assign({}, options, { isPool: true }));
+    return new pool_1.default(attach, max, Object.assign({}, (0, uri_1.normalizeOptions)(options), { isPool: true }));
 }
+var named_params_1 = require("./named-params");
+Object.defineProperty(exports, "parseNamedPlaceholders", { enumerable: true, get: function () { return named_params_1.parseNamedPlaceholders; } });
 function attachAsync(options) {
     return (0, callback_1.fromCallback)(function (cb) { attach(options, cb); });
 }

package/lib/named-params.d.ts

@@ -0,0 +1,42 @@
+/***************************************
+ *
+ *   Named placeholders (:name → ?)
+ *
+ ***************************************/
+/**
+ * Result of scanning a SQL string for named placeholders.
+ */
+export interface ParsedNamedPlaceholders {
+    /** SQL with every named placeholder replaced by a positional "?". */
+    sql: string;
+    /**
+     * Placeholder names in positional order (a repeated name appears once
+     * per occurrence), or null when the SQL contains none.
+     */
+    names: string[] | null;
+}
+/**
+ * Scan `sql` for named placeholders (`:name`) and rewrite them to positional
+ * `?` markers, returning the rewritten SQL and the names in positional
+ * order. Placeholders inside string literals ('...'), quoted identifiers
+ * ("..."), line comments (--), block comments and Firebird alternative
+ * string literals (q'{...}') are left untouched.
+ *
+ * Note: the scanner has no SQL grammar — inside an EXECUTE BLOCK body every
+ * `:variable` reference looks like a placeholder too. Use positional params
+ * (or per-call `namedPlaceholders: false`) for EXECUTE BLOCK.
+ */
+export declare function parseNamedPlaceholders(sql: string): ParsedNamedPlaceholders;
+/**
+ * True when `params` is a plain values-by-name object (and not one of the
+ * values the driver accepts as a single positional parameter, like Date or
+ * Buffer).
+ */
+export declare function isNamedParamsObject(params: any): params is Record<string, any>;
+/**
+ * Map a values-by-name object onto the positional order collected by
+ * parseNamedPlaceholders. A name may be bound multiple times; every name
+ * must be an own property of `params` (a present key holding null is a
+ * NULL parameter, a missing key is an error).
+ */
+export declare function bindNamedParams(names: string[], params: Record<string, any>): any[];

package/lib/named-params.js

@@ -0,0 +1,133 @@
+"use strict";
+/***************************************
+ *
+ *   Named placeholders (:name → ?)
+ *
+ ***************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNamedPlaceholders = parseNamedPlaceholders;
+exports.isNamedParamsObject = isNamedParamsObject;
+exports.bindNamedParams = bindNamedParams;
+const IDENT_START = /[A-Za-z_]/;
+const IDENT_PART = /[A-Za-z0-9_$]/;
+// Parsing is pure string work, so identical SQL (the common case with
+// query builders and hot paths) is scanned only once.
+const CACHE_MAX = 100;
+const cache = new Map();
+/**
+ * Scan `sql` for named placeholders (`:name`) and rewrite them to positional
+ * `?` markers, returning the rewritten SQL and the names in positional
+ * order. Placeholders inside string literals ('...'), quoted identifiers
+ * ("..."), line comments (--), block comments and Firebird alternative
+ * string literals (q'{...}') are left untouched.
+ *
+ * Note: the scanner has no SQL grammar — inside an EXECUTE BLOCK body every
+ * `:variable` reference looks like a placeholder too. Use positional params
+ * (or per-call `namedPlaceholders: false`) for EXECUTE BLOCK.
+ */
+function parseNamedPlaceholders(sql) {
+    var cached = cache.get(sql);
+    if (cached)
+        return cached;
+    var out = '';
+    var names = [];
+    var i = 0;
+    var n = sql.length;
+    while (i < n) {
+        var c = sql[i];
+        if (c === "'" || c === '"') {
+            // string literal or quoted identifier; doubled quotes escape
+            var quote = c;
+            var end = i + 1;
+            while (end < n) {
+                if (sql[end] === quote) {
+                    if (sql[end + 1] === quote) {
+                        end += 2;
+                        continue;
+                    }
+                    end++;
+                    break;
+                }
+                end++;
+            }
+            out += sql.slice(i, end);
+            i = end;
+        }
+        else if (c === '-' && sql[i + 1] === '-') {
+            var eol = sql.indexOf('\n', i);
+            if (eol === -1)
+                eol = n;
+            out += sql.slice(i, eol);
+            i = eol;
+        }
+        else if (c === '/' && sql[i + 1] === '*') {
+            var close = sql.indexOf('*/', i + 2);
+            close = close === -1 ? n : close + 2;
+            out += sql.slice(i, close);
+            i = close;
+        }
+        else if ((c === 'q' || c === 'Q') && sql[i + 1] === "'" && i + 2 < n &&
+            (i === 0 || !IDENT_PART.test(sql[i - 1]))) {
+            // Firebird 3+ alternative string literal: q'{...}' / q'!...!'
+            var open = sql[i + 2];
+            var closer = open === '(' ? ')'
+                : open === '[' ? ']'
+                    : open === '{' ? '}'
+                        : open === '<' ? '>'
+                            : open;
+            var stop = sql.indexOf(closer + "'", i + 3);
+            stop = stop === -1 ? n : stop + 2;
+            out += sql.slice(i, stop);
+            i = stop;
+        }
+        else if (c === ':' && i + 1 < n && IDENT_START.test(sql[i + 1])) {
+            var end2 = i + 2;
+            while (end2 < n && IDENT_PART.test(sql[end2]))
+                end2++;
+            names.push(sql.slice(i + 1, end2));
+            out += '?';
+            i = end2;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    var result = names.length
+        ? { sql: out, names: names }
+        : { sql: sql, names: null };
+    if (cache.size >= CACHE_MAX) {
+        cache.delete(cache.keys().next().value);
+    }
+    cache.set(sql, result);
+    return result;
+}
+/**
+ * True when `params` is a plain values-by-name object (and not one of the
+ * values the driver accepts as a single positional parameter, like Date or
+ * Buffer).
+ */
+function isNamedParamsObject(params) {
+    return params !== null &&
+        typeof params === 'object' &&
+        !Array.isArray(params) &&
+        !Buffer.isBuffer(params) &&
+        !(params instanceof Date);
+}
+/**
+ * Map a values-by-name object onto the positional order collected by
+ * parseNamedPlaceholders. A name may be bound multiple times; every name
+ * must be an own property of `params` (a present key holding null is a
+ * NULL parameter, a missing key is an error).
+ */
+function bindNamedParams(names, params) {
+    var missing = [];
+    var values = names.map(function (name) {
+        if (!Object.prototype.hasOwnProperty.call(params, name))
+            missing.push(name);
+        return params[name];
+    });
+    if (missing.length)
+        throw new Error('Missing value for named placeholder(s): ' + missing.join(', '));
+    return values;
+}

package/lib/types.d.ts

@@ -90,9 +90,21 @@ export type BatchOptions = {
     /** Rows per op_batch_msg packet (default 500). */
     chunkSize?: number;
 };
+/**
+ * Positional query parameters (array), or — when named placeholders are
+ * enabled via the `namedPlaceholders` connection/query option — values by
+ * placeholder name.
+ */
+export type QueryParams = any[] | Record<string, any>;
 export type QueryOptions = {
     timeout?: number;
     scrollable?: boolean;
+    /**
+     * Per-query override of the `namedPlaceholders` connection option
+     * (e.g. disable it for one EXECUTE BLOCK statement whose body uses
+     * `:variable` PSQL references).
+     */
+    namedPlaceholders?: boolean;
     /**
      * Abort the query when the signal fires (Firebird 2.5+ / protocol 12+).
      * If the signal is already aborted the query is not sent at all and the
@@ -107,11 +119,11 @@ export interface Database {
     detach(callback?: SimpleCallback): Database;
     transaction(options: TransactionOptions | Isolation | TransactionCallback, callback?: TransactionCallback): Database;
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): Database;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): Database;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): Database;
     /** Bulk-execute in its own transaction, all-or-nothing (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): Database;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    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;
     drop(callback: SimpleCallback): void;
     escape(value: any): string;
     attachEvent(callback: any): this;
@@ -119,10 +131,10 @@ export interface Database {
     alterTablespace(name: string, filePath: string, callback?: QueryCallback): Database;
     dropTablespace(name: string, callback?: QueryCallback): Database;
     createSchema(schemaName: string, tablespaceName?: string | QueryCallback, callback?: QueryCallback): Database;
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<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>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     transactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
     startTransactionAsync(options?: TransactionOptions | Isolation): Promise<Transaction>;
@@ -143,19 +155,19 @@ export interface Database {
 }
 export interface Transaction {
     newStatement(query: string, callback: (err: Error | null, statement: Statement) => void): void;
-    query(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
-    execute(query: string, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    query(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
+    execute(query: string, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     /** Bulk-execute within this transaction; per-record failures do not roll back (Firebird 4.0+). */
-    executeBatch(query: string, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
-    sequentially(query: string, params: any[], rowCallback: SequentialCallback, callback: SimpleCallback, options?: QueryOptions | boolean): Database;
+    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;
     commit(callback?: SimpleCallback): void;
     commitRetaining(callback?: SimpleCallback): void;
     rollback(callback?: SimpleCallback): void;
     rollbackRetaining(callback?: SimpleCallback): void;
-    queryAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeAsync<T = any>(query: string, params?: any[], options?: QueryOptions): Promise<T[]>;
-    executeBatchAsync(query: string, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
-    sequentiallyAsync(query: string, params: any[] | undefined, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
+    queryAsync<T = any>(query: string, params?: QueryParams, options?: QueryOptions): Promise<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>;
     sequentiallyAsync(query: string, rowCallback: SequentialCallback, options?: QueryOptions | boolean): Promise<void>;
     newStatementAsync(query: string): Promise<Statement>;
     commitAsync(): Promise<void>;
@@ -167,14 +179,14 @@ export interface Statement {
     close(callback?: SimpleCallback): void;
     drop(callback?: SimpleCallback): void;
     release(callback?: SimpleCallback): void;
-    execute(transaction: Transaction, params: any[], callback: QueryCallback, options?: QueryOptions): void;
+    execute(transaction: Transaction, params: QueryParams, callback: QueryCallback, options?: QueryOptions): void;
     fetch(transaction: Transaction, count: number, callback: QueryCallback): void;
     fetchScroll(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset: number, count: number, callback: QueryCallback): void;
     fetchAll(transaction: Transaction, callback: QueryCallback): void;
     /** Execute this prepared statement once per row (Firebird 4.0+ batch API). */
-    executeBatch(transaction: Transaction, rows: any[][], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
-    executeAsync(transaction: Transaction, params?: any[], options?: QueryOptions): Promise<any>;
-    executeBatchAsync(transaction: Transaction, rows: any[][], options?: BatchOptions): Promise<BatchResult>;
+    executeBatch(transaction: Transaction, rows: QueryParams[], callback?: (err: any, result: BatchResult) => void, options?: BatchOptions): void;
+    executeAsync(transaction: Transaction, params?: QueryParams, options?: QueryOptions): Promise<any>;
+    executeBatchAsync(transaction: Transaction, rows: QueryParams[], options?: BatchOptions): Promise<BatchResult>;
     fetchAsync(transaction: Transaction, count: number | 'all'): Promise<any>;
     fetchScrollAsync(transaction: Transaction, direction: 'NEXT' | 'PRIOR' | 'FIRST' | 'LAST' | 'ABSOLUTE' | 'RELATIVE' | number, offset?: number, count?: number): Promise<any>;
     fetchAllAsync(transaction: Transaction): Promise<any>;
@@ -209,6 +221,16 @@ export interface Options {
     blobReadChunkSize?: number;
     wireCrypt?: number;
     wireCompression?: boolean;
+    /**
+     * Enable named placeholders: SQL may use `:name` markers and params may
+     * be a values-by-name object (`db.query('... WHERE id = :id', { id: 1 })`).
+     * Placeholders are rewritten client-side to positional `?` before
+     * preparing; positional arrays keep working unchanged. Off by default
+     * because `EXECUTE BLOCK` bodies use `:variable` for PSQL references —
+     * with this option on, run such statements with positional params or a
+     * per-query `namedPlaceholders: false` override.
+     */
+    namedPlaceholders?: boolean;
     pluginName?: string;
     parallelWorkers?: number;
     maxInlineBlobSize?: number;

package/lib/uri.d.ts

@@ -0,0 +1,57 @@
+/***************************************
+ *
+ *   Connection URI strings
+ *
+ ***************************************/
+import type { Options } from './types';
+/**
+ * Parse a firebird:// connection URI into an options object.
+ *
+ *   firebird://user:password@host:port/database?option=value&...
+ *
+ * The database part:
+ *   firebird://host/employee              → alias "employee"
+ *   firebird://host//var/db/prod.fdb      → absolute path "/var/db/prod.fdb"
+ *   firebird://host/var/db/prod.fdb       → "/var/db/prod.fdb" (a database
+ *                                           part with slashes is a path —
+ *                                           aliases cannot contain "/")
+ *   firebird://host/C:/db/prod.fdb        → Windows path "C:/db/prod.fdb"
+ *
+ * Credentials and the database path are URL-decoded, so reserved characters
+ * can be percent-encoded (e.g. p%40ss for "p@ss"). Query parameters map
+ * 1:1 to option keys and are coerced to the option's type (booleans accept
+ * 1/true/yes/on). `user` and `password` may be given as query parameters
+ * instead of in the authority.
+ */
+export declare function parseConnectionUri(uri: string): Options;
+/**
+ * Parse a traditional ("old style") Firebird connection string:
+ *
+ *   [host[/port]:]{path | alias}
+ *
+ *   employee                              → alias "employee" (default host)
+ *   /var/fb/prod.fdb                      → local path (default host)
+ *   C:\fbdata\prod.fdb                    → Windows path — a single character
+ *                                           before ":" is a drive letter, not
+ *                                           a host (same rule as Firebird)
+ *   db.example.com:employee               → host + alias
+ *   db.example.com/3051:/var/fb/prod.fdb  → host + port + path
+ *   myserver:C:\fbdata\prod.fdb           → host + Windows path
+ *   [::1]/3050:employee                   → IPv6 host + port + alias
+ *
+ * Unlike firebird:// URIs, traditional strings carry no credentials or
+ * options — the driver defaults apply (SYSDBA/masterkey, port 3050).
+ * The port must be numeric; /etc/services names are not resolved.
+ */
+export declare function parseOldStyleConnectionString(str: string): Options;
+/**
+ * Parse any connection string the driver accepts: a firebird:// URI, or a
+ * traditional [host[/port]:]database string when there is no scheme.
+ */
+export declare function parseConnectionString(str: string): Options;
+/**
+ * Accept either an options object or a connection string (firebird:// URI
+ * or traditional host[/port]:database) everywhere options are taken.
+ * Strings are parsed; objects pass through unchanged.
+ */
+export declare function normalizeOptions<T>(options: T | string): T;