turbine-orm 0.81.0 → 0.90.0

package/dist/powdb-shared.js

@@ -220,16 +220,42 @@ function isTsSpace(code) {
         code === 0xfeff);
 }
 /**
- * Does this column map to PowDB's native `json` document type? A Postgres
+ * The labels of the enum type this column is declared as, or `undefined` when
+ * it is not an enum column of `enums`.
+ *
+ * An enum column carries its TYPE NAME as `dialectType` / `pgType` and a
+ * `tsType` that says nothing useful (`unknown` from `defineSchema`, a union of
+ * the labels from introspection), so the column's own metadata cannot answer
+ * the question: the schema's `enums` map is the only authority. PowDB has no
+ * enum type, so such a column is a `str` holding the label text, which is what
+ * PostgreSQL stores and returns. Without this the tsType heuristic in
+ * {@link isJsonColumn} declared a `defineSchema` enum column as `json`, and
+ * writing a label failed as invalid JSON.
+ */
+export function powdbEnumLabels(col, enums) {
+    if (!enums || col.isArray)
+        return undefined;
+    const type = col.dialectType ?? col.pgType;
+    return type !== undefined && Object.hasOwn(enums, type) ? enums[type] : undefined;
+}
+/**
+ * Does this column map to PowDB's native `json` document type? An enum column
+ * of `enums` never does (see {@link powdbEnumLabels}). A Postgres
  * `json`/`jsonb` type (via `dialectType`/`pgType`) is authoritative; otherwise
  * the tsType heuristic (`Record<…>`, `object`, `unknown`, an object/array
  * literal) that the four scalar branches do not claim. Array columns never map
  * to json, a PowDB array only exists INSIDE a json document, so a Postgres
  * array column has no PowDB shape and still throws in {@link powqlColumnType}.
+ *
+ * `enums` is optional for callers outside Turbine; every call inside the
+ * engine passes the schema's map (a source scan in fx-powdb-r2.test.ts
+ * checks it).
  */
