node-firebird 2.8.1 → 2.10.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, 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,14 +175,80 @@ 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.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
+
+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 +452,174 @@ 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 });
+```
+
+### 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.
@@ -919,6 +1154,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
@@ -1657,13 +1912,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
 
@@ -1720,6 +1975,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

@@ -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';
@@ -23,20 +24,27 @@ 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
  * 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.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;
@@ -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; } });
@@ -60,7 +63,37 @@ 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;
     var port = options.port || const_1.default.DEFAULT_PORT;
     var manager = options.manager || false;
@@ -83,7 +116,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 +125,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 +146,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) {
@@ -129,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;
                 }
@@ -139,8 +176,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/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) {