-export function isJsonColumn(col) {
+export function isJsonColumn(col, enums) {
     if (col.isArray)
         return false;
+    if (powdbEnumLabels(col, enums))
+        return false;
     const dbType = (col.dialectType ?? col.pgType ?? '').toLowerCase();
     if (dbType === 'json' || dbType === 'jsonb')
         return true;
@@ -247,14 +273,17 @@ export function isJsonColumn(col) {
  *   - `Date` → `int` (epoch micros)   - `boolean` → `bool`
  *   - integral `number`/`bigint` → `int`   - fractional `number` → `float`
  *   - JSON / object columns → `json` (native PowDB document type, ≥ 0.12)
+ *   - an enum column of `enums` → `str` (the label text)
  *   - everything else (incl. UUID/PK strings) → `str`
  * Array (non-json) and bytes columns throw, they have no PowDB equivalent.
  */
-export function powqlColumnType(col) {
+export function powqlColumnType(col, enums) {
     if (col.isArray) {
         throw new ValidationError(`Column "${col.name}" is an array, PowDB has no array type. Arrays are unsupported on the PowDB backend.`);
     }
-    if (isJsonColumn(col))
+    if (powdbEnumLabels(col, enums))
+        return 'str';
+    if (isJsonColumn(col, enums))
         return 'json';
     const ts = baseTsType(col.tsType);
     if (ts === 'Date')
@@ -272,6 +301,23 @@ export function powqlColumnType(col) {
     }
     return 'str';
 }
+/**
+ * Is this a `numeric` / `decimal` / `money` column that PowDB stores as `str`?
+ *
+ * A Postgres-sourced decimal surfaces as a JS string (so its digits survive),
+ * and PowDB has no decimal type, so the column is DDL'd as PowQL `str`. Every
+ * comparison, ordering and aggregate the engine runs on it is then a TEXT
+ * operation, which is why the query generator refuses those on such a column.
+ */
+export function isPowdbDecimalTextColumn(col, enums) {
+    // An enum type's NAME is free text (`money_kind`), so an enum column is
+    // answered before the type-name match below can mistake it for a decimal.
+    if (powdbEnumLabels(col, enums))
+        return false;
+    if (col.isArray || isJsonColumn(col, enums) || baseTsType(col.tsType) !== 'string')
+        return false;
+    return /numeric|decimal|money/.test((col.dialectType ?? col.pgType ?? '').toLowerCase());
+}
 /** Heuristic: does this numeric column hold fractional values (→ PowQL `float`)? */
 function isFloatColumn(col) {
     const t = (col.dialectType ?? col.pgType ?? '').toLowerCase();
@@ -467,9 +513,12 @@ export function quotePowqlDotted(name) {
  * Every PowDB value arrives as a string; NULL arrives as the bareword `"null"`.
  * Metadata resolves the `"null"` ambiguity for nullable non-string columns.
  */
-export function coerceValue(raw, col) {
+export function coerceValue(raw, col, enums) {
+    // An enum column holds its label as text, read as a string column is.
+    if (powdbEnumLabels(col, enums))
+        return raw === 'null' && col.nullable ? null : raw;
     const ts = baseTsType(col.tsType);
-    const json = isJsonColumn(col);
+    const json = isJsonColumn(col, enums);
     // NULL bareword: unambiguous for non-string columns; for `str` we cannot tell a
     // literal "null" from SQL NULL, so a nullable str of value "null" reads as null.
     // For a `json` column the bareword `null` (a legacy-wire rendering shared by an
@@ -552,7 +601,7 @@ export function coerceNativeValue(value, col) {
  * cells arrive pre-typed and go through {@link coerceNativeValue} (see F3).
  * Callers on the native transport pass `this.pool.capabilities.nativeRaw`.
  */
-export function rowToEntity(raw, meta, native = false) {
+export function rowToEntity(raw, meta, native = false, enums) {
     const byName = new Map(meta.columns.map((c) => [c.name, c]));
     const out = {};
     for (const snake of Object.keys(raw)) {
@@ -565,8 +614,16 @@ export function rowToEntity(raw, meta, native = false) {
         else if (native) {
             out[field] = coerceNativeValue(value, col);
         }
+        else if (typeof value === 'string') {
+            out[field] = coerceValue(value, col, enums);
+        }
+        else if ((typeof value === 'number' || typeof value === 'bigint') && isDateColumn(col)) {
+            // A Date column's micros as a number cell: the Date it stores, as on the
+            // other wires, never the raw count (which a filter would then refuse).
+            out[field] = new Date(Number(value) / 1000);
+        }
         else {
-            out[field] = typeof value === 'string' ? coerceValue(value, col) : value;
+            out[field] = value;
         }
     }
     return out;

package/dist/powdb.d.ts

@@ -55,6 +55,7 @@
 import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
 import { type Dialect } from './dialect.js';
 import type { EngineClientConfig } from './engine-config.js';
+import { type TurbineLogger } from './logger.js';
 import type { PowdbExec } from './powdb-introspect.js';
 import { type PowdbCapabilities } from './powdb-shared.js';
 import { type SchemaMetadata } from './schema.js';
@@ -261,6 +262,8 @@ export declare function capabilitiesFromVersion(version: string | undefined | nu
  */
 export interface PowqlSchemaDDLOptions {
     capabilities?: PowdbCapabilities;
+    /** Where a skipped-link warning goes. Defaults to the console logger. */
+    logger?: TurbineLogger;
     /**
      * Emit `link Owner.name -> Target on local = target` declarations (PowDB entity
      * links, >= 0.19) for every single-column hasMany / hasOne / belongsTo relation
@@ -340,6 +343,7 @@ export declare function powqlSchemaDDL(schema: SchemaMetadata, opts?: PowqlSchem
  */
 export declare function applyPowdbLinks(exec: PowdbExec, schema: SchemaMetadata, options?: {
     capabilities?: PowdbCapabilities;
+    logger?: TurbineLogger;
 }): Promise<string[]>;
 /**
  * Translate a PowDB error into a typed Turbine error. Handles BOTH transports,

package/dist/powdb.js

@@ -56,6 +56,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
 import { ConnectionError, malformedConnectionStringMessage, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { consoleLogger, logTo } from './logger.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { ALL_POWDB_CAPABILITIES, atLeastVersion, isDateColumn, PowdbFloatParam, PowdbJsonParam, parsePowdbSemver, powqlColumnType, quotePowqlIdent, requireCapability, } from './powdb-shared.js';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
@@ -91,6 +92,48 @@ export { ALL_POWDB_CAPABILITIES, coerceNativeValue, coerceValue, isJsonColumn, i
 export const powdbDialect = {
     ...postgresDialect,
     name: 'powdb',
+    // PowqlInterface compiles PowQL itself and refuses what PowDB lacks; these
+    // answer for the client paths a PowDB client shares (transactions, raw
+    // queries, `tx.$connection()`) and keep every SQL-only feature off.
+    capabilities: Object.freeze({
+        distinctOn: false,
+        positionalJson: false,
+        nullsOrderingClause: false,
+        nullsSortHigh: false,
+        insensitiveInList: false,
+        jsonDocumentEquality: 'text',
+        jsonExtractTyped: false,
+        jsonExactNumericCast: false,
+        numericTextComparison: false,
+        // PowDB has no foreign keys: declared relations are not enforced, and its
+        // own mass-mutation guard already folds with foreignKeys: false.
+        enforcesForeignKeys: false,
+        partitionLimitPushdown: false,
+        utcTimestampRewrite: false,
+        paramTypeCasts: false,
+        namedEnumTypes: false,
+        structuredValueColumns: 'scalars',
+        maxBindParameters: Number.POSITIVE_INFINITY,
+        maxInsertRows: Number.POSITIVE_INFINITY,
+        upsertConflictTarget: 'explicit',
+        setClauseOrder: 'snapshot',
+        reselectLocksRows: false,
+        integerDivision: '/',
+        updateExpressions: false,
+        bulkUpsertAppliesRepeatedKeys: false,
+        readOnlyTransactions: false,
+        connectionParameters: false,
+        backendCancel: false,
+        idleTransactionTimeout: false,
+        abortsTransactionOnError: false,
+        connectionDriver: 'none',
+        preparesEveryStatement: false,
+        statementSyntax: null,
+        // No foreign keys to declare, inline or otherwise; PowQL DDL comes from
+        // powqlSchemaDDL, which never reads this.
+        inlineForeignKeys: false,
+        unboundedTextKeys: true,
+    }),
     // `resultStrategy` is decorative for PowDB, PowqlInterface owns its own write
     // path and never reads it. Set to 'returning' for honesty: writes use PowDB
     // 0.7.0's trailing `returning` keyword (upsert excepted, see PowqlInterface).
@@ -108,6 +151,11 @@ export const powdbDialect = {
     // earlier, this override keeps the flag truthful if a future path consults it.
     supportsLateralJoin: false,
     supportsPlanCacheMode: false,
+    // PowqlInterface reads none of these (it refuses each feature itself); they
+    // are set so the flags stay truthful if a shared path consults them.
+    rowLockModes: [],
+    supportsPercentileAggregates: false,
+    supportsBulkUpsert: false,
     beginStatement: () => 'begin',
     commitStatement: () => 'commit',
     rollbackStatement: () => 'rollback',
@@ -324,7 +372,7 @@ export function powqlSchemaDDL(schema, opts = {}) {
             new Set(idx.columns).size === pkSet.size &&
             idx.columns.every((c) => pkSet.has(c));
         const fields = meta.columns.map((col) => {
-            const powqlType = powqlColumnType(col);
+            const powqlType = powqlColumnType(col, schema.enums);
             // Gate `json` columns behind the engine's jsonDocs capability when a
             // caller supplied one, an old engine has no `json` type and would reject
             // the DDL. Pure-function callers (no opts) emit unconditionally.
@@ -409,8 +457,8 @@ export function powqlSchemaDDL(schema, opts = {}) {
             requireCapability(caps, 'entityLinks', 'entity link DDL (`emitLinks`)');
         const links = deriveDesiredLinks(schema, (owner, name) => {
             if (shouldWarnOnce(WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
-                console.warn(`[turbine] powqlSchemaDDL(emitLinks): relation "${name}" on "${owner}" collides with a column of the ` +
-                    'same name; skipping its link declaration (PowDB hard-errors on a link that shadows a column).');
+                logTo(opts.logger ?? consoleLogger, 'warn', `powqlSchemaDDL(emitLinks): relation "${name}" on "${owner}" collides with a column of the ` +
+                    'same name; skipping its link declaration (PowDB hard-errors on a link that shadows a column).', { code: 'powdb-link-collision', table: owner, relation: name, operation: 'powqlSchemaDDL' });
             }
         });
         for (const link of links)
@@ -438,6 +486,7 @@ export function powqlSchemaDDL(schema, opts = {}) {
  */
 export async function applyPowdbLinks(exec, schema, options = {}) {
     const caps = options.capabilities;
+    const logger = options.logger ?? consoleLogger;
     if (caps) {
         requireCapability(caps, 'entityLinks', 'entity link DDL (`applyPowdbLinks`)');
         requireCapability(caps, 'linkIntrospection', 'PowDB `schema links` introspection');
@@ -446,8 +495,8 @@ export async function applyPowdbLinks(exec, schema, options = {}) {
     const byOwnerName = new Map(existing.map((l) => [`${l.owner}\u0000${l.name}`, l]));
     const desired = deriveDesiredLinks(schema, (owner, name) => {
         if (shouldWarnOnce(WARN_NS.powdbLinks, `collide:${owner}.${name}`)) {
-            console.warn(`[turbine] applyPowdbLinks: relation "${name}" on "${owner}" collides with a column of the same name; ` +
-                'skipping its link (PowDB hard-errors on a link that shadows a column).');
+            logTo(logger, 'warn', `applyPowdbLinks: relation "${name}" on "${owner}" collides with a column of the same name; ` +
+                'skipping its link (PowDB hard-errors on a link that shadows a column).', { code: 'powdb-link-collision', table: owner, relation: name, operation: 'applyPowdbLinks' });
         }
     });
     const executed = [];
@@ -456,9 +505,9 @@ export async function applyPowdbLinks(exec, schema, options = {}) {
         if (found) {
             const same = found.target === link.target && found.localKey === link.localKey && found.targetKey === link.targetKey;
             if (!same && shouldWarnOnce(WARN_NS.powdbLinks, `drift:${link.owner}.${link.name}`)) {
-                console.warn(`[turbine] applyPowdbLinks: link "${link.name}" on "${link.owner}" is already declared with different ` +
+                logTo(logger, 'warn', `applyPowdbLinks: link "${link.name}" on "${link.owner}" is already declared with different ` +
                     `endpoints (have ${found.target} on ${found.localKey} = ${found.targetKey}, want ${link.target} on ` +
-                    `${link.localKey} = ${link.targetKey}); leaving it untouched (PowDB has no drop-link DDL).`);
+                    `${link.localKey} = ${link.targetKey}); leaving it untouched (PowDB has no drop-link DDL).`, { code: 'powdb-link-drift', table: link.owner, relation: link.name, operation: 'applyPowdbLinks' });
             }
             continue; // identical → idempotent skip; drift → warned skip
         }
@@ -704,7 +753,9 @@ export function wrapPowdbError(err) {
     // evaluate true for every row. Runs before the generic `type mismatch` regex
     // below so the column name and the fix survive into the message.
     {
-        const m = /type mismatch for column '([^']+)': expected ([^,]+), got (\w+)/i.exec(msg);
+        // Every group is bounded: `[^,]+` retried from each "expected " in a long
+        // message made this quadratic in the message length.
+        const m = /type mismatch for column '([^']{1,256})': expected ([^,]{1,64}), got (\w{1,32})/i.exec(msg);
         if (m) {
             return new ValidationError(`PowDB rejected a comparison on column "${m[1]}": the column is ${m[2]} but the bound value is ` +
                 `${m[3]}. PowQL never coerces across types in a comparison (before engine 0.20 this silently matched ` +
@@ -841,6 +892,19 @@ function reentrantTransactionError() {
         'on the write lock the open transaction holds. Use the `tx` client the callback receives, or start the ' +
         'second transaction after the first completes. (Independent concurrent transactions queue automatically.)');
 }
+/**
+ * The error for a plain statement issued through the CLIENT (not the `tx`
+ * client) from inside that client's own open transaction callback, on the
+ * embedded engine. Its one handle carries one transaction, so the statement
+ * could only run inside the transaction (and be rolled back with it) or wait
+ * for the transaction to finish, which is itself waiting on this statement.
+ */
+function statementInsideTransactionError() {
+    return new UnsupportedFeatureError('A statement on the client while its own transaction is open', 'powdb', 'This call was made through the client, not the `tx` client, from inside an open $transaction callback. The ' +
+        'embedded engine has one handle and one transaction, so the call would either join that transaction (and be ' +
+        'rolled back with it) or wait for it forever. Use the `tx` client the callback receives, or make the call ' +
+        'after the transaction completes.');
+}
 // ---------------------------------------------------------------------------
 // Single-writer transaction gate, FIFO queueing + re-entrancy detection
 // ---------------------------------------------------------------------------
@@ -911,9 +975,15 @@ class PowdbTxGate {
     queueTimeoutMs;
     /** Tail of the FIFO queue, resolves once every earlier transaction has finished. */
     tail = Promise.resolve();
+    /** Holds taken and not yet finished, queued ones included. */
+    outstanding = 0;
     constructor(queueTimeoutMs) {
         this.queueTimeoutMs = queueTimeoutMs;
     }
+    /** True while any transaction holds the gate or waits for it. */
+    get busy() {
+        return this.outstanding > 0;
+    }
     /**
      * Take a place in the transaction queue. The prologue walks the caller's
      * marker chain (planted around transaction callbacks by the pool's
@@ -922,7 +992,7 @@ class PowdbTxGate {
      * the returned hold carries the fresh marker (`hold.ctx`) for
      * `wrapTransactionCallback` to scope around the user callback.
      */
-    async acquire() {
+    async acquire(reentrantError = reentrantTransactionError) {
         // Walk the WHOLE marker chain, not just the innermost marker: with two
         // pools, dbA-tx → dbB-tx → dbA-begin leaves dbB's marker innermost, but
         // the dbA ancestor is still open, queueing the inner dbA begin behind it
@@ -935,7 +1005,7 @@ class PowdbTxGate {
             parent = parent.parent;
         for (let c = parent; c !== undefined; c = c.parent) {
             if (c.gate === this && !c.done) {
-                throw reentrantTransactionError();
+                throw reentrantError();
             }
         }
         const ctx = { gate: this, done: false, parent };
@@ -945,12 +1015,14 @@ class PowdbTxGate {
         });
         const ahead = this.tail;
         this.tail = ahead.then(() => finished);
+        this.outstanding++;
         const hold = {
             ctx,
             finish: () => {
                 if (ctx.done)
                     return;
                 ctx.done = true;
+                this.outstanding--;
                 handOff();
             },
         };
@@ -1608,6 +1680,30 @@ export class PowdbEmbeddedPool {
                 throw new ConnectionError('The PowDB embedded pool is closed: disconnect() was already called on this client.');
             }
         }
+        if (ctl === null && holdRef.hold === null && this.txGate.busy) {
+            // A statement from OUTSIDE the open transaction. The engine is one
+            // handle, so running it now would put it inside that transaction: it
+            // would read uncommitted rows, and a write would be rolled back with the
+            // transaction after being reported as done. It takes its FIFO turn on the
+            // gate instead, as a one-statement transaction of its own would. From
+            // inside the transaction's own callback that wait could never end, so the
+            // gate refuses it there.
+            const hold = await this.txGate.acquire(statementInsideTransactionError);
+            try {
+                if (this.closed) {
+                    throw new ConnectionError('The PowDB embedded pool is closed: disconnect() was already called on this client.');
+                }
+                try {
+                    return this.exec(powql, params);
+                }
+                catch (err) {
+                    throw wrapPowdbError(err);
+                }
+            }
+            finally {
+                hold.finish();
+            }
+        }
         if ((ctl === 'commit' || ctl === 'rollback') && holdRef.hold === null) {
             // This context never acquired the gate, its `begin` never ran (the
             // gate timed out / threw re-entrant E017, or no begin was issued at
@@ -1799,25 +1895,52 @@ async function openEmbeddedPool(target, poolOptions = {}, assumeEngineVersion, i
             throw err;
         throw new ConnectionError(`PowDB embedded could not open data dir "${dir}": ${err.message}`);
     }
-    if (syncMode !== undefined) {
-        if (typeof db.setSyncMode !== 'function') {
-            throw new ConnectionError('embedded `syncMode` requires @zvndev/powdb-embedded ≥ 0.7.1 (the installed addon has no setSyncMode).');
+    try {
+        if (syncMode !== undefined) {
+            if (typeof db.setSyncMode !== 'function') {
+                throw new ConnectionError('embedded `syncMode` requires @zvndev/powdb-embedded ≥ 0.7.1 (the installed addon has no setSyncMode).');
+            }
+            db.setSyncMode(syncMode);
+        }
+        // Native typed wire is feature-detected on the OPENED handle: an addon ≥ 0.14
+        // exposes `queryWithParams`, so nativeRaw turns on (server-gate ≥ 0.13 still
+        // applies via the version); an older addon has no such method → false.
+        const capabilities = capabilitiesFromVersion(assumeEngineVersion ?? resolveEmbeddedVersion(), {
+            hasNativeRaw: typeof db.queryWithParams === 'function',
+        });
+        // A read-only target forces the pool's readonly flag; otherwise honor whatever
+        // `poolOptions` (threaded from `options.readonly`) carried.
+        return new PowdbEmbeddedPool(db, {
+            ...poolOptions,
+            capabilities,
+            readonly: Boolean(readonly) || Boolean(poolOptions.readonly),
+        });
+    }
+    catch (err) {
+        // The caller never receives this handle, so nothing else can close it.
+        try {
+            db.close?.();
+        }
+        catch {
+            // The failure being reported is the useful one.
         }
-        db.setSyncMode(syncMode);
+        throw err;
+    }
+}
+/**
+ * Probe a networked pool Turbine just built and wrap it. The pool is closed
+ * when the probe or the wrapper refuses, because the caller never sees it
+ * and its idle sockets would otherwise keep the process alive.
+ */
+async function wrapOwnedClientPool(clientPool, poolOptions, assumeEngineVersion) {
+    try {
+        const capabilities = await assertNetworkedVersion(clientPool, assumeEngineVersion);
+        return new PowdbPool(clientPool, undefined, { ...poolOptions, capabilities });
+    }
+    catch (err) {
+        await clientPool.close().catch(() => { });
+        throw err;
     }
-    // Native typed wire is feature-detected on the OPENED handle: an addon ≥ 0.14
-    // exposes `queryWithParams`, so nativeRaw turns on (server-gate ≥ 0.13 still
-    // applies via the version); an older addon has no such method → false.
-    const capabilities = capabilitiesFromVersion(assumeEngineVersion ?? resolveEmbeddedVersion(), {
-        hasNativeRaw: typeof db.queryWithParams === 'function',
-    });
-    // A read-only target forces the pool's readonly flag; otherwise honor whatever
-    // `poolOptions` (threaded from `options.readonly`) carried.
-    return new PowdbEmbeddedPool(db, {
-        ...poolOptions,
-        capabilities,
-        readonly: Boolean(readonly) || Boolean(poolOptions.readonly),
-    });
 }
 /**
  * Bind Turbine to PowDB. `target` is one of:
@@ -1848,9 +1971,7 @@ export async function turbinePowDB(target, schema, options = {}) {
     const max = options.connectionLimit ?? 10;
     if (typeof target === 'string') {
         const mod = options.powdbClientModule ?? (await loadPowdb());
-        const clientPool = new mod.Pool({ ...parsePowdbUrl(target), max });
-        const capabilities = await assertNetworkedVersion(clientPool, options.assumeEngineVersion);
-        pool = new PowdbPool(clientPool, undefined, { ...poolOptions, capabilities });
+        pool = await wrapOwnedClientPool(new mod.Pool({ ...parsePowdbUrl(target), max }), poolOptions, options.assumeEngineVersion);
         owns = true;
     }
     else if (target instanceof PowdbPool) {
@@ -1870,26 +1991,36 @@ export async function turbinePowDB(target, schema, options = {}) {
     }
     else {
         const mod = options.powdbClientModule ?? (await loadPowdb());
-        const clientPool = new mod.Pool({ ...target, max });
-        const capabilities = await assertNetworkedVersion(clientPool, options.assumeEngineVersion);
-        pool = new PowdbPool(clientPool, undefined, { ...poolOptions, capabilities });
+        pool = await wrapOwnedClientPool(new mod.Pool({ ...target, max }), poolOptions, options.assumeEngineVersion);
         owns = true;
     }
-    // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
-    const { PowqlInterface } = await import('./powql.js');
-    const queryInterfaceFactory = (p, table, sch, middlewares, opts) => new PowqlInterface(p, table, sch, middlewares, opts);
-    // Forward every client-level option EXCEPT the ones this factory owns (they
-    // configure the pool / transport above, and TurbineClient warns on a config
-    // key it does not recognize). Destructured rather than hand-listed on the way
-    // IN: an allowlist is how `globalFilters` came to be accepted and ignored.
-    const { connectionLimit: _connectionLimit, transactionQueueTimeoutMs: _transactionQueueTimeoutMs, retryStaleReads: _retryStaleReads, assumeEngineVersion: _assumeEngineVersion, readonly: _readonly, powdbClientModule: _powdbClientModule, powdbEmbeddedModule: _powdbEmbeddedModule, ...clientConfig } = options;
-    const client = new TurbineClient({
-        ...clientConfig,
-        pool,
-        preparedStatements: false,
-        dialect: powdbDialect,
-        queryInterfaceFactory,
-    }, schema);
+    let client;
+    try {
+        // The PowQL generator is loaded here to keep client.ts free of any PowDB import.
+        const { PowqlInterface } = await import('./powql.js');
+        const queryInterfaceFactory = (p, table, sch, middlewares, opts) => new PowqlInterface(p, table, sch, middlewares, opts);
+        // Forward every client-level option EXCEPT the ones this factory owns (they
+        // configure the pool / transport above, and TurbineClient warns on a config
+        // key it does not recognize). Destructured rather than hand-listed on the way
+        // IN: an allowlist is how `globalFilters` came to be accepted and ignored.
+        const { connectionLimit: _connectionLimit, transactionQueueTimeoutMs: _transactionQueueTimeoutMs, retryStaleReads: _retryStaleReads, assumeEngineVersion: _assumeEngineVersion, readonly: _readonly, powdbClientModule: _powdbClientModule, powdbEmbeddedModule: _powdbEmbeddedModule, ...clientConfig } = options;
+        client = new TurbineClient({
+            ...clientConfig,
+            pool,
+            preparedStatements: false,
+            dialect: powdbDialect,
+            queryInterfaceFactory,
+        }, schema);
+    }
+    catch (err) {
+        // A failed factory hands the caller nothing to close, so a pool or embedded
+        // handle it BUILT is closed here (the client constructor refuses a bad
+        // config, a static global filter naming no table for one). A pool the
+        // caller supplied is the caller's and stays open.
+        if (owns)
+            await pool.end().catch(() => { });
+        throw err;
+    }
     if (owns) {
         // Turbine built this pool / embedded handle, so disconnect()/end() must
         // close it. client.ts sees TurbineConfig.pool as EXTERNAL (ownsPool =
@@ -1898,9 +2029,10 @@ export async function turbinePowDB(target, schema, options = {}) {
         // open until powdb-server's idle timeout (~300s) closed them. Consistent
         // with turbineMssql's owned-pool patch.
         const baseDisconnect = client.disconnect.bind(client);
-        const close = async () => {
-            await baseDisconnect();
+        const close = async (options) => {
+            const result = options === undefined ? await baseDisconnect() : await baseDisconnect(options);
             await pool.end();
+            return result ?? undefined;
         };
         const patch = client;
         patch.disconnect = close;
@@ -1908,7 +2040,7 @@ export async function turbinePowDB(target, schema, options = {}) {
     }
     else {
         // Injected pool, the caller owns its lifecycle.
-        client.disconnect = async () => { };
+        client.disconnect = async (options) => (options === undefined ? undefined : { timedOut: false, forcedConnections: 0 });
     }
     return client;
 